January 23, 2013

Using SharePoint TaxonomyWebTaggingControl control: Access and manipulate from client side

19 Comments

Overview

In previous post we’ve discussed one of the useful features for TaxonomyWebTaggingControl control that allows to specify ID of parent Term for any valid value in control. This could improve user experience in cases when subset of terms should be displayed for selection based on some conditions instead of displaying all terms from term set.

This time we will dig in a little bit to investigate how TaxonomyWebTaggingControl works and illustrate some examples how to access and manipulate TaxonomyWebTaggingControl on the client side.

TaxonomyWebTaggingControl

Before we proceed let me clarify some details about TaxonomyWebTaggingControl control itself.

TaxonomyWebTaggingControl ASP.NET control is a server side wrapper for ScriptForWebTaggingUI client control. One of the main purposes of TaxonomyWebTaggingControl control is to provide the ability to initialize ScriptForWebTaggingUI control by generating parameters on the server side (see table 1).

It is interesting to note here that ScriptForWebTaggingUI was built using Script#. Script# is a development tool that generates JavaScript by compiling C# source code. It means that ScriptForWebTaggingUI was originally created by Microsoft as C# control and this is another great example of using Script# for building real world applications.

ScriptForWebTaggingUI control properties

Table 1. ScriptForWebTaggingUI client control properties .

InputFieldId	Input field ID that is used for storing term value
SspId	IDs of the TermStore objects that this control will validate against
GroupId	Gets and sets the IDs of the Group object that this control will validate against
TermSetId	Gets the IDs of the TermSet object that this control will validate against
AnchorId	Get or set the ID of the Taxonomy whose children will be used to validate against
IsMulti	Gets or sets whether this control accepts multiple Term objects
AllowFillIn	Gets or sets whether this control will give the option of adding new Term objects if the Open() property is set.
WidthCSS	Gets or sets a CSS class that will be applied to the control that should specify a width CSS class.
Lcid	Gets or sets the LCID repesenting the language this control will validate against.
IsSpanTermSets	Gets and sets whether this control will resolve against all TermSet objects or only the TermSet objects provided.
IsSpanTermStores	Gets or sets whether this control will resolve against all TermStore objects or only the TermStore objects provided.
IsIgnoreFormatting	Gets or sets whether this control will format valid and invalid Term objects or leave them as plain text.
IsIncludeDeprecated	Gets or sets whether this control will resolve against deprecated Term objects.
IsIncludeUnavailable	Gets or sets whether this control will resolve against unavailable Term objects.
IsIncludeTermSetName	Gets and sets whether this control will resolve against the names of TermSet object names.
IsAddTerms	Gets and sets whether this control will try to add unresolved Term objects to the TermSet object.
IsIncludePathData	Gets or sets whether this control will include the full GUID path for all Term objects.
IsUseCommaAsDelimiter	Gets or sets whether this control will use a comma in addition to a semi-colon as a delimiter.
Disable	Gets or sets whether this control is disabled or not
ExcludeKeyword	Gets and sets whether this control will resolve against keyword Term object or not
WebServiceUrl	Gets and sets the URL of the TaxonomyInternalService that will be used to resolve against
FieldName	Gets and sets the value that will be shown in the ToolTip on the client
FieldId	Gets and sets the id of field
DisplayPickerButton	Gets or sets whether this control will allow browsing with the picker

Relevant properties for server side TaxonomyWebTaggingControl control are listed here.

Microsoft.SharePoint.Taxonomy client namespace in SharePoint 2010

Table 2. The following table lists classes used for ScriptForWebTaggingUI control

HighlightResult
ScriptForWebTaggingUI	Represents container for ControlObject
ControlObject	Represents control itself
Term	Defines Term on the client side
ScriptResources
PanelResizer
SelectionMadeEventArgs
SuggestionContainer
SuggestionGroup
Suggestion

Access and manipulate TaxonomyWebTaggingControl from client side

To manipulate term values in TaxonomyWebTaggingControl control we’ll use Client Object model for Taxonomy listed in table 2, in particular ControlObject capabilities. Below are provided methods for getting and setting values in TaxonomyWebTaggingControl on the client side

To find TaxonomyWebTaggingControl on the client side webTaggingId identifier is used, that corresponds to ContainerId property of control.

Usage

Testing data

For demonstration purposes we’ll use information about countries that has the following structure:

the first level is the continents
the second level is the countries

Example 1. Setting TaxonomyWebTaggingControl control value

Example 2. Getting TaxonomyWebTaggingControl control value

In this example is demonstrated how to get term value from

Example 3.Retrieve ScriptForWebTaggingUI control properties

For every instance of TaxonomyWebTaggingControl control placed on page is generated corresponding ScriptForWebTaggingUI control that could be used to retrieving properties as shown below:

References

19 thoughts on “Using SharePoint TaxonomyWebTaggingControl control: Access and manipulate from client side”

Max says:

March 4, 2013 at 1:08 am

Hi, Vadim!

Have you found any way to attach to the event when the user clicks OK button in WebTagging dialog and the value of termset field is changed?

Reply
Vadim Gremyachev says:

March 6, 2013 at 11:15 pm

Hi Max,
when the value of termset field is changed, event Microsoft.SharePoint.Taxonomy.ScriptForWebTaggingUI.onTextChanged is raised by default.
This event is registered for ScriptForWebTaggingUI control with the following line:

RTE.CanvasEvents.registerListener(RTE.CanvasEvents.editableRegionChangedEvent, Function.createDelegate(null, Microsoft.SharePoint.Taxonomy.ScriptForWebTaggingUI.onTextChanged));

It means that you could provide additional event handler when the value of termset field is changed:

function initTaggingControl() { RTE.CanvasEvents.registerListener(RTE.CanvasEvents.editableRegionChangedEvent, Function.createDelegate(null, onCustomTextChanged)); }
function onCustomTextChanged(sender, args) { //Some code after value of termset field is changed goes here... }
ExecuteOrDelayUntilScriptLoaded(initTaggingControl, 'ScriptForWebTaggingUI.js');

Hope it helps,
Vadim

Reply
- Max says:
  
  May 16, 2014 at 9:51 am
  
  Hi Vadim,
  I’m working on a different project now and come across your blog again while searching for different kind of information after a year and just noticed that I asked you a question and you actually answered it! 🙂
  I wish I had seen your answer before! Actually, a year ago I handle onchange event differently: http://maxim-dikhtyaruk.blogspot.com/2013/03/client-side-scripting-for-taxonomyterm.html
  Solution is definitely not elegant and right, but it worked for me :).
  Now, we are looking for possibility of using SharePoint taxonomy picker in our provider-hosted app. Presumably, it will work fine with client context…
  Cheers,
  Maksym
  
  Reply
Guillermo says:

June 17, 2013 at 10:00 pm

Great post Vadim! Very helpful.
I need to go a little further. Is there a way to create the TaxonomyWebTaggingControl directly from client side?
I need to create the control dynamically from javascript. Do you think there’s a way to do that?

Thanks!

Reply
- Vadim Gremyachev says:
  
  June 18, 2013 at 5:03 pm
  Hi Guillermo, yes, I’m pretty sure it is doable.
  
  The list of some points that should be considered for implementing JavaScript based taxonomy control:
  - TaxonomyWebTaggingControl is rendered as a div container and hidden field for storing taxonomy value(s) on the client side
  - tagUI JavaScript object is used for storing Taxonomy information (SspId, TermSetId and etc.)
  - TaxonomyWebTaggingControl control utilizes internal service /_vti_bin/TaxonomyInternalService.json for communication with Taxonomy service application
  Reply
  - ovsleep says:
    
    June 18, 2013 at 5:33 pm
    
    Thanks Vadim!
    I’ll give it a try and let you know.
  - Vadim Gremyachev says:
    
    June 18, 2013 at 6:01 pm
    
    Hi Guillermo, thank you, it is really interesting idea.
  - ovsleep says:
    
    June 18, 2013 at 11:18 pm
    
    Vadim, I finally managed to create the taxonomy control from client side code. Thanks for the help!
    I leave you a function to do this:
    
    //id: the id the control will have
    //parent: dom element where the field will be appended
    //SspId: SspId for the field in GUID format, ex: {00923257-fabc-4cd2-8442-ff475ed16743}
    //TermSetId: TermSetId for the field in GUID format, ex: {00923257-fabc-4cd2-8442-ff475ed16743}
    function generateTaxonomyField(id, parent, SspId, TermSetId) {
    //Generates required dom elements
    var span = $(“”);
    span.append($(“”));
    span.append($(“”));
    parent.append(span);
    
    //Get the site collection url
    var wsUrl = window.location.protocol + “//” + window.location.host + _spPageContextInfo.siteServerRelativeUrl;
    wsUrl.replace(‘/’, ‘\u002f’);
    
    //initialize control
    var tagUI = document.getElementById(id + “_div”);
    if (tagUI) {
    tagUI[‘InputFieldId’] = id + “_input”;
    tagUI[‘SspId’] = SspId;
    tagUI[‘GroupId’] = ‘00000000-0000-0000-0000-000000000000’;
    tagUI[‘TermSetId’] = TermSetId;
    tagUI[‘AnchorId’] = ‘00000000-0000-0000-0000-000000000000’;
    tagUI[‘IsMulti’] = true;
    tagUI[‘AllowFillIn’] = true;
    tagUI[‘WidthCSS’] = ‘ms-taxonomy-width’;
    tagUI[‘JavascriptOnValidation’] = “”;
    tagUI[‘Lcid’] = 3082;
    tagUI[‘IsSpanTermSets’] = false;
    tagUI[‘IsSpanTermStores’] = false;
    tagUI[‘IsIgnoreFormatting’] = false;
    tagUI[‘IsIncludeDeprecated’] = false;
    tagUI[‘IsIncludeUnavailable’] = false;
    tagUI[‘IsIncludeTermSetName’] = false;
    tagUI[‘IsAddTerms’] = false;
    tagUI[‘IsIncludePathData’] = false;
    tagUI[‘IsUseCommaAsDelimiter’] = false;
    tagUI[‘Disable’] = false;
    tagUI[‘ExcludeKeyword’] = false;
    tagUI[‘WebServiceUrl’] = wsUrl + ‘\u002f_vti_bin\u002fTaxonomyInternalService.json’;
    tagUI[‘FieldName’] = ‘Agregar t\u00E9rminos’;
    tagUI[‘FieldId’] = ‘00000000-0000-0000-0000-000000000000’;
    tagUI[‘DisplayPickerButton’] = true;
    var _emmTaggingLoadCall;
    if (_emmTaggingLoadCall == null) {
    _emmTaggingLoadCall = true;
    SP.SOD.executeFunc(‘ScriptForWebTaggingUI.js’, ‘Microsoft.SharePoint.Taxonomy.ScriptForWebTaggingUI.taggingLoad’,
    function () { Microsoft.SharePoint.Taxonomy.ScriptForWebTaggingUI.resetEventsRegistered(); }
    );
    }
    SP.SOD.executeFunc(‘ScriptForWebTaggingUI.js’, ‘Microsoft.SharePoint.Taxonomy.ScriptForWebTaggingUI.onLoad’,
    function () { Microsoft.SharePoint.Taxonomy.ScriptForWebTaggingUI.onLoad(id + “_div”); }
    );
    }
    }
    
    var container = $(‘#container’);
    generateTaxonomyField(‘myTaxonomyField’, container, “{00923257-fabc-4cd2-8442-ff475ed16743}”, “{6abc6553-8a75-4a0b-8100-ce330ce4779b}”);
  - Vadim Gremyachev says:
    
    June 19, 2013 at 5:13 pm
    
    Hi Guillermo,
    oh, that’s a great, thanks for sharing it!
W0ut says:

February 21, 2014 at 3:34 pm

It is possible to share a sample solution? Thanks.

I’m having problems with getting the pop-up, of the taxonomyWebTaggingControl, to work. It remains empty. Filling out terms directly in the control, the suggestions, etc… all work. Only the the “select pop-up” is giving me a headache.

Reply
Esben Wiberg says:

July 24, 2014 at 3:39 pm

I’m getting error, and the dialog is remaining empty:
Refused to display ‘http://XXX/_layouts/15/WebTaggingDialog.aspx?Field=XXX&IsDlg=1′ in a frame because it set ‘X-Frame-Options’ to ‘SAMEORIGIN’
any ideas ?

Reply
Esben Wiberg says:

July 24, 2014 at 3:40 pm

Hi, I’m getting the following error, and the dialog remains empty:

Refused to display ‘http://XXX/_layouts/15/WebTaggingDialog.aspx?Field=XXX&IsDlg=1’ in a frame because it set ‘X-Frame-Options’ to ‘SAMEORIGIN’

Any ideas ?

Reply
- Esben Wiberg says:
  
  July 24, 2014 at 4:53 pm
  
  Got it.. I needed to lazy load init.js and strings.js before the call to ‘Microsoft.SharePoint.Taxonomy.ScriptForWebTaggingUI.onLoad(id + “_div”); }’
  
  My next issue here (I’ve had a lot so far) Is the autolookup in the input control..
  In the dialog it works like a charm though 🙂
  
  Any ideas ?
  
  Reply
Gabriel Smoljár (@gabbsmo) says:

September 18, 2014 at 1:31 pm

How should the termValue be formatted if the control accepts multiple values?

Reply
nilsandrey says:

November 18, 2014 at 12:02 am

This post was life saver. Works like charms. Other ways with javascript couldn’t actually save the value of the term on a Form of new item for a particular content type. I introduce the code via JSLink associated to the Content Type.

Reply
nilsandrey says:

November 18, 2014 at 12:32 am

Reblogged this on Nilsandrey's Weblog.

Reply
Adam says:

November 27, 2014 at 12:10 pm

Not sure how this has worked for others but I found the webTaggingId required isnt the control ID but the div that sits beneath that control ID, which you wont know at runtime. So I had to have this in the get function above:

var webTaggingId = jQuery(“#” + elementId + “> div”).attr(“id”);

Otherwise it doesnt work.

Reply
Ghofrane Rhimi says:

November 12, 2015 at 12:32 am

Great ! thanks a lot you saved my life !
In my case The webTaggingId is the div taxonomy fieldName + ‘_$container’

Reply
Tolu Adesegha says:

January 19, 2017 at 6:50 pm

I found the code required to render the taxonomy picker on the web but ovsleep is the only one I’ve found that has sample values. I spent a good number of hours ( more than I would like to admit ) trying to figure out why the picker was not rendering. Eventually I read through this post, and comments, and found out braces were required around the sspId and termSetId guids.

Reply