Tag Archives: TaxonomyWebTaggingControl

Using SharePoint TaxonomyWebTaggingControl control: Access and manipulate from client side

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.

//Set Taxonomy ControlObject value
//webTaggingId – TaxonomyWebTaggingControl ID
//termValue – represents a single value held in a TaxonomyField object using the following format: NameOfTerm|GUIDOfTerm
function setTaxonomyControlObjectValue(webTaggingId, termValue) {
var webTaggingCtl = $get(webTaggingId);
var taxCtlObj = new Microsoft.SharePoint.Taxonomy.ControlObject(webTaggingCtl);
taxCtlObj.enableControl(true);
taxCtlObj.setRawText(termValue);
taxCtlObj.retrieveTerms();
}

view raw
setTaxonomyControlObjectValue.js
hosted with ❤ by GitHub

//Get Taxonomy ControlObject value
//webTaggingId – TaxonomyWebTaggingControl ID
function getTaxonomyControlObjectValue(webTaggingId) {
var webTaggingCtl = $get(webTaggingId);
var taxCtlObj = new Microsoft.SharePoint.Taxonomy.ControlObject(webTaggingCtl);
var termValue = taxCtlObj.getRawText();
return termValue;
}

view raw
getTaxonomyControlObjectValue.js
hosted with ❤ by GitHub

Usage

Testing data

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

CountriesTermSet

Example 1. Setting TaxonomyWebTaggingControl control value

//Example 1. Setting TaxonomyWebTaggingControl control value during event (page load, button click and etc.)
function initCountryTaggingControl() {
var countriesControlId = "ctl00_PlaceHolderMain_ctl03";
var continentTermValue = "Africa|43f3b1e7-e40c-45d2-a613-88643668d373";
setTaxonomyControlObjectValue(countriesControlId, continentTermValue);
}
ExecuteOrDelayUntilScriptLoaded(initCountryTaggingControl, 'ScriptForWebTaggingUI.js');

view raw
initCountryTaggingControl1.js
hosted with ❤ by GitHub

Example 2. Getting TaxonomyWebTaggingControl control value

In this example is demonstrated how to get  term value from

//Example 2. Getting TaxonomyWebTaggingControl control value
function initCountryTaggingControl2() {
var countriesControlId = "ctl00_PlaceHolderMain_ctl03";
var continentTermValue = getTaxonomyControlObjectValue(countriesControlId);
}
ExecuteOrDelayUntilScriptLoaded(initCountryTaggingControl, 'ScriptForWebTaggingUI.js');

view raw
initCountryTaggingControl2.js
hosted with ❤ by GitHub

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:

//Example 3. Retrieve ScriptForWebTaggingUI control properties
function initCountryTaggingControl3() {
var tagUI = document.getElementById(taggingWebId);
if (tagUI){
console.log(tagUI.TermSetId); //prints TermSet ID
console.log(tagUI.SspId); //prints TermStore ID
}
}
ExecuteOrDelayUntilScriptLoaded(initCountryTaggingControl3, 'ScriptForWebTaggingUI.js');

view raw
initCountryTaggingControl3.js
hosted with ❤ by GitHub

References

Using SharePoint TaxonomyWebTaggingControl control: specifying parent terms

Overview

TaxonomyWebTaggingControl represents a generic Web control for picking managed metadata terms.

During initialization two properties are mandatory to bind this control with Managed Metadata Service (MMS):

Below is presented example how to initialize it

/// <summary>
/// Initializing TaxonomyWebTaggingControl control
/// </summary>
/// <param name="countryControl"> </param>
/// <param name="session"></param>
/// <param name="countriesTermSet"></param>
private void InitCountriesControl(TaxonomyWebTaggingControl countryControl, TaxonomySession session, TermSet countriesTermSet)
{
countryControl.SSPList = countriesTermSet.TermStore.Id.ToString();
countryControl.TermSetList = countriesTermSet.Id.ToString();
}

view raw
InitCountriesControl.cs
hosted with ❤ by GitHub

Country picker

Let us consider the case when not all terms for the term set should be shown but a subset only. Assume we have the following structure for the countries:

CountriesTermSet

and our goal to display countries in TaxonomyWebTaggingControl only for selected continent as shown below

TaxonomyWebTaggingControl

This could be achieved by setting AnchorId property for TaxonomyWebTaggingControl control that allows to specify ID of parent Term for any valid value in control.

Implementation

Country picker allows to select continent/country from Countries term set.

Depending on the selected continent  only countries specific  for  continent are shown in TaxonomyWebTaggingControl control

CountryPicker

The code below contains Country Picker implementation:

public class CountryPickerPage : LayoutsPageBase
{
protected override void OnInit(EventArgs e)
{
continentsControl.AutoPostBack = true;
continentsControl.SelectedIndexChanged += ContinentsControlChanged;
base.OnInit(e);
}
protected override void OnLoad(EventArgs e)
{
var session = new TaxonomySession(SPContext.Current.Site, false);
if(!Page.IsPostBack)
{
var countriesTermSet = InitContinentsControl(session);
InitCountriesControl(session, countriesTermSet,null);
}
base.OnLoad(e);
}
private TermSet InitContinentsControl(TaxonomySession session)
{
var termStore = session.DefaultKeywordsTermStore;
var groupSE = termStore.Groups["Geography"];
var countriesTermSet = groupSE.TermSets["Countries"];
if (countriesTermSet != null)
{
var countriesTerms = countriesTermSet.Terms;
continentsControl.DataTextField = "Name";
continentsControl.DataValueField = "Id";
continentsControl.DataSource = countriesTerms;
continentsControl.DataBind();
}
return countriesTermSet;
}
private void InitCountriesControl(TaxonomySession session, TermSet countriesTermSet, Term continentTerm)
{
if (countriesTermSet != null)
{
this.countryControl.SSPList = countriesTermSet.TermStore.Id.ToString();
this.countryControl.TermSetList = countriesTermSet.Id.ToString();
}
else if (continentTerm != null)
{
this.countryControl.SSPList = continentTerm.TermStore.Id.ToString();
this.countryControl.AnchorId = continentTerm.Id;
this.countryControl.TermSetList = continentTerm.TermSet.Id.ToString();
}
}
void ContinentsControlChanged(object sender, EventArgs e)
{
var control = sender as DropDownList;
if (control != null)
{
var continentTermId = new Guid(control.SelectedValue);
var session = new TaxonomySession(SPContext.Current.Site, false);
var termStore = session.DefaultKeywordsTermStore;
var continentTerm = termStore.GetTerm(continentTermId);
InitCountriesControl(session, null, continentTerm);
}
}
protected TaxonomyWebTaggingControl countryControl;
protected DropDownList continentsControl;
}

view raw
CountryPickerPage.cs
hosted with ❤ by GitHub