Microsoft® SharePoint® 2013 Developer Reference: Data Provisioning

The previous chapters showed you how many Microsoft SharePoint solutions rely on lists of items that contain data, such as contacts, files, and so on. When you develop a SharePoint solution, therefore, one of your main tasks is to provision data structures for these lists of items. In fact, whenever you need to develop a reusable and maintainable solution that will reside on many different site collections and has many different customers, you should formally define the data structures that you will use. Simply designing them through the SharePoint visual design interface from a web browser might seem easy (any end user can do it), but in the long run it will become a source of confusion. Formal definitions can be reused many times in multiple sites and can be versioned. Meanwhile, data structure definitions made manually through the visual design interface are difficult to reuse and can lead to duplication of definitions in multiple sites. Also, when you create SharePoint apps hosted on SharePoint, you can use the data model of lists and items provided by SharePoint for storing data and content related to your apps.

This chapter explores the rules for custom lists and the tools that SharePoint 2013 provides to create them. To learn how these tools behave in a real-world scenario, you will investigate how to define a custom list of contacts that can use custom forms and can be browsed through specific list views. The list in this case study will be based on two content types: Customer and Supplier.

Site columns

The first and main step in provisioning a custom data structure is to define site columns. A site column describes a reusable data type model that you can use in many different content types and list definitions, across multiple SharePoint sites. Unless you have never used SharePoint at all, you will have already defined many site columns using a web browser, within the appropriate section of the Site Settings page. To create a more flexible and reusable solution, you can also define a site column using some XML code, which in SharePoint is called a feature element.

Listing 3-1 shows a very simple site column definition for a Text column that contains the company name of the sample contact.

LISTING 3-1 A simple site column defined in a feature element

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Field
    ID="{A8F24550-55CD-4d34-A015-811954C6CE24}"
    Name="DevLeapCompanyName"
    StaticName="DevLeapCompanyName"
    DisplayName="Company Name"
    Type="Text"
    Group="DevLeap Columns" />
</Elements>

Aside from the Elements tag itself, which is simply a container element, the interesting part of the preceding column definition is the Field element. The most important feature of this element is the ID attribute, which is a globally unique identifier (GUID) that uniquely identifies the site column. You can use the ID attribute to reference this specific site column everywhere. Notice that you can create unique GUIDs by using the GUIDGEN tool provided with Microsoft Visual Studio 2012.

Listing 3-1 declares that the Company Name column will have an internal Name attribute of DevLeapCompanyName. Name is a required attribute, and like the ID attribute, it should also be unique, because it provides an alternative way to exclusively reference the column from code. In general, this example uses the developer’s company name value as a prefix to better ensure the uniqueness of this name. The Name attribute value cannot contain spaces or any characters other than numbers (0 through 9) and letters (a through z and A through Z). Any other characters will be converted into the corresponding hexadecimal representation. For example, if you want to name a field Company Name, you must define it as Company_x0020_Name. If you want to name a field Revenue %, you must define it as Revenue_x0020__x0025_. The last thing to keep in mind is that the Name attribute cannot be longer than 32 characters.

The preceding site column definition also defines the optional StaticName attribute, which is another way of defining the internal name. The StaticName can be useful for referencing your field in custom code, regardless of the encoding used in the Name field. Finally, the site column definition defines the field’s DisplayName attribute, whose value is the title that users will see in their browsers. This last attribute can take advantage of the multilanguage support provided by Microsoft .NET in general, so declaring its value as a resource string reference (“$Resources:<Assembly_Name>,<Resource_Name>;”) instead of an explicit value will result in a multilanguage value.

The Type attribute is mandatory for site column definitions. It defines the data type assigned to the field. This Type attribute value can be one of a predefined set of SharePoint field types, or it can be a custom field type that you have defined and deployed. Table 3-1 presents some of the main field types provided by SharePoint.

Table 3-1. Common predefined field types

The last attribute defined in the site column example is the Group attribute, which simply defines a group membership to make it easier to find custom fields through the web browser administrative interface. Group is an optional attribute, but it is better that you define it whenever you create a custom site column, in order to organize your columns in personalized custom groups.

Although it’s not an exhaustive keyword reference, Table 3-2 shows some of the many other interesting attributes that you can use when defining custom site columns. For a complete reference of the available attributes, you can read the following page on MSDN: http://msdn.microsoft.com/en-us/library/aa979575.aspx.

Table 3-2. Interesting optional Boolean attributes available for the Field element

While Listing 3-1 introduced a basic definition, Listing 3-2 adds another level of complexity by declaring a Choice field that will be used to select the contact’s country affiliation.

LISTING 3-2 A Choice site column defined in a feature element

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Field
    ID="{149BF9A1-5BBB-468d-AA35-91ACEB054E3B}"
    Name="DevLeapCountry"
    StaticName="DevLeapCountry"
    DisplayName="Country"
    Type="Choice"
    Group="DevLeap Columns"
    Sortable="TRUE">
      <Default>Italy</Default>
      <CHOICES>
        <CHOICE>Italy</CHOICE>
        <CHOICE>USA</CHOICE>
        <CHOICE>Germany</CHOICE>
        <CHOICE>France</CHOICE>
      </CHOICES>
  </Field>
</Elements>

This example shows how you can define a set of available values for a Choice field. Note that the list defines a Default element.

Another interesting task that you can accomplish when defining a site column is to declare a custom validation rule for its content. To do that, you simply define a Validation element as a child of the Field definition. The Validation element can have a Message attribute, which defines an error message to display to end users when validation fails, and a Script attribute, which defines a JavaScript rule that performs the validation. Alternatively, you can define a rule using the Formulas syntax of SharePoint, putting the rule inside the Validation element.