Microsoft® SharePoint® 2013 Developer Reference: Data Provisioning

List definitions

Now that you have defined your content types, you are ready to use them in a real list of contacts, comprising customers and suppliers. In fact, generally, whenever you define a set of custom content types, you also define one or more list definitions that use these content types. A list definition is simply a formal representation, using an XML schema, of a list data model from which you are able to create one or more instances of items corresponding to that model.

In SharePoint, a list definition is a combination of two files: a Schema.xml file, which defines the data structure and configuration of the list definition model, and a feature element file that describes the ListTemplate, which defines the information required for provisioning and deploying the list definition model.

List schema file

The list schema file is an XML document that describes all the metadata for the list data structure. The following are the main areas of the Schema.xml file for a list definition:

• Content Types This section defines the content types that will be available within the list definition.
• Fields This section declares the list-level site columns, which correspond to the entire set of site columns referenced by all the content types associated with the list definition.
• Views This section defines the views that will be available to the end user for navigating among the items of list template instances.
• Forms This section declares the ASPX pages that will be provided to the end user to add, display, and update items of a list instance based on the current list definition.
• Validation This section defines the validation rules for list items.
• Toolbar This section declares the type of toolbar that must be provided in the browser interface.

In addition to the preceding list, the complete XML schema contains some other elements as well. Listing 3-8 shows an excerpt from a Schema.xml file that describes a list definition, together with these main sections.

LISTING 3-8 Excerpt of a list definition schema file

<?xml version="1.0" encoding="utf-8"?>
<List xmlns:ows="Microsoft SharePoint"
    Title="DevLeapContacts"
    FolderCreation="FALSE"
    Direction="$Resources:Direction;"
    Url="Lists/DevLeapContacts"
    BaseType="0"
    EnableContentTypes="TRUE"
    xmlns="http://schemas.microsoft.com/sharepoint/">
    <MetaData>
        <ContentTypes>
        <!-- Here are referenced the content types -->
        </ContentTypes>
        <Fields>
        <!-- Here are declared the list-level site columns -->
        </Fields>
        <Views>
        <!-- Here are defined the views -->
        </Views>
        <Forms>
        <!-- Here are declared the forms used to add, display, update items -->
        </Forms>
        <Validation>
        <!-- Here are declared the validation rules for list items -->
        </ Validation >
        <Toolbar />
        <!-- To define what kind of toolbar to use in the Web browser UI  -->
    </MetaData>
</List>

The List element

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 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

• 0 Generic/Custom List
• 1 Document Library
• 2 Not used, may be reserved for future use
• 3 Discussion Forum (deprecated, use 0 instead)
• 4 Vote or Survey
• 5 Issues List

For example, Listing 3-8 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 Listing 3-8, 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.

Table 3-4 Some of the main attributes for the List element of a Schema.xml list definition file

Attribute	Description
DisableAttachments	Optional Boolean value to disable attachments on the list.
EnableMinorVersions	Optional Boolean value that controls versioning with major and minor version of items.
ModeratedList	Optional Boolean value to enable content approval on inserted items.
PrivateList	Optional Boolean value to specify that the list is private.
VersioningEnabled	Optional Boolean value to enable versioning on the list. This value can be changed when creating a list instance.

The MetaData element

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 Listing 3-9 declares the ContentTypes element for the custom Contacts list.

LISTING 3-9 The ContentTypes section of metadata for the sample list definition

<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>

Listing 3-9 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.

Listing 3-9 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. Listing 3-10 shows the Fields element declared for the custom Contacts list.

LISTING 3-10 The Fields section of the MetaData element for the sample list definition

<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.

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).

Table 3-5 Some of the main attributes for the View element of a Schema.xml list definition file

Attribute	Description
Type	The type of view. Type can be HTML, Chart, or Pivot.
BaseViewID	An Integer value that declares the ID of the view. BaseViewID must be unique within a Schema.xml file.
Url	The public URL to access the view from the browser.
DisplayName	The name of the view in the web browser.
DefaultView	A Boolean value that declares if the view is the default view for the current list.
MobileView	A Boolean value that specifies if the current view has to be made available to mobile devices.
MobileDefaultView	A Boolean value that declares if the view, enabled for mobile access, is the default view for mobile devices.
SetupPath	Defines the site-relative path to the ASPX file corresponding to the current view model. It allows provisioning a custom page for the current view.
WebPartZoneID	A string that declares the ID of the WebPartZone control where the current view will be loaded, within the ASPX Web Part page.

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

Listing 3-11 The default View definition for the sample list

<View BaseViewID="1" Type="HTML"
      WebPartZoneID="Main"
      DisplayName="$Resources:core,objectiv_schema_mwsidcamlidC24;"
      DefaultView="TRUE" MobileView="TRUE"
      MobileDefaultView="TRUE"
      SetupPath="pages\viewpage.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>

Listing 3-11 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 pages\viewpage.aspx filling out the WebPartZone control whose ID is Main.

The child elements of the View tag in Listing 3-11 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, Listing 3-11 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, Listing 3-11 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_Root\TEMPLATE\LAYOUTS\XSL. 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 Listing 3-12.

LISTING 3-12 The Forms configuration section of the custom Contacts list definition

<Forms>
  <Form Type="DisplayForm"
  Url="DispForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
  <Form Type="EditForm"
  Url="EditForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
  <Form Type="NewForm"
  Url="NewForm.aspx" SetupPath="pages\form.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:

• DisplayForm The form to display a list item
• EditForm The form to edit an existing list item
• NewForm The form to add a new list item

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. Listing 3-13 shows how to declare a custom validation rule together with a validation error message that end users will see if validation fails.

LISTING 3-13 Declaring a sample validation rule for the custom Contacts list definition items

<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.

Defining a custom view

When defining custom list definitions, you’ll frequently want to declare some custom views that correspond to the business rules of your data model. For example, the sample model could feature one view that shows only customers and another that shows only suppliers. This section demonstrates how to define the former view; the latter’s definition will be almost identical.

First, define a new View element under the Views element of the Schema.xml file. The new view will have a unique BaseViewID; in this example it will be 2. The DisplayName will be All Customers, the Type will be HTML, and the Url will be AllCustomers.aspx. All the other attributes values of the View element are trivial. You can see the complete definition of this view in Listing 3-14.

LISTING 3-14 Defining a custom view for a custom Contacts list definition

<View BaseViewID="2" Type="HTML"
      WebPartZoneID="Main"
      DisplayName="All Customers"
      DefaultView="FALSE" MobileView="TRUE"
      MobileDefaultView="FALSE"
      SetupPath="pages\viewpage.aspx"
      ImageUrl="/_layouts/images/generic.png"
      Url="AllCustomers.aspx">
  <Toolbar Type="FreeForm" />
  <XslLink>Contacts_Main.xsl</XslLink>
  <RowLimit Paged="TRUE">20</RowLimit>
  <ViewFields>
    <FieldRef Name="Attachments">
    </FieldRef>
    <FieldRef Name="LinkTitle">
    </FieldRef>
    <FieldRef Name="DevLeapContactID">
    </FieldRef>
    <FieldRef Name="DevLeapCompanyName">
    </FieldRef>
    <FieldRef Name="DevLeapCountry">
    </FieldRef>
    <FieldRef Name="DevLeapCustomerLevel">
    </FieldRef>
  </ViewFields>
  <Query>
    <Where>
      <Eq>
        <FieldRef Name="ContentType" />
        <Value Type="Text">DevLeapCustomer</Value>
      </Eq>
    </Where>
    <OrderBy>
      <FieldRef Name="ID">
      </FieldRef>
    </OrderBy>
  </Query>
</View>

There are some areas of interest in this view definition. First, the code defines a Query to filter only items with a ContentType value of DevLeapCustomer and orders the result by the item ID. Then it references all the fields of the Customer content type, defining a set of FieldRef elements within the ViewFields element. Lastly, a custom XSLT transformation is defined for rendering the custom view. SharePoint will search for this XSLT file, Contacts_Main.xsl, in the SharePoint15_Root\TEMPLATE\LAYOUTS\XSL folder. The file has to be placed in that folder using the solution-provisioning tools provided by Visual Studio 2012 to create a full-trust solution. (For further details, see Chapter 4) Otherwise, as you have already seen, you can define the XSLT code directly in the View schema definition, inside an Xsl element.

The XSLT file you reference or define in the View definition is a common XSLT transformation that will receive a wide range of parameters at run time from SharePoint. In the XSLT code, for example, you can access the XmlDefinition variable, which provides the XML definition of the current View. To define an XSLT for a custom view, you must provide an XSLT template that matches the BaseViewID of the targeted view. For the Contacts example, the following template was defined:

<xsl:template match="View[@BaseViewID="2"]" mode="full">
  <!-- Here is our custom XSLT transformation -->
</xsl:template>

The XSLT also receives a parameter named Rows that contains all the items to be rendered. Listing 3-15 shows an excerpt of the XML content of the Rows parameter. You can read it simply by using an XSLT template that copies the source content with an <xsl:copy-of /> element.

LISTING 3-15 The content of the Rows parameter provided to a custom XSLT for rendering a list view

<Rows>
  <Row ID="1" PermMask="0x7fffffffffffffff" Attachments="0"
  Title="Customer 01" FileLeafRef="1_.000" FileLeafRef.Name="1_"
  FileLeafRef.Suffix="000" FSObjType="0"
  Created_x0020_Date="1;#2010-02-13 16:24:12" Created_x0020_Date.ifnew="1"
  FileRef="/sites/SP2010DevRef/Lists/Test/1_.000"
  FileRef.urlencode="%2Fsites%2FSP2010DevRef%2FLists%2FTest%2F1%5F%2E000"
  FileRef.urlencodeasurl="/sites/SP2010DevRef/Lists/Test/1_.000"
  File_x0020_Type=""
  HTML_x0020_File_x0020_Type.File_x0020_Type.mapall="icgen.gif||"
  HTML_x0020_File_x0020_Type.File_x0020_Type.mapcon=""
  HTML_x0020_File_x0020_Type.File_x0020_Type.mapico="icgen.gif" ContentTypeId
="0x0100A60F69C4B1304FBDA6C4B4A25939979F010044C1B948A829E64CBD49ED3F42A868C7"
DevLeapContactID="C01"DevLeapCompanyName="Company 01"
  DevLeapCountry="Italy" DevLeapCustomerLevel="Level C"
  ContentType="DevLeapCustomer"></Row>
  <!—And many other rows here, one for each list item to show -->
</Rows>

Listing 3-15 illustrates that the Rows parameter provides each row along with its data columns, specified as attributes of a Row element. To output the content of the rows, you simply need to retrieve the values of these attributes, placing them inside the proper HTML elements to adhere to the graphical layout that you need to render.

However, many SharePoint developers do not like writing XSLT files, because XSLT is inflexible (although very powerful) from a syntax viewpoint. Luckily, starting with SharePoint 2013, you have the option to provide a custom JavaScript file through the JsLink child element of the View element, in order to move rendering templates into client-side code. Generally speaking, this technique is known as client-side rendering (CSR). Listing 3-16 uses this new technique to define a custom view.

LISTING 3-16 A custom view definition for the custom Contacts list definition using JavaScript rendering

<View BaseViewID="3" Type="HTML"
      WebPartZoneID="Main"
      DisplayName="All Customers via JS"
      DefaultView="FALSE" MobileView="TRUE"
      MobileDefaultView="FALSE"
      SetupPath="pages\viewpage.aspx"
      ImageUrl="/_layouts/images/generic.png"
      Url="AllCustomersViaJS.aspx">
  <Toolbar Type="FreeForm" />
  <XslLink>main.xsl</XslLink>
  <JsLink Default="TRUE">~site/Scripts/CustomCustomersView.js</JsLink>
  <RowLimit Paged="TRUE">20</RowLimit>
  <ViewFields>
    <FieldRef Name="Attachments">
    </FieldRef>
    <FieldRef Name="LinkTitle">
    </FieldRef>
    <FieldRef Name="DevLeapContactID">
    </FieldRef>
    <FieldRef Name="DevLeapCompanyName">
    </FieldRef>
    <FieldRef Name="DevLeapCountry">
    </FieldRef>
    <FieldRef Name="DevLeapCustomerLevel">
    </FieldRef>
  </ViewFields>
  <Query>
    <Where>
      <Eq>
        <FieldRef Name="ContentType" />
        <Value Type="Text">DevLeapCustomer</Value>
      </Eq>
    </Where>
    <OrderBy>
      <FieldRef Name="ID">
      </FieldRef>
    </OrderBy>
  </Query>
</View>

In Listing 3-16, shows the JsLink element (highlighted in bold) configured as the default (Default="TRUE”) rendering template. SharePoint will look for the JavaScript file at a URL relative to the current site collection, because of the ~site token at the very beginning of the URL. You can deploy the JavaScript code of the CustomCustomerView.js file to the target site simply working at the website level, using a sandboxed solution or an app deployment process. In the JavaScript code, you can reference the Client Object Model of SharePoint in order to query the current list configuration, as well as the items to render. This technique is extremely powerful. While provisioning lists for Office 365, for example, you can use this technique to move all the rendering logic to the client side, using jQuery or CSS rendering templates. With its XSLT and JavaScript support, SharePoint opens up some great business opportunities; because it gives you the capability to display fully customized rendering of list views, your solutions can support fully customized template layouts, even in extreme web content management solutions.

The ListTemplate definition file

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. Listing 3-17 shows the ListTemplate for the sample Contacts list definition.

LISTING 3-17 The ListTemplate feature element 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

• 1 Users can edit any item.
• 2 Users can edit only their own items.
• 4 Users cannot edit items.

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.

Working with lists in Visual Studio 2012

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.

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.

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.

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.

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.

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.