The List element is the root of the schema file and declares some basic attributes for the list definition. The Title attribute defines the name of the list definition. The BaseType attribute defines the base list type to use for the current list definition. The global onet.xml file of SharePoint (for further details, please read Chapter 13) declares the list of all the available integer values for the BaseType values within a BaseTypes element.

The available BaseTypes values are

For example, Excerpt of a list definition schema file used a BaseType with a value of 0 because we are defining a generic/custom list definition. The Url attribute is optional and defines the path to the root directory containing any ASPX file specific for the list definition. The FolderCreation attribute is also optional, and informs SharePoint whether to show (TRUE) or not show (FALSE) the New Folder command on the list toolbar. Finally, the Direction attribute is optional and declares the reading direction: RTL (right to left) or LTR (left to right). In Excerpt of a list definition schema file, the Direction value is read from a resource string so that the list will be compliant with the current locale settings of the site collection. Lastly, to make the users aware of the existence of the different available content types (Contact, Customer, and Supplier) when they are creating new items, we need to explicitly enable content types on the list definition, setting the EnableContentTypes attribute to a value of TRUE. There are many other attributes available for the List definition element; Table 3-4 shows some of them.

The main child element of List is the MetaData element, which wraps all the other elements in the Schema.xml file.

One of the main child nodes of MetaData is the ContentTypes element. This element declares the entire list of content types referenced by the current list definition. The ContentTypes section of metadata for the sample list definition declares the ContentTypes element for the custom Contacts list.

<ContentTypes>
  <ContentType
    ID="0x0100A60F69C4B1304FBDA6C4B4A25939979F"
    Name="DevLeapContact"
    Group="DevLeap Content Types"
    Description="Base Contact of DevLeap"
    Inherits="TRUE" Version="0" Hidden="TRUE">
    <FieldRefs>
      <FieldRef ID="{fa564e0f-0c70-4ab9-b863-0177e6ddd247}"
                Name="Title" DisplayName="Full name" Required="TRUE" />
      <FieldRef ID="{C7792AD6-F2F3-4f2d-A7E5-75D5A8206FD9}"
                Name="DevLeapContactID" DisplayName="Contact ID"
                Required="TRUE" />
      <FieldRef ID="{A8F24550-55CD-4d34-A015-811954C6CE24}"
                Name="DevLeapCompanyName" DisplayName="Company Name" />
      <FieldRef ID="{149BF9A1-5BBB-468d-AA35-91ACEB054E3B}"
                Name="DevLeapCountry" DisplayName="Country" />
    </FieldRefs>
  </ContentType>
  <ContentType
    ID="0x0100A60F69C4B1304FBDA6C4B4A25939979F01"
    Name="DevLeapCustomer"
    Group="DevLeap Content Types"
    Description="Customer of DevLeap"
    Inherits="TRUE" Version="0">
    <FieldRefs>
      <FieldRef ID="{AC689935-8E8B-485e-A45E-FF5A338DD92F}"
                Name="DevLeapCustomerLevel" Required="TRUE" />
    </FieldRefs>
    <XmlDocuments>
      <XmlDocument NamespaceURI=
        "http://schemas.microsoft.com/sharepoint/v3/contenttype/forms">
        <FormTemplates xmlns=
          "http://schemas.microsoft.com/sharepoint/v3/contenttype/forms">
          <Display>DevLeapCustomerDisplay</Display>
          <Edit>DevLeapCustomerEdit</Edit>
          <New>DevLeapCustomerNew</New>
        </FormTemplates>
      </XmlDocument>
    </XmlDocuments>
  </ContentType>
<ContentType
    ID="0x0100A60F69C4B1304FBDA6C4B4A25939979F02"
    Name="DevLeapSupplier"
    Group="DevLeap Content Types"
    Description="Supplier of DevLeap"
    Inherits="TRUE" Version="0">
    <FieldRefs>
      <FieldRef ID="{A73DE518-B9B9-4e8d-9D94-6099B4603997}"
                Name="DevLeapSupplierAccount" Required="TRUE" />
    </FieldRefs>
  </ContentType>
</ContentTypes>

The ContentTypes section of metadata for the sample list definition defines all the content types already defined in the previous section, repeating their IDs to link these copies to the original definitions. Why repeat these declarations instead of simply referencing them in some way—such as by just linking their IDs, for example? During a content type’s lifetime, its structure might change. To prevent and avoid any data loss, SharePoint copies content type definitions inside the list definitions that use them. Doing so preserves data models and data instances even if someone later changes them. Imagine what would happen if you had a simple content type reference rather than a copy; if you were to provision a Customer content type and use it in a custom list, then a few months later, when you have thousands of customer instances in your list, you delete a column from the Customer content type—or worse, you delete the entire content type! Having a complete copy of the content type definition allows SharePoint to maintain your data, even when the original content type changes or is removed.

On the other hand, whenever you want to make a change to one of your provisioned content types and you want that change applied to every instance in a site collection, you need to explicitly force the update through the browser-based content type administration page, through code using the Server Object Model, or by manually updating any references in the provisioned XML files, including the Schema.xml files for list definitions.

The ContentTypes section of metadata for the sample list definition defines all three content types (Contact, Customer, and Supplier) and declares the base Contact as hidden, which forces users to explicitly create Customer or Supplier instances.

Another child of MetaData is the Fields element. It defines the list-level columns used to store metadata of item instances. These list-level columns are almost the same as the site columns defined in the first section of this chapter. Once again, their definitions are duplicated rather than referenced, and for the same reason: to support changes of the models without data loss during the site columns’ lifetimes. The Fields section of the list definition contains all the columns used by any of the content types declared in the same Schema.xml file. The Fields section of the MetaData element for the sample list definition shows the Fields element declared for the custom Contacts list.

<Fields>
  <Field ID="{c7792ad6-f2f3-4f2d-a7e5-75d5a8206fd9}"
         Name="DevLeapContactID"
         StaticName="DevLeapContactID"
         DisplayName="Contact ID"
         Type="Text"
         Group="DevLeap Columns"
         Sortable="TRUE" />
  <Field ID="{a8f24550-55cd-4d34-a015-811954c6ce24}"
         Name="DevLeapCompanyName"
         StaticName="DevLeapCompanyName"
         DisplayName="Company Name"
         Type="Text"
         Group="DevLeap Columns"
         Sortable="TRUE" />
  <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>
  <Field ID="{ac689935-8e8b-485e-a45e-ff5a338dd92f}"
         Name="DevLeapCustomerLevel"
         StaticName="DevLeapCustomerLevel"
         DisplayName="Customer Level"
         Type="Choice"
         Group="DevLeap Columns">
    <Default>Level C</Default>
    <CHOICES>
      <CHOICE>Level A</CHOICE>
      <CHOICE>Level B</CHOICE>
      <CHOICE>Level C</CHOICE>
    </CHOICES>
  </Field>
  <Field ID="{a73de518-b9b9-4e8d-9d94-6099b4603997}"
         Name="DevLeapSupplierAccount"
         StaticName="DevLeapSupplierAccount"
         DisplayName="Supplier Account"
         Type="User"
         Group="DevLeap Columns"
         Sortable="TRUE" />
</Fields>

Just as with the ContentTypes section, the Fields section is simply a wrapper for the copies of all the previously defined site columns. Notice that the ID values for the site columns are the same as those of the global site columns, serving to keep the global site columns linked to the local list-level columns.

Figure 3-5 shows how the List Settings page of a list based on the custom Contacts list definition looks in a web browser. Note that all three content types and all the list-level columns are present.

Figure 3-5. The List Settings page of a list instance based on the custom Contacts list definition.

Just after the Fields section comes the Views element, which is a child of MetaData. This section is really interesting because it is where you define the views on data that will be available to the end users in the web browser. Each View element, which is a child of Views, defines a data view declaring some configuration attributes (illustrated in Table 3-5).

The View element also allows you to declare some other configuration details using child elements. The default View definition for the sample list shows the default view definition for the list of contacts.

<View BaseViewID="1" Type="HTML"
      WebPartZoneID="Main"
      DisplayName="$Resources:core,objectiv_schema_mwsidcamlidC24;"
      DefaultView="TRUE" MobileView="TRUE"
      MobileDefaultView="TRUE"
      SetupPath="pagesviewpage.aspx"
      ImageUrl="/_layouts/images/generic.png"
      Url="AllItems.aspx">
  <Toolbar Type="Standard" />
  <RowLimit Paged="TRUE">50</RowLimit>
  <ViewFields>
    <FieldRef Name="Attachments">
    </FieldRef>
    <FieldRef Name="LinkTitle">
    </FieldRef>
  </ViewFields>
  <Query>
    <OrderBy>
      <FieldRef Name="ID">
      </FieldRef>
    </OrderBy>
  </Query>
  <XslLink>main.xsl</XslLink>
  <JSLink>clienttemplates.js</JSLink>
</View>

The default View definition for the sample list declares a BaseViewID with a value of 1, and specifies that this view will be the default (DefaultView), not only for classic web browsers, but also for mobile devices (MobileDefaultView). The URL to access the view will be AllItems.aspx, and this page will be based on the SetupPath file pagesviewpage.aspx filling out the WebPartZone control whose ID is Main.

The child elements of the View tag in The default View definition for the sample list inform SharePoint to use the Standard value for the toolbar. The maximum number of rows (RowLimit) is set to return a value of 50, enabling paging.

After these configuration elements, The default View definition for the sample list defines some other elements that determine the data to show, declaring a Query element to filter and sort data, and a set of ViewFields elements to show, as well as some optional grouping rules. The Query element is simply a Collaborative Application Markup Language (CAML) query that defines the values to extract from the source list, the ordering rule, and which values will be shown in the current view. For example, The default View definition for the sample list queries all the items in the list, sorting them by the value of their ID fields.

Another important child section of the View element is the ViewFields element, which declares the fields to show in the resulting view. These fields are referenced by their internal names, using a specific FieldRef element.

The last child elements in the View are the XslLink and JsLink elements. Since SharePoint 2010, SharePoint can render views using XSLT transformations. The XslLink element specifies the path to the XSLT file used to render the view. This XSLT file path is relative to the folder SharePoint15_RootTEMPLATELAYOUTSXSL. Moreover, starting from SharePoint 2013, the JsLink element allows declaring a JavaScript file to include and use for rendering the view.

As an alternative to providing an explicit XSLT file path, you can use an Xsl element to simply declare the XSLT transformation inside the Schema.xml file. Because you may want to reuse the XSLT transformation, however, a better choice is to reference an external file. This is especially useful when you are developing a full-trust solution. The capability to define the XSLT transformation inside the Schema.xml file is provided for those situations, such as for sandboxed solutions and SharePoint apps, when you want to avoid copying files to the file system of the target SharePoint farm.

The Forms element is another important configuration section for the list definition, as shown in The Forms configuration section of the custom Contacts list definition.

<Forms>
  <Form Type="DisplayForm"
  Url="DispForm.aspx" SetupPath="pagesform.aspx" WebPartZoneID="Main" />
  <Form Type="EditForm"
  Url="EditForm.aspx" SetupPath="pagesform.aspx" WebPartZoneID="Main" />
  <Form Type="NewForm"
  Url="NewForm.aspx" SetupPath="pagesform.aspx" WebPartZoneID="Main" />
</Forms>

The Forms element contains a set of Form elements that declare the forms available to the end user. Each Form element requires a Type attribute that takes one of the following values:

Every form also requires a URL where it can be accessed. Forms might include an optional SetupPath attribute from which to load the ASPX page model, as well as a WebPartZoneID attribute, which specifies the ID of the Web Part zone used to load the rendering control of the form. As an alternative to the SetupPath attribute, you could have a Path attribute, which defines a physical file system path relative to the _layouts folder for a template file, and a Template attribute, which specifies the name of the template to use. You can also use CAML syntax to define the template for the body, buttons, opening section, and closing section of each of these forms, using these specific child nodes of the Form element: ListFormBody, ListFormButtons, ListFormClosing, and ListFormOpening.

The last configuration section shown is the Validation element. This element, introduced with SharePoint 2010, supports defining validation rules that can apply to each item of the list. Declaring a sample validation rule for the custom Contacts list definition items shows how to declare a custom validation rule together with a validation error message that end users will see if validation fails.

<Validation Message="Please check your data, there is something wrong!">
      =Title<>"Blank"
</Validation>

The validation rule forces the items to have a Title field with a value not equal to Blank. Notice that list-level validation rules work properly only with fields shared by all the content types of the list. If you enforce a rule against a field that is not defined in all the content types of the list, then your rule will always throw an error when applied to the wrong content types. For example, if you define a rule at the list level for the DevLeapCustomerLevel field of the Customer content type, you will not be able to add or update any Supplier instances, because the DevLeapCustomer field is not present in the Supplier content type. In such cases, you should instead define the validation rule at the site column level.

ListTemplate is the feature element file that declares all the deployment properties needed to provision the list definition. It must be provisioned into a custom feature together with the Schema.xml file. The ListTemplate feature element for the sample Contacts list definition shows the ListTemplate for the sample Contacts list definition.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <ListTemplate
        Name="DevLeapContacts"
        Type="10001"
        BaseType="0"
        OnQuickLaunch="TRUE"
        SecurityBits="11"
        Sequence="410"
        DisplayName="DevLeap Contacts"
        Description="A list of Contact for DevLeap"
        Image="/_layouts/images/dlcon.png"/>
</Elements>

The Type attribute is the most important attribute in the ListTemplate element. Type takes an integer value that should be unique at the site collection level. The code sample uses a value of 10001 to avoid overlapping with values of out-of-the-box list templates. In general, you should use a large integer value to avoid overlapping with SharePoint. Consider that values in the range between 100 and 1200 are already taken, and developers should allocate numbers greater than 10000. The uniqueness of this attribute allows you to define custom UI extensions that will target the entire set of lists with that Type value.

The other attributes are straightforward. The BaseType attribute states the base type for the current list definition. The Name attribute represents the internal name of the list, and the DisplayName is the text shown to end users, together with the Description and the Image. You can load the values of these descriptive attributes from external resource strings to provision list definitions in a multilanguage environment. The OnQuickLaunch Boolean attribute value controls whether SharePoint shows any instance of the list in the Quick Launch menu. You can also provision a list instance through a custom feature of type ListInstance, which will be explained in Chapter 4.

Finally, the SecurityBits attribute defines the security behavior of the list. This is a two-digit string, where the first digit controls whether users can read all items (1) or only their own items (2). The second digit defines edit access permissions. The possible values are

For example, a value of 22 for the SecurityBits attribute means that users can see and edit only their own items, while the default value of 11 means that users can see and edit all the items in the list.

Just as you can define content types with Visual Studio 2012 and its designers, you can also define basic lists. In fact, whenever you add an item of type List to a SharePoint project, regardless of whether it is a solution or an app, you are provided with a graphical designer that allows you to design fields, content types, and views, and provide descriptive information for the list. First, you are prompted with the wizard shown in Figure 3-6. Here you can specify the name of the target list and create a customizable list definition based on a basic content type or a list instance based on an existing list definition.

Figure 3-6. The wizard for creating a new list in a SharePoint solution or app.

After you complete the page and click Finish, you can configure the resulting item through a specific designer. If you created a new list definition, you will have access to a designer with three tabs, for configuring fields, content types, and views of the custom list definition. Figure 3-7 shows the designer for this chapter’s example Contacts list, displaying the columns defined in the schema of the list definition.

Figure 3-7. Configuring the fields of a custom list definition within Visual Studio 2012.

The designer also provides also a Content Types button; click it to open the dialog box shown in Figure 3-8. Here you can determine the content types associated with the current list template.

Figure 3-8. The dialog box for configuring the content types associated with a list definition.

Once you have defined the content types and the columns, you can determine the views for the custom list definition. Click the Views tab to access the controls shown in Figure 3-9.

Figure 3-9. Determining the views for the custom list definition.

Whether you are defining an instance of your custom list definition or simply declaring an instance of an already existing list definition, you can configure some descriptive aspects of the target list using the List tab, shown in Figure 3-10.

Figure 3-10. The List tab for configuring the list instance descriptive parameters.

By default, Visual Studio 2012 always defines a list instance together with the list definition. If you do not want to provision a list instance, you can comment the code of the ListInstance element created within the Elements.xml file available inside the list item in the Visual Studio project outline.