Compartilhar via


TaxonomyField Class

Represents a taxonomy field.

Inheritance Hierarchy

System.Object
  Microsoft.SharePoint.SPField
    Microsoft.SharePoint.SPFieldLookup
      Microsoft.SharePoint.Taxonomy.TaxonomyField

Namespace:  Microsoft.SharePoint.Taxonomy
Assembly:  Microsoft.SharePoint.Taxonomy (in Microsoft.SharePoint.Taxonomy.dll)

Syntax

'Declaration
<SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel := True)> _
<SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel := True)> _
Public Class TaxonomyField _
    Inherits SPFieldLookup
'Usage
Dim instance As TaxonomyField
[SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
[SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
public class TaxonomyField : SPFieldLookup

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.

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 descendents 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(".");
        }
    }
}

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

TaxonomyField Members

Microsoft.SharePoint.Taxonomy Namespace

TaxonomyFieldValue

Microsoft.SharePoint.Taxonomy

SPFieldLookup

SPField

Microsoft.SharePoint