Home > Sample chapters

Microsoft® SharePoint® 2013 Developer Reference: Data Provisioning

This chapter from Microsoft® SharePoint® 2013 Developer Reference 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.

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

Field type name

Description

Boolean

Represents a Boolean value (TRUE or FALSE), stored as a bit in Microsoft SQL Server and accessible as an SPFieldBoolean object through the Server Object Model.

Choice

Allows the user to select a single value from a predefined set of values. The XML schema of the Field element must declare the values (for further details, see Listing 3-2). It is stored as an nvarchar in SQL Server, and is accessible as an SPFieldChoice object through the Server Object Model.

MultiChoice

Allows the user to select multiple values from a predefined set of values. The XML schema of the Field element has to declare the values. It is stored as an ntext in SQL Server, and is accessible as an SPFieldMultiChoice object through the Server Object Model.

Currency

Defines a currency value. Currency is bound to a specific locale, using an LCID attribute. It can have constraints using Min, Max, and Decimals attributes. It is stored as a float in SQL Server and is accessible as an SPFieldCurrency object through the Server Object Model.

DateTime

Saves a date and time value. DateTime is stored as a datetime in SQL Server, and is accessible as an SPFieldDateTime object through the Server Object Model.

Lookup and LookupMulti

Behave almost the same as Choice and MultiChoice; however, the set of values to choose from is taken from another list of items within the same site. These field types are stored as int types in SQL Server, and are accessible as SPFieldLookup objects through the Server Object Model.

Note

Stores multiple lines of text. Note is stored as an ntext in SQL Server, and is accessible as an SPFieldMultiLineText object through the Server Object Model.

Number

Defines a floating-point number. Number can have constraints using Decimals, Div, Max, Min, Mult, and Percentage. It is stored as a float in SQL Server and is accessible as an SPFieldNumber object through the Server Object Model.

Text

Describes a single line of text of a configurable maximum length. Text is stored as an nvarchar in SQL Server, and is accessible as an SPFieldText object through the Server Object Model.

URL

Defines a URL with a specific LinkType (Hyperlink or Image). URL is stored as an nvarchar in SQL Server and is accessible as an SPFieldUrl object through the Server Object Model.

User and UserMulti

Describe a lookup for a single user or a set of users. These are stored as an int types in SQL Server, and are accessible as SPFieldUser objects through the Server Object Model.

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

Field attribute

Description

Hidden

Can assume a value of TRUE or FALSE. When TRUE, the field will be completely hidden from the UI and will be accessible only through code, using the Object Model.

ReadOnly

Can assume a value of TRUE or FALSE. When TRUE, the field will not be displayed in new and edit forms, but can be included in read-only data views. It will remain accessible using the object model.

Required

Can assume a value of TRUE or FALSE. Its name implies its role.

RichText

Can assume a value of TRUE or FALSE. It determines whether a text field will accept rich text formatting.

ShowInDisplayForm

Can assume a value of TRUE or FALSE. When FALSE, the field will not be displayed in the display form of the item containing the field.

ShowInEditForm

Can assume a value of TRUE or FALSE. When FALSE, the field will not be displayed in the editing form of the item containing the field.

ShowInNewForm

Can assume a value of TRUE or FALSE. If it is FALSE, the field will not be displayed in the form to add a new item containing the field.

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.