Creating a Site Column with Managed Metadata using JavaScript

A while ago now, and one of my popular blog posts I created a post called Creating a Site Column with Managed Metadata. this showed you how to create a Managed Metadata Site Column and tie it up to a Term Set. With the use of feature activate events hooking up the site column the Term Set was easily achieved.

With SharePoint Online, using a Sandbox solution we are unable to use any C# code. Therefore we are left to use JavaScript to tie up the column and the TermSet. In this blog post I will walk through creating a Managed Metadata column and using a custom configuration page to get the Managed Metadata column working.
First thing you will need to do, is ensure you have a term set created in your environment. As you can see below I have created a group calledCannonfodder with a term set call Countries. Take note of the Unique Identifier of your term set you will require this later on in the code. You might not want to hard code this value into your code, which is understandable if you are going from one environment to another. You could just use the name of your term set, but if you have the same name in different groups you might encounter unexpected results. A solution to this issue would be to ensure you export and import Taxonomy Term Store Groups from one environment to another, as this would retain the Unique Identifier. My next blog post is about this.

Here we are going to walk through creating a Sandbox solution, creating a Managed Metadata column via a feature, then we are going to build upon it to create a list definition and list instance.

Open Visual Studio, and create a new Empty SharePoint ProjectName the project ManagedMetadataSB.
Use your SharePoint Site for debugging, I’m using the Development Site in 365, and Deploy as a Sandbox Solution.

Creating Site Column.

In Solution Explorer right click your project and select Add -> New Item.
Add a Site Column. I’ve named my Column CO_Column. This will also create a Feature for you.
Open the Elements.xml file and add the following to create 2 fields. The first field is of type Note field, this is a hidden field that contains a reference to the actual term in the term set that was selected, and this is required for each Managed Metadata Column. You must always put the note field first. The reason behind this is, when SharePoint reads in the XML, if it reads the Taxonomy Field first, it will automatically create the notes field for you, which you will not know the GUID, or have any control over the internal name etc. The second field is of type TaxonomyFieldType is the actual field we are trying to create (TaxonomyFieldTypeMulti for multiple selection, don’t forget to add Multi = True to the element field too). The Show Field will always point to Term1033 for any Managed Metadata Column. You will need to also include the Customization section. This will be identical for every Managed Metadata Column you create, except the Guid which is the same GUID ID of the Note Hidden Field ID.

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

 <Field

 ID="{8228CEF8-3021-4CD9-82F2-36CC027E52AA}"

 Type="Note"

 DisplayName="CF_SBCountryTax_0"

 StaticName="CF_SBCountryTax_0"

 Name="CF_SBCountryTax_0"

 ShowInViewForms="FALSE"

 Required="FALSE"

 Hidden="TRUE"

 CanToggleHidden="TRUE"

 Overwrite="TRUE"

 Group="Cannonfodder"

 xmlns="http://schemas.microsoft.com/sharepoint/">

 </Field>

 <Field Type="TaxonomyFieldType"

 DisplayName="Country"

 Description="Country List"

 List="Lists/TaxonomyHiddenList"

 WebId="~sitecollection"

 ShowField="Term1033"

 Required="FALSE"

 EnforceUniqueValues="FALSE"

 Group="Cannonfodder"

 ID="{3F937DB0-4D86-4EE5-B553-07AC64B070BB}"

 StaticName="CF_SBCountry"

 Name="CF_SBCountry"

 Overwrite="TRUE"

 xmlns="http://schemas.microsoft.com/sharepoint/">

 <Customization>

 <ArrayOfProperty>

 <Property>

 <Name>TextField</Name>

 <Value xmlns:q6="http://www.w3.org/2001/XMLSchema"

 p4:type="q6:string"

 xmlns:p4="http://www.w3.org/2001/XMLSchema-instance">{8228CEF8-3021-4CD9-82F2-36CC027E52AA}</Value>

 </Property>

 </ArrayOfProperty>

 </Customization>

 </Field>

</Elements>

Creating Content Type.

Right click your project and select Add -> New Item.
Add a Content Type. I’ve named mine CT_Document Location and
inherit from Document content type.
In the GUI added both your TaxonomyField and your Note field. Also include two additional fields Taxonomy Catch All Column (TaxCatchAll) and Taxonomy Catch All Column 1 (TaxCatchAllLabel) . The TaxCatchAll and TaxCatchAllLabel columns are lookup fields pointing to the special hidden list in the site collection (TaxonomyHiddenList). They point to the CatachAllData and CatachAllDataLabel fields in the hidden list and are used within each list that has a column of type Managed Metadata.

Give your Content type a name, description and Group.

Create your List Definition

Right click your project and select Add -> New Item.
Add List. Give your list a name, I’ve named mine Reference Document and Create a Customizable list based onDocument Library, and Use a standard document template for this library.
On the GUI, Click the Content Types button.
Add your content type to the Content Type Settings box. At this point I always Click OK. Then reopen the Content Type Settings box to set the default. If I don’t close the dialog after adding my content type, I find when I try to set it as default Visual Studio sometimes removes items/properties I don’t expect it to. After setting my Content Type to default, I removeDocument to ensure only my one will appear, select the row and press the delete key.

After click OK to the Content Type Settings dialog, you will find your columns from your content type will be added to the Columns in the GUI.
If you select the Views tab, you will see that your managed metadata column will be in the default view.
If you select the List tab, you can update the Title, List Url, and Description if you want.

Event Receivers

With Taxonomy we need to add event receivers on item adding and item updating. The events are SharePoint Taxonomy events, and they ensure the hidden columns are updated whenever the vales within the Managed Metadata column changes.

Right click your project and select Add -> New Item.
Add Empty Element. Put the following XML. Remember to put the ListTemplateId equals to the List Definition Type. This can be found by viewing the Elements.xml file for the List Definition.

<Name>TaxonomyItemSynchronousAddedEventReceiver</Name>

<Synchronization>Synchronous</Synchronization>

<Type>ItemAdding</Type>

<Assembly>Microsoft.SharePoint.Taxonomy, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c</Assembly>

<Class>Microsoft.SharePoint.Taxonomy.TaxonomyItemEventReceiver</Class>

</Receiver>

<Name>TaxonomyItemUpdatingEventReceiver</Name>

<Synchronization>Synchronous</Synchronization>

<Type>ItemUpdating</Type>

<Assembly>Microsoft.SharePoint.Taxonomy, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c</Assembly>

<Class>Microsoft.SharePoint.Taxonomy.TaxonomyItemEventReceiver</Class>

</Receiver>

</Receivers>

</Elements>

Features

One of the gotcha’s I have experience in the past is that when you create a list instance with Managed Metadata and you put both the Definition and the Instance within the same feature, the list instance doesn’t get instantiated. Therefore add a new feature to the Features folder.

Set one feature to Site and name it Site – Assets. Set the other feature to Web and name it Web – Assets.
In the Site feature, add your Column, Content Type and List Definition.
In the Web feature, add your List instance, and Event Receiver.
Grab the ID of your Site Feature (Where your list Definition is), and add the ID to your List Instance.

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

 <ListInstance Title="Reference Document Sandbox"

 OnQuickLaunch="TRUE"

 TemplateType="10001"

 FeatureId="[GUID of Site Feature of List Definition]"

 Url="Lists/SBReferenceDocument"

 Description="My List Instance">

 </ListInstance>

</Elements>

If you deploy now you will find that nothing ties up. Your column, content type and list will exist, but it will not be connected to the Term Set. Easiest way to prove this:

Goto your Reference Document Library.
Upload a document.
You will notice that the Country/Managed Metadata Field is greyed out.

This is where the JavaScript file comes in. Really, ideally, you would want this script to run as a configuration script that would run when an admin user hits the page, perhaps more configuration stuff will happen, such as setting default content types, branding, setting up navigation etc, this would be somehow tied into the master page, or inserted by a custom action link. In this demo I will show you a configuration page, which you could also extend. If the configuration hasn’t been ‘configured’ then every user would redirect to this page until the configuration has been complete. For now this is just a demo, and a simple page with a config button will be enough to explain how to connect the Manage metadata column to the term set.

JavaScript, Property Bag and configuration page.

I’m going to add a simple aspx page to my solution. HTML and JavaScript will be self-contained within this page for simplicity, but in a live environment, you would probably separate them out.

Right click on the project and add Module. Name this Assets.
Right click Manage NuGet Packages… It is a much easier way of adding libraries such as Knockout, JQuery and Underscore etc.
Search for JQuery, and Underscore and add them to the solution.
Now move this Javascript files and put them within the Assets module in a folder called Scripts.
The elements file for the module, make sure that all <File> have ReplaceContent=”True”. This ensures any update to the files will be successfully updated over.
Right click on the project and add Module. Name thisConfigurationPage.
Rename the .txt file to Config.aspx
Change the text within the text file to the following. This is a typical test start page. It will inherit your master page, and be a basic page so that you can add JavaScript/HTML.

<%@ Assembly Name="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

<%@ Import Namespace="Microsoft.SharePoint.WebPartPages" %>

<%@ Register TagPrefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

<%@ Register TagPrefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

<%@ Import Namespace="Microsoft.SharePoint" %>

<%@ Assembly Name="Microsoft.Web.CommandUI, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

<%@ Register TagPrefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

<%@ Page Language="C#" MasterPageFile="~masterurl/default.master" Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage,Microsoft.SharePoint,Version=15.0.0.0,Culture=neutral,PublicKeyToken=71e9bce111e9429c" EnableViewState="false" meta:webpartpageexpansion="full" meta:progid="SharePoint.WebPartPage.Document" %>

<asp:Content ID="Content1" ContentPlaceHolderID="PlaceHolderAdditionalPageHead" runat="server" >

</asp:Content>

<asp:Content ID="Content2" ContentPlaceHolderID="PlaceHolderPageTitleInTitleArea" runat="server">

 Configuration Page

</asp:Content>

<asp:Content ID="Content3" ContentPlaceHolderID="PlaceHolderSearchArea" runat="server" />

<asp:Content ID="Content4" ContentPlaceHolderID="PlaceHolderMain" runat="server">

 <SharePoint:FormDigest ID="FormDigest1" runat="server"/>

</asp:Content>

Within the ContentID=”Content4″ under the SharePoint:FormDigestadd the following HTML.

<div id="outerContainer" style="display:none">

<div class="cellOuter">

 <div class="inner">Taxonomy Fields Configured</div>

 <div class="inner"><span id="taxConfigured" class="cross"></span></div>

 </div>

 <div class="cellOuter">

 <div class="inner"></div>

 <div class="inner"></div>

 </div>

 <div class="cellOuter">

 <div class="inner"></div>

 <div class="buttons">

 <input class="configButton" type="button" title="Configure Site" name="Run Configuration" onclick="CF.SiteConfiguration.Provisioning.Execute();" value="Configure Site" />

 </div>

 </div>

</div>

<div id="error" style="display:none">

 There has been an error. Unable to configure this site at this time.

</div>

The above HTML is a simple table that displays the configuration item, in this case “Taxonomy Configuration” and a button, that when pressed it will call our JavaScript we are yet to write. I’m using class “Tick” and “Cross” to display an icon to inform the user if Taxonomy is already been configured or not. At this point lets create our CSS that this page will use.
Within the Assets Module create a folder called CSS and add a style sheet. I’ve called mine CF.css
Put the following CSS code. This enough css to create a table like format, and will display a cross or a tick depending on the class used. If you download the solution at the bottom of this blog post you will be able to use the same jpeg files as me for the Cross and Tick. Add these to your Assets Module under a folder called Images.

.cross{

background:#fff url(../../assets/images/cross.jpg) no-repeat right center;

display:block;

height:24px;

width:24px;

float:right

}

.tick{

background:#fff url(../../assets/images/tick.jpg) no-repeat right center;

display:block;

height:24px;

width:24px;

float:right;

}

#outerContainer{display:table}

.cellOuter{display:table-row}

.inner{display:table-cell;width:50%;}

.buttons{display:table-cell;float:right;margin-top:20px;margin-r

To ensure that this code can only run once, I have created a property bag item called TaxonomyFieldsConfigured and set the value to false. The JavaScript will change this to True once the Site column has been configured.
To create the Property Bag item, right click the project and select Add -> New Item.
Select Empty Elements. Give it the name of PB_Config.
We want our property bag to just be on the Site Collection (Root Web), as the Site Column will only be configured at the Root Web. Within the Elements.xml file of PB_Config put the following. This will create a property bag value called TaxonomyFieldsConfigured.

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

 <PropertyBag ParentType="Web" RootWebOnly="TRUE">

 <Property Name="TaxonomyFieldsConfigured" Value="false" Type="string"/>

 </PropertyBag>

</Elements>

Going back to the Config.aspx we need to add the following reference to JQuery.js, Underscore.js and our CSS. Within theContentPlaceHolderID=”PlaceHolderAdditionalPageHead” add the following.

The above will ensure that JQuery, UnderScore (used for array handling) and the CSS will be loaded on the page.
Underneath the above code within thePlaceHolderAdditionalPageHead the following JavaScript will do the following: (Comments within the code to explain each step).
- Check On Load of the page if the Taxonomy Configuration has already taken place.
  - If it has, by checking the property bag, it will disable the Config button to prevent configuration from happening again, it will also update the page to the user to show that configuration has already taken place by showing a tick next to the Taxonomy Configuration text.
  - If it hasn’t, by checking the property bag, the code will display the config button, and indicate to the user that the configuration hasn’t taken place yet.
- On Click of the Config button, it will load relevant required SharePoint Javascript libraries, such as SP.Taxonomy.js before calling the relevant code to tie up the column with the Term Set. On successful update it will then update the property bag and disable the Config button to prevent the user from running the code a second time.
- As stated at the start of my blog, you could find the TermSet name by Name instead of ID, this will allow you to move this code through environments without needing to import and export your termsets with the code. The below JavaScript doesn’t show this, as I use TermSet ID. The downside of using Name instead of ID is that you could have two groups with the same TermSet name, meaning you might grab the wrong one. Also you would need to obtain all TermSet names and loop through them looking for a match to grab the TermSetID, this would be additional call to SharePoint.

//Create NameSpace

var CF = CF || {};

CF.SiteConfiguration = CF.SiteConfiguration || {};

CF.Data = CF.Data || {};

//On Load function calls the Provision Load Function

//This will check to see if the Configuration has already taken place.

CF.onLoadFunction = function () {

CF.SiteConfiguration.Provisioning.Load();

}

//A Constant that contains the Property Bag Value. This allows the code to get/set the value.

CF.Data.Constants = {

CFTaxonomyFieldConfigured: "TaxonomyFieldsConfigured"

}

//ID contains the Term Set Id, Name contains the internal name of the Site Column.

//This is written as an array, therefore if there is more that one Site Column to connect, you just need to add more Id's/Name's for this to work.

CF.Data.TaxonomyFields = [

{ Id: '69c09582-e13d-4662-a675-abee73995586', Name: 'CF_SBCountry' }

];

//Provisioning Code, self contained variables and functions.

CF.SiteConfiguration.Provisioning = function () {

var ctx,

web,

properties,

currentDlg,

dlgTitle,

dlgMsg,

dlgWidth,

dlgHeight;

//Load function, gets all web properties.

var load = function () {

ctx = SP.ClientContext.get_current();

web = ctx.get_web();

properties = web.get_allProperties();

ctx.load(web);

ctx.load(properties);

ctx.executeQueryAsync(onLoadSuccess, onFailedCallback);

};

//On Success of getting web Properties.

var onLoadSuccess = function () {

var allProps = properties.get_fieldValues();

var taxConfigured;

//Success, so show Configuration Grid.

jQuery("#outerContainer").show();

//Check if property bag of Taxonomy Field Exists.

if (allProps[CF.Data.Constants.CFTaxonomyFieldConfigured] != null) {

taxConfigured = properties.get_item(CF.Data.Constants.CFTaxonomyFieldConfigured);

}

else {

//If doesn't exist then show that it's configured, and disable button.

jQuery("#taxConfigured").removeClass("cross").addClass("tick");

jQuery(".configButton").attr("disabled", "disabled");

return;

}

//Property bag value found.

if (taxConfigured == "true") {

//If true, already been configured. Update screen for user.

jQuery("#taxConfigured").removeClass("cross").addClass("tick");

jQuery(".configButton").attr("disabled", "disabled");

}

};

//Error handler.

var onFailedCallback = function (sender, args) {

// Timeout on dialog for demo purposes so you can see it, you wouldn't put this in your code.

setTimeout(function () {

if (currentDlg != null) {

//Close dialog if exists.

currentDlg.close();

}

//Display an error message to user that there is an issue.

var errorStatus = SP.UI.Status.addStatus("Error", "There has been a problem configuring this site. " + args.get_message(), true);

SP.UI.Status.setStatusPriColor(errorStatus, "red");

//Hide the Configuration Table to user.

jQuery("#outerContainer").hide();

//Show Error message.

jQuery("#error").show();

}, 4000);

};

//Function to configure, title, message, height and width of pop up dialog.

var configureDlg = function (title, message, height, width) {

if (currentDlg != null) {

currentDlg.close();

}

dlgTitle = title;

dlgMsg = message;

dlgHeight = height;

dlgWidth = width;

currentDlg = SP.UI.ModalDialog.showWaitScreenWithNoClose(dlgTitle, dlgMsg, dlgHeight, dlgWidth);

};

//Callback if Connecting Taxonomy is successful.

var taxonomySuccessCallBack = function () {

setTimeout(function () {

if (currentDlg != null) {

currentDlg.close();

}

jQuery("#taxConfigured").removeClass("cross").addClass("tick");

jQuery(".configButton").attr("disabled", "disabled");

}, 4000);

};

//Utility to update the property bag. Passing in the Property Key, Value to update to, Success and Failure callback.

var updatePropertyBag = function (key, value, successCallback, failedCallback) {

ctx = SP.ClientContext.get_current();

properties = ctx.get_web().get_allProperties();

properties.set_item(key, value);

ctx.get_web().update();

ctx.load(properties);

ctx.executeQueryAsync(successCallback, failedCallback);

};

//Check to see if there is any Taxonomy Fields to configure.

var configureTaxonomyFields = function (successCallBack, failedCallback) {

ctx = SP.ClientContext.get_current();

var fieldNames;

if (CF.Data.TaxonomyFields == null || CF.Data.TaxonomyFields.length == 0) {

successCallBack();

return;

}

//There are fields to configure call the function.

connectMMFieldsToSP(CF.Data.TaxonomyFields, successCallBack, failedCallback);

};

//Main code that connects the Site columns to the Term sets.

var connectMMFieldsToSP = function (taxFields, success, failed) {

ctx = SP.ClientContext.get_current();

//load the termstore.

var termStore = SP.Taxonomy.TaxonomySession.getTaxonomySession(ctx).getDefaultKeywordsTermStore();

ctx.load(termStore);

//Using underscore, loop through each site column and load them to modify.

_.each(taxFields, function (current) {

var field = ctx.get_site().get_rootWeb().get_fields().getByInternalNameOrTitle(current.Name);

ctx.load(field);

});

//Call query to get given field Site columns

ctx.executeQueryAsync(function () {

//Using Underscore to loop through all site columns again now loaded, and update with TermStore ID and TermSet.

_.each(taxFields, function (current) {

var field = ctx.get_site().get_rootWeb().get_fields().getByInternalNameOrTitle(current.Name);

var taxField = ctx.castTo(field, SP.Taxonomy.TaxonomyField);

taxField.set_sspId(termStore.get_id().toString());

taxField.set_termSetId(current.Id.toString().toUpperCase());

taxField.updateAndPushChanges(true);

});

//Execute Changes.

ctx.executeQueryAsync(success, failed);

failed);

};

//Init function that will load the Taxonomy.js on the page first, followed by calling code to tie up the Columns to Term Sets, lastly it will update the Property bag to prevent code running again.

var init = function () {

SP.SOD.registerSod('sp.taxonomy.js', SP.Utilities.Utility.getLayoutsPageUrl('sp.taxonomy.js'));

SP.SOD.executeFunc('sp.taxonomy.js', 'SP.Taxonomy.TaxonomySession', function () {

configureDlg("Configuring Taxonomy on your site...", "</br>Please wait</br></br>;Please do not close your browser window.", 300, 1000);

configureTaxonomyFields(updatePropertyBag(CF.Data.Constants.CFTaxonomyFieldConfigured, "true", taxonomySuccessCallBack, onFailedCallback), onFailedCallback);

});

};

return {

Execute: init,

Load: load

}

}();

//After all SharePoint code has run, it will call the onLoadFunction.

_spBodyOnLoadFunctionNames.push("CF.onLoadFunction");

</script>

Assets Element file.

I’ve mentioned in this post add stuff to the Assets module but haven’t actually shown you the final Elements.xml file. Within my Asset file I have put css, images, and Scripts within separate folders. (You may have noticed this from declaring Scripts and CSS link in the PalceHolderAdditonalPageHead of the Config.aspx page). Here is my final Elements.xml file.

Updating the Features.

With the new modules/elements/pages since last time I told you to deploy, you will need to update the features.

In the Site feature, you should now have Column, Content Type, List Definition, and Assets Module.
In the Web feature, you should now have List instance, and Event Receiver, Configuration Page and Property Bag.

Deploy

You can now deploy your solution to your SharePoint site. Either using Visual Studio or publishing your solution and uploading you WSP.

Once deployed, ensure that both your Site and Web features are both activated then navigate to your Config.aspx page. (e.g.https://%5BYour365Site%5D.sharepoint.com/config.aspx)

As you can see from above, the first time you hit the page, it has already done a check to see if the property bag value “TaxonomyFieldsConfigured” has been set to true. The value has equalled false as we haven’t configured yet and the Configure Site button is enabled.

By clicking the Configure Site button our Configuring Dialog will appear while the JavaScript runs.

Once complete the Taxonomy Fields Configured task will be updated with a “Tick” and the Configure Site will be disabled. Even if you refresh the page, you won’t be able to run the Configure Site button again.

If you now navigate to your list instance, in my case “Reference Document Sandbox” and upload a document, the managed metadata column will now be available for editing.

SharePointRockzz

Saturday, 20 February 2016

Update – Creating a Site Column with Managed Metadata using Javascript.

Creating a Site Column with Managed Metadata using JavaScript

Creating Site Column.

Creating Content Type.

Create your List Definition

Event Receivers

Features

JavaScript, Property Bag and configuration page.

Assets Element file.

Updating the Features.

Deploy