SharePoint 2010 Field Collections

Every SharePoint cell in a list is controlled by a field. Fields are implemented as derived types from SPField class and exposed as collections through SPFieldCollection. This topic shows diagrams to better understand how fields relate to any other SharePoint artifact. We start with smaller diagrams, with less detail, and we finish with a complete view for all field-related collections and classes.

Fields Property

SPFieldCollection collections of SPField objects are returned through a Fields property by the following SharePoint classes: SPWeb, SPList, SPListItem, SPContentType and SPContext:

Edit

View

Print

A field has a field type definition (SPField.FieldTypeDefinition –> SPFieldTypeDefinition). All field type definitions are held at the website level (SPWeb.FieldTypeDefinitionCollection).

SPWeb.Fields returns all fields in the website, while SPWeb.AvailableFields returns all site columns and the built-in columns used by the lists, except custom columns created at the document library level. SPListItem returns all SPField objects used in its cells, while SPList.Fields returns all fields used by all its items.

SPContext may have a current list item or content type of the Microsoft SharePoint Foundation context, in which case SPContentType.Fields returns all associated fields.

Web, List, and Content Type Fields

The following diagram shows the close relationships between SPWeb, SPContentType, SPList and SPListItem. They all return collection of SPField objects through their Fields property, but content types may be defined at the website-level or list-level, lists have list items, and a list item may be based on a content type:

Edit

View

Print

The following code sequence creates a “Products” list, updates the “Title” field and adds three custom fields. A view is created to render list data using the added fields:

private static Guid CreateProductsList(SPWeb site, Guid categsListId) {
    // check list exists
    SPList list = site.Lists.TryGetList("Products");
    if (list != null) list.Delete();

    // create new list
    Guid listId = site.Lists.Add("Products", "", SPListTemplateType.GenericList);

    // update list properties
    list = site.Lists[listId];
    list.EnableAttachments = true; list.EnableFolderCreation = false;
    list.OnQuickLaunch = true;

    // update list Title
    list.Fields["Title"].Title = "Product";
    list.Fields["Title"].Update();

    // add lookup field to Category
    list.Fields.AddLookup("Category", categsListId, true);
    SPFieldLookup lookup = (SPFieldLookup) list.Fields["Category"];
    lookup.Indexed = true;
    lookup.RelationshipDeleteBehavior = SPRelationshipDeleteBehavior.Restrict;
    lookup.Update();

    // add field List Price
    string s = list.Fields.Add("ListPrice", SPFieldType.Currency, true);
    SPFieldCurrency price = (SPFieldCurrency) list.Fields.GetFieldByInternalName(s);
    price.Title = "List Price";
    price.DefaultValue = "0"; price.MinimumValue = 0; price.MaximumValue = 10000;
    price.CurrencyLocaleId = 1033; // local ID for United States Dollars
    price.DisplayFormat = SPNumberFormatTypes.TwoDecimals;
    price.Update();

    // add choice field Age Group
    s = ProductsList.Fields.Add("AgeGroup", SPFieldType.Choice, true);
    SPFieldChoice ageGroup = (SPFieldChoice) list.Fields.GetFieldByInternalName(s);
    ageGroup.Choices.Add("Ages 1-4"); ageGroup.Choices.Add("Ages 5-12");
    ageGroup.Choices.Add("Ages 12 and up"); ageGroup.Choices.Add("Ages 18 and up");

    // modify display name and field rendering format
    ageGroup.Title = "Age Group";
    ageGroup.EditFormat = SPChoiceFormatType.RadioButtons;
    ageGroup.Update(true);

    list.Update();

    // add new fields to default view
    SPView view = list.DefaultView;
    view.ViewFields.Add("Category");
    view.ViewFields.Add("ListPrice");
    view.ViewFields.Add("AgeGroup");
    view.Update();

    return listId;
}

List and View Fields

List data is rendered though list views, exposed by the Views collection. The SPView.ViewFields property contains the names of all fields actually rendered by the view, which should map to the names of the SPField list fields. Lists also expose, thourgh the SPList.FieldIndexes property, a collection of SPFieldIndex objects, which represent content indexes extending over one or two fields in the list. SPFieldIndex supports the efficient query of list items that filter by those fields.

Edit

View

Print

SPQuery contains a property with the same name, but SPQuery.ViewFields must be set to referenced fields using a CAML syntax. The following code sequence uses a query to get a collection of items from the Tasks list and specifies the field values to return with each item.

using (SPSite site = new SPSite("http://localhost"))
using (SPWeb web = site.OpenWeb()) {
   // Build a query.
   SPQuery query = new SPQuery();
   query.Query = string.Concat(
      "<Where><Eq>",
         "<FieldRef Name='Status'/>",
         "<Value Type='CHOICE'>Not Started</Value>",
      "</Eq></Where>",
      "<OrderBy>",
         "<FieldRef Name='DueDate' Ascending='TRUE' />",
         "<FieldRef Name='Priority' Ascending='TRUE' />",
      "</OrderBy>");
   query.ViewFields = string.Concat(
      "<FieldRef Name='AssignedTo' />",
      "<FieldRef Name='LinkTitle' />",
      "<FieldRef Name='DueDate' />",
      "<FieldRef Name='Priority' />");
   query.ViewFieldsOnly = true; // Fetch only the data that we need.

   // Get data from a list.
   SPListItemCollection items = web.GetList(web.ServerRelativeUrl + "/lists/tasks").GetItems(query);
}

Content Type Fields

SPContentType.Fields returns the collection of fields defined specifically for that content type. However, content types may include fields defined elsewhere, in which case SPContentType.FieldLinks property returns a collection of references to those fields. Each SPFieldLink is instantiated with a reference to the actual SPField.

Edit

View

Print

The following code sequence defines a new “Customer” content type at the SPWeb website level and a “LastOrder” site field, then uses this field through a SPFieldLink reference. A new “Customers” list is created to use this content type:

using (SPSite site = new SPSite("http://my-host/dev/"))
using (SPWeb web = site.OpenWeb()) {
    // Create a new site content type.
    Debug.Assert(web.AvailableContentTypes["Customer"] == null);
    SPContentType ct = new SPContentType(
        web.ContentTypes[SPBuiltInContentTypeId.Contact], web.ContentTypes, "Customer");
    web.ContentTypes.Add(ct);

    // Create a site field to link to.
    Debug.Assert(!web.Fields.ContainsField("LastOrder"));
    web.Fields.Add("LastOrder", SPFieldType.DateTime, false);
    SPField field = web.Fields.GetField("LastOrder");
    ct.FieldLinks.Add(new SPFieldLink(field));
    ct.Update();

    // Create a list.
    Guid listID = web.Lists.Add("Customers", "...", SPListTemplateType.Contacts);
    SPList list = web.Lists[listID];
    list.OnQuickLaunch = true;
    list.Update();

    // Apply the new content type to the list.
    list.ContentTypesEnabled = true;
    if (list.IsContentTypeAllowed(ct)) {
        list.ContentTypes.Add(ct);
        list.ContentTypes[0].Delete();
        list.Update();
    }
}

Complete Diagram

All previous diagrams have been derived from this complete diagram. If you’re rather a visual person and prefer an image with full details, it may be helpful:

Edit

View

Print