TaxonomyField Class

Definition

Namespace:

Microsoft.SharePoint.Taxonomy

Assembly:

Microsoft.SharePoint.Taxonomy.dll

Represents a taxonomy field.

public ref class TaxonomyField : Microsoft::SharePoint::SPFieldLookup

[Microsoft.SharePoint.Client.ClientCallableType(ClientLibraryTargets=Microsoft.SharePoint.Client.ClientLibraryTargets.NonRESTful, ServerTypeId="0831C0F3-C1B9-4d8a-A339-0160F42257B4")]
public class TaxonomyField : Microsoft.SharePoint.SPFieldLookup

type TaxonomyField = class
    inherit SPFieldLookup

Public Class TaxonomyField
Inherits SPFieldLookup

Inheritance

Object

SPField

SPFieldLookup

TaxonomyField

Attributes

ClientCallableTypeAttribute

Examples

using System;
using System.IO;
using System.Globalization;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Taxonomy;

namespace Microsoft.SDK.SharePointServer.Samples
{
    /// <summary>
    /// This project requires the Microsoft.SharePoint.dll and the Microsoft.SharePoint.Taxonomy.dll as
    /// references in order to work.
    /// </summary>
    internal partial class TestTaxonomy
    {
        /// <summary>
        /// This method will create a TaxonomyField on the given list and is bound
        /// to the given term set and has the name columnName
        /// </summary>
        private void TestTaxonomyFieldCreate(SPList list, TermSet termSet, string columnName)
        {
            if (list == null)
            {
                throw new ArgumentException("Parameter list cannot be null");
            }

            if (termSet == null)
            {
                throw new ArgumentException("Parameter termSet cannot be null");
            }

            // The constructor is not actually used
            TaxonomyField taxonomyField = list.Fields.CreateNewField("TaxonomyFieldType", columnName) as TaxonomyField;
            // Sets whether the field accepts multiple values or not
            taxonomyField.AllowMultipleValues = false;
            // If this is set to a GUID of a term only terms that are descendants of the term can
            // be picked
            taxonomyField.AnchorId = Guid.Empty;
            // If this is set to true terms that are not validated will be created
            taxonomyField.CreateValuesInEditForm = false;
            // If this is set to true the user will be given the option to add new terms
            taxonomyField.Open = false;
            // Id of the term store 
            taxonomyField.SspId = termSet.TermStore.Id;
            // If this is set to a URL the items will link to that URL on display
            taxonomyField.TargetTemplate = string.Empty;
            // This assumes you have a group and term set created.  Normally you would pick the specific termset you want
            taxonomyField.TermSetId = termSet.Id;

            // After creating the taxonomy field you have to add it to the list
            list.Fields.Add(taxonomyField);

            Console.WriteLine("Field created");
        }

        /// <summary>
        /// This method will update an SPListItem taxonomy field with the given term
        /// </summary>
        private void TestTaxonomyFieldUpdateFieldItem(Term term, SPListItem item, TaxonomyField taxonomyField)
        {
            if (taxonomyField == null)
            {
                throw new ArgumentException("Parameter taxonomyField cannot be null");
            }
            if (term == null)
            {
                throw new ArgumentException("Parameter term cannot be null");
            }
            if (item == null)
            {
                throw new ArgumentException("Parameter item cannot be null");
            }

            if (item.Fields.Contains(taxonomyField.Id))
            {
                taxonomyField.SetFieldValue(item, term, CultureInfo.CurrentUICulture.LCID);
            }
            else
            {
                throw new ArgumentException("taxonomyField must exist on the list that item is from");
            }
            // Finally we have to actually update the item.
            item.Update();

            Console.WriteLine("Field updated with value " + term.Name);
        }

        /// <summary>
        /// This method will clear an SPListItem taxonomy field
        /// </summary>
        private void TestTaxonomyFieldClearFieldItem(SPListItem item, TaxonomyField taxonomyField)
        {
            if (taxonomyField == null)
            {
                throw new ArgumentException("Parameter taxonomyField cannot be null");
            }
            if (item == null)
            {
                throw new ArgumentException("Parameter item cannot be null");
            }

            if (item.Fields.Contains(taxonomyField.Id))
            {
                if (taxonomyField.AllowMultipleValues)
                {
                    TaxonomyFieldValueCollection taxCollection = new TaxonomyFieldValueCollection(taxonomyField);
                    taxonomyField.SetFieldValue(item, taxCollection);
                }
                else
                {
                    TaxonomyFieldValue taxValue = new TaxonomyFieldValue(taxonomyField);
                    taxonomyField.SetFieldValue(item, taxValue);
                }

                // Finally we have to actually update the item.
                item.Update();

                Console.WriteLine("Field cleared");
            }
            else
            {
                throw new ArgumentException("taxonomyField must exist on the list that item is from");
            }
        }

        /// <summary>
        /// This method will write out to the console the HTML value of the taxonomy field on the given
        /// SPListItem
        /// </summary>
        private void TestGetFieldValueAsHtml(SPListItem item, TaxonomyField taxonomyField)
        {
            if (taxonomyField == null)
            {
                throw new ArgumentException("Parameter taxonomyField cannot be null");
            }
            if (item == null)
            {
                throw new ArgumentException("Parameter item cannot be null");
            }

            if (item.Fields.Contains(taxonomyField.Id))
            {
                Console.WriteLine("The value as HTML is " + taxonomyField.GetFieldValueAsHtml(item[taxonomyField.Id]));
            }
            else
            {
                throw new ArgumentException("taxonomyField must exist on the list that item is from");
            }
        }

        /// <summary>
        /// This method will write out to the console the text value of the taxonomy field on the given
        /// SPListItem
        /// </summary>
        private void TestGetFieldValueAsText(SPListItem item, TaxonomyField taxonomyField)
        {
            if (taxonomyField == null)
            {
                throw new ArgumentException("Parameter taxonomyField cannot be null");
            }
            if (item == null)
            {
                throw new ArgumentException("Parameter item cannot be null");
            }

            if (item.Fields.Contains(taxonomyField.Id))
            {
                Console.WriteLine("The value as text is " + taxonomyField.GetFieldValueAsText(item[taxonomyField.Id]));
            }
            else
            {
                throw new ArgumentException("taxonomyField must exist on the list that item is from");
            }
        }

        /// <summary>
        /// This method will write out to the console the Wss Id values of the taxonomy term
        /// on the given SPSite for the Enterprise Keywords
        /// </summary>
        private void TestGetWssIdsOfKeywordTerm(SPSite site, Term term)
        {
            if (term == null)
            {
                throw new ArgumentException("Parameter term cannot be null");
            }
            if (site == null)
            {
                throw new ArgumentException("Parameter site cannot be null");
            }

            // We are trying to get all the Wss Id's of this term when used as a keyword
            int[] wssIds = TaxonomyField.GetWssIdsOfKeywordTerm(site, term.Id, 500);
            Console.Write("The wss ID's of your term are");
            if (wssIds.Length == 0)
            {
                Console.Write(" empty");
            }
            else
            {
                foreach (int wssId in wssIds)
                {
                    Console.WriteLine(" " + wssId.ToString());
                }
            }

            Console.WriteLine(".");
        }

        /// <summary>
        /// This method will write out to the console the Wss Id values of the taxonomy term
        /// on the given SPSite
        /// </summary>
        private void TestGetWssIdsOfTerm(SPSite site, Term term)
        {
            if (term == null)
            {
                throw new ArgumentException("Parameter term cannot be null");
            }
            if (site == null)
            {
                throw new ArgumentException("Parameter site cannot be null");
            }

            // We are trying to get all the Wss Id's of this term without it's children
            int[] wssIds = TaxonomyField.GetWssIdsOfTerm(site, term.TermStore.Id, term.TermSet.Id, term.Id, false /*includeDescendants*/, 500);
            Console.Write("The wss ID's of your term are");
            if (wssIds.Length == 0)
            {
                Console.Write(" empty");
            }
            else
            {
                foreach (int wssId in wssIds)
                {
                    Console.Write(" " + wssId.ToString());
                }
            }

            Console.WriteLine(".");
        }
    }
}

Remarks

The TaxonomyField class is a custom field class that inherits from the SPFieldLookup class. If you set the properties of the TaxonomyField class, call the Update() method for changes to take effect in the database.

The TaxonomyFieldValue class contains the field value for the TaxonomyField class.

Either the TaxonomyFieldControl object or the TaxonomyWebTaggingControl object server controls can render a TaxonomyField object.

Constructors

TaxonomyField(SPFieldCollection, String)	Initializes a new instance of the TaxonomyField object that is based on the specified field collection and name.
TaxonomyField(SPFieldCollection, String, String)	Initializes a new instance of the TaxonomyField object that is based on the specified field collection, type name, and display name.

Properties

AggregationFunction	(Inherited from SPField)
AllowDeletion	(Inherited from SPField)
AllowMultipleValues	Gets or sets a Boolean value that specifies whether multiple Term objects can be used in the TaxonomyField object.
AnchorId	Gets or sets the GUID of the anchor Term object for a TaxonomyField object.
AuthoringInfo	(Inherited from SPField)
CalloutMenu	(Inherited from SPField)
CalloutMenuAllowed	(Inherited from SPField)
CanBeDeleted	(Inherited from SPField)
CanBeDisplayedInEditForm	(Inherited from SPField)
CanToggleHidden	(Inherited from SPField)
CompositeIndexable	(Inherited from SPField)
CountRelated	(Inherited from SPFieldLookup)
CreateValuesInEditForm	Gets or sets a Boolean value that specifies whether the new Term objects can be added to the TermSet while typing in the TaxonomyField editor control.
DefaultFormula	(Inherited from SPField)
DefaultListField	(Inherited from SPField)
DefaultValue	(Inherited from SPField)
DefaultValueTyped	Gets the default TaxonomyFieldValueCollection or the TaxonomyFieldValue object.
Description	(Inherited from SPField)
DescriptionResource	(Inherited from SPField)
Direction	(Inherited from SPField)
DisplaySize	(Inherited from SPField)
EnforceUniqueValues	(Inherited from SPField)
EntityPropertyName	(Inherited from SPField)
FieldReferences	(Inherited from SPField)
FieldRenderingControl	Gets a TaxonomyFieldControl object that can be used to render the TaxonomyField object.
FieldRenderingMobileControl	Obsolete. Gets the mobile control that is used to render the TaxonomyField object in mobile applications.
FieldRenderingMobileWebControl	(Inherited from SPFieldLookup)
FieldTypeDefinition	(Inherited from SPField)
FieldValueType	Gets the type of the TaxonomyField object.
Filterable	(Inherited from SPField)
FilterableNoRecurrence	(Inherited from SPField)
FromBaseType	(Inherited from SPField)
Group	(Inherited from SPField)
Hidden	(Inherited from SPField)
Id	(Inherited from SPField)
IMEMode	(Inherited from SPField)
Indexable	(Inherited from SPField)
Indexed	(Inherited from SPFieldLookup)
InternalName	(Inherited from SPField)
IsAnchorValid	Gets a Boolean value that specifies whether the Term object identified by the T:Microsoft.SharePoint.Taxonomy.TaxonomyField.AnchorId property is valid.
IsDependentLookup	(Inherited from SPFieldLookup)
IsKeyword	Gets or sets a Boolean value that indicates whether the TaxonomyField value points to the Enterprise Keywords TermSet object.
IsPathRendered	Gets or sets a Boolean value that specifies whether the default Label objects of all the parent Term objects of a Term in the TaxonomyField object will be rendered in addition to the default label of that Term.
IsRelationship	(Inherited from SPFieldLookup)
IsTermSetValid	Gets a Boolean value that specifies whether the TermSet object identified by the TermSetId property exists and is available for tagging.
JSLink	Gets a string containing a list, delimited with the '|' character, of all Javascript files required for the client-side rendering of TaxonomyField values.
JumpToField	(Inherited from SPField)
LinkToItem	(Inherited from SPField)
LinkToItemAllowed	(Inherited from SPField)
ListItemMenu	(Inherited from SPField)
ListItemMenuAllowed	(Inherited from SPField)
LookupField	(Inherited from SPFieldLookup)
LookupList	(Inherited from SPFieldLookup)
LookupWebId	(Inherited from SPFieldLookup)
NoCrawl	(Inherited from SPField)
Open	Gets or sets a Boolean value that specifies whether the TaxonomyField object is linked to an open TermSet object or a closed TermSet.
ParentList	(Inherited from SPField)
PIAttribute	(Inherited from SPField)
PITarget	(Inherited from SPField)
PrependId	(Inherited from SPFieldLookup)
PreviewValueTyped	(Inherited from SPField)
PrimaryFieldId	(Inherited from SPFieldLookup)
PrimaryPIAttribute	(Inherited from SPField)
PrimaryPITarget	(Inherited from SPField)
PushChangesToLists	(Inherited from SPField)
ReadOnlyField	(Inherited from SPField)
RelatedField	(Inherited from SPField)
RelationshipDeleteBehavior	(Inherited from SPFieldLookup)
Reorderable	(Inherited from SPField)
Required	(Inherited from SPField)
SchemaXml	(Inherited from SPField)
SchemaXmlWithResourceTokens	(Inherited from SPField)
Scope	(Inherited from SPField)
Sealed	(Inherited from SPField)
ShowInDisplayForm	(Inherited from SPField)
ShowInEditForm	(Inherited from SPField)
ShowInListSettings	(Inherited from SPField)
ShowInNewForm	(Inherited from SPField)
ShowInVersionHistory	(Inherited from SPField)
ShowInViewForms	(Inherited from SPField)
Sortable	(Inherited from SPField)
SourceId	(Inherited from SPField)
SspId	Gets or sets the GUID that identifies the TermStore object, which contains the Enterprise Keywords for the site that the current TaxonomyField belongs to.
StaticName	(Inherited from SPField)
TargetTemplate	Gets or sets the Web-relative URL of the target page that is used to construct the hyperlink on each Term object when the TaxonomyField object is rendered.
TaxonomyGuidLabelDelimiter	Gets the character that is used to delimit GUIDs and labels in the string representation of the value of a TaxonomyField object.
TaxonomyMultipleTermDelimiter	Gets the character used to delimit multiple Term objects in the string representation of a taxonomy field value collection.
TaxonomyTermPathDelimiter	Gets the character used to delimit Term labels in the path string returned by the GetPath() method.
TermSetId	Gets or sets the GUID of the TermSet object that contains the Term objects used by the current TaxonomyField object.
TextField	Gets or sets the GUID that identifies the hidden text field in an item.
Title	(Inherited from SPField)
TitleResource	(Inherited from SPField)
TranslationXml	(Inherited from SPField)
Type	(Inherited from SPField)
TypeAsString	(Inherited from SPField)
TypeDisplayName	(Inherited from SPField)
TypeShortDescription	(Inherited from SPField)
UnlimitedLengthInDocumentLibrary	(Inherited from SPFieldLookup)
UsedInWebContentTypes	(Inherited from SPField)
UserCreated	Gets or sets a Boolean value that specifies whether the TaxonomyField object is linked to a customized TermSet object.
ValidationEcmaScript	(Inherited from SPField)
ValidationFormula	(Inherited from SPField)
ValidationMessage	(Inherited from SPField)
Version	(Inherited from SPField)
XPath	(Inherited from SPField)

Methods

AnnotateField(XmlNode)	(Inherited from SPFieldLookup)
Delete()	(Inherited from SPField)
FilteringJavascript()	Returns a string containing the that must be rendered on a page to display hierarchical filtering in the filter menu.
GetCustomProperty(String)	(Inherited from SPField)
GetDependentLookupInternalNames()	(Inherited from SPFieldLookup)
GetFieldValue(String)	Converts the specified string value into a TaxonomyFieldValue or a TaxonomyFieldValueCollection object.
GetFieldValueAsHtml(Object)	Returns the field value in HTML format in order to render the field valuedirectly on a page.
GetFieldValueAsText(Object)	Returns a plain text representation of the field value.
GetFieldValueForClientRender(SPItem, SPControlMode)	Converts the field value into an object for use in Display, Edit and New item forms.
GetFieldValueForEdit(Object)	(Inherited from SPField)
GetFilteringHtml(String, SPField, String)	Constructs an HTML string that can be rendered to display a list of Term objects that can be used to filter on the specified TaxonomyField object.
GetJsonClientFormFieldSchema(SPControlMode)	Returns the necessary field schema information for client-side rendering of this control.
GetProperty(String)	(Inherited from SPField)
GetValidatedString(Object)	Validates the field value object using logic specific to the Microsoft.Sharepoint.Taxonomy.TaxonomyField object, and returns a serialized string representation of the validated field value object.
GetWssIdsOfKeywordTerm(SPSite, Guid, Int32)	Gets an array of the list item IDs of all the list items in the taxonomy hidden list where the Enterprise Keywords field contains the specified Term object.
GetWssIdsOfTerm(SPSite, Guid, Guid, Guid, Boolean, Int32)	Gets an array of the list item IDs for all of the list items in the taxonomy hidden list that contain the specified Term object.
HasValue(Object)	Represents whether the current TaxonomyField object has a value.
ListsFieldUsedIn()	(Inherited from SPField)
OnAdded(SPAddFieldOptions)	Occurs after a TaxonomyField object is added.
OnAddingToContentType(SPContentType)	Occurs when a TaxonomyField object is added to a specified content type.
OnDeleting()	Occurs when a TaxonomyField object is being deleted.
OnDeletingFromContentType(SPContentType)	Occurs when a TaxonomyField object is deleted from a specified content type.
OnInitFieldNode()	(Inherited from SPFieldLookup)
OnUpdated()	(Inherited from SPFieldLookup)
ParseAndSetValue(SPListItem, String)	(Inherited from SPField)
ParseValue(SPListItem, String)	(Inherited from SPField)
RenderFieldValueAsJson(Object)	Renders the field value as a serialized JavaScript Object Notation (JSON) string.
RevertCustomizations()	(Inherited from SPField)
SetCustomProperty(String, Object)	(Inherited from SPField)
SetFieldValue(SPListItem, ICollection<Term>)	Sets the value of the corresponding multi-value field in the list item to the properties of the T:Microsoft.SharePoint.Taxonomy.Term objects in the specified collection.
SetFieldValue(SPListItem, ICollection<Term>, Int32)	Sets the value of the corresponding multi-value field in the list item to the properties of the Term objects in the specified collection, in the specified language.
SetFieldValue(SPListItem, TaxonomyFieldValue)	Sets the value of the corresponding field in the list item to the value of the specified TaxonomyFieldValue object.
SetFieldValue(SPListItem, TaxonomyFieldValueCollection)	Sets the value of the corresponding multi-valued field in the list item to the value of the specified TaxonomyFieldValueCollection object.
SetFieldValue(SPListItem, Term)	Sets the value of the corresponding field in the list item to the properties of the specified Term object in the default language of the TermStore object.
SetFieldValue(SPListItem, Term, Int32)	Sets the value of the corresponding field in the list item to the properties of the specified Term in the specified language.
SetFieldValue(SPListItem, TermCollection)	Sets the value of the corresponding multi-value field in the list item to the properties of the Term objects in the specified collection.
SetFieldValue(SPListItem, TermCollection, Int32)	Sets the value of the corresponding multi-value field in the list item to the properties of the Term objects in the specified collection, in the specified language.
ToString()	(Inherited from SPField)
Update()	Updates the database with changes that are made to the TaxonomyField object.
Update(Boolean)	(Inherited from SPField)
ValidateAndParseValue(SPListItem, String)	Parses the field value and returns a validated object.
ValidateParseAndSetValue(SPListItem, String)	(Inherited from SPField)