hen you’re trying to change the way that SharePoint appears and operates to something more in-line with what your organization needs, you’ll find that modifying the site definition to change the appearance is a good first start. As you get more advanced, you may decide that you need to add functionality to the SharePoint list editing tools, or make other changes that impact how the user edits data in SharePoint. Ultimately, however, pushing branding or your additional tools down and into the site whenever a list is created means changing the list definition.
While you can create site templates with changes bundled in to implement your specific branding and tools, when a new list is created, it is created using the rules stored in the list definition. If your branding and tools changes aren’t in that list definition, then the new list that the user creates won’t follow your branding or tools strategy.
List definitions also allow you to define new fields in a list?but not just new fields to store data, which can be done from the user interface, but also the ability to define new types of fields that behave in new ways. For instance, it is possible to create a variant of the links list that allows you to specify whether you want the links to open up in a new window or not. This additional flexibility can be essential to implementing enhanced list types.
This article explains how list definitions work, explores their relationship to site definitions, and shows you both how to change the appearance and the structure of the list.
How Do List Definitions Work?
List definitions are actually a part of site definitions. If you look under the standard STS site definition in SharePoint (C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions60TEMPLATE1033STS), you’ll find a LISTS directory. This directory contains a set of list definitions. These list definitions are referenced from the XMLONET.XML file in the site definition. Under the
Connecting a list definition to a site definition is the process of creating the list definition, copying it to the LISTS directory, adding the appropriate
In order to walk through the examples in this article, it’s advised that you create a new site definition to work with. The article “SharePoint Site Definitions: Why You Need Them and How to Use Them” shows you how to do this. Once you’ve done that, it’s further advised that you create a new list definition based on one of the list definitions that already exist in the site definition. To create that new list definition, follow these steps:
- Copy one of the directories under the site defintion’s LISTS directory to a new name. For example, copy CONTACTS to TESTCONT.
- Open the ONET.XML in the .XML directory of the site definition.
- Locate the
- Copy the
node underneath the node that corresponds to the list you copied. The Name attribute directly maps to the directory name that you copied (if you copied CONTACTS, it’s the ninth node in the list).
- Paste a copy of this node at the end of the
- Change the Name attribute to match your new directory name. In the case of this example, TESTCONT.
- Change the DisplayName attribute to something descriptive. In this example, that might be “Test Contacts.”
- Change the Type attribute to a unique number. In this case, 201 should work. The 200 series of numbers is unused so it’s a good place to start with numbering your custom list definitions.
- Save the ONET.XML file.
- Reset IIS (Start?>Run?>IISRESET)
- Create a new site and verify that you can create a new list of type “Test Contacts.”
Now that you’ve created new copies of a site definition and a list so that your changes won’t break anything, it’s time to dig into the heart of the list definition. Internally, a list definition consists of a SCHEMA.XML file and a set of .aspx pages that represent the display, new, update/edit, and default views for the list. These files are referred to in the SCHEMA.XML so that, when the list is created, SharePoint creates links to these pages in the database.
The SCHEMA.XML has the basic format shown in Figure 1.
|Figure 1. The SCHEMA.XML File: This shows the SCHEMA.XML file’s basic structure.
SCHEMA.XML has two basic sections. The first section is the
Controlling the Appearance of List Pages
There are two parts to customizing the appearance of list pages. They are the same two components you use when modifying a Web part page in a site definition. First, you can modify the page’s ASPX file. In a site definition, this file has the name default.aspx. In a custom list, you have four or more pages to be concerned with. Each list has a form for: listing the entries, displaying a single entry, creating a new entry in the list, and editing an entry in the list. However, the process for these pages isn’t any different than for the default.aspx page in the root of the site definition. It’s all about manipulating the ASP.NET code (if you read “A Sensible Framework for SharePoint Intranet Navigation, you may want to add a few new zones on your pages?including your list pages?so that you have more flexibility in the appearance).
The second part of the process, which involves getting your custom Web parts to appear on the page along with the existing controls that create the user interface, involves modifying the schema and adding a few nodes.
By default, SharePoint will place a ListFormWebPart on each of the form pages. The FormsForm node itself indicates that the ListFormWebPart should appear. However, in addition to the ListForm Web part, you can also add other Web parts. One example of this, in Windows SharePoint Services’ out of the box definitions, is in the ISSUE list in the STS definition. It includes a FormsFormWebParts node that, in turn, contains two
Another node you can add to the FormsFormWebParts node of the SCHEMA.XML is an AllUsersWebPart node. This node can contain any Web part you want to add to the page. One good use of this is to add text above an entry form to help explain the purpose behind filling out the information or how to fill out the fields. For example, you’d create some simple instructions for filling out the contacts record by adding the content editor Web part to the default page for the site, entering the text you want, and then exporting it and adding it to SCHEMA.XML. In the interest of brevity, the DWP added at the top of the contact’s new entry form is available here.
Integrating this into the SCHEMA.XML is done by the following procedure. This example uses the TESTCONTSCHEMA.XML:
- Locate the node or
node of the form or view to which you want to add the Web part. For this example, locate the third node in the ListMetaDataForms path of the XML. This node should have a type of NewForm.
- Add a
node under this node. In some views or forms this node may already exist. This is fine. For this example, however, the node is missing.
- Add a new
node under the new node.
- Add two attributes: a WebPartZoneID attribute with a value of “Main” and a WebPartOrder attribute with a value of “0”. These tell the Web part where to go on the page. Note that this information is also included in the DWP file itself.
- Under the
, add a CDATA node which is everything between the quotes here: ““.
- Into this CDATA node, add the contents of the DWP file minus the first line which identifies the DWP file as XML.
- Remove the wrapper from around the
node in the content editor Web part. XML doesn’t allow for nested CDATA nodes, so the inclusion of a CDATA node in the DWP will cause problems.
- Save the file.
- Perform an IISRESET.
- Create a new list of the type that you were working on and verify that the Web part appears. Figure 2 shows what a new “test” list looks like.
|Figure 2. A New “Test”: The results of adding a content editor Web part to the new form of the contacts list.
If you need multiple Web parts or you want to add a Web part to every form, you simply repeat the process for any Web part that you want to add. The real power of this technique is when you couple it with removing all of the built in Web controls that are on the pages. They can be easily wrapped and added as Web parts to Web part zones. See the article “Wrapping Web Controls in a SharePoint Web Part” for how to wrap a Web control?like the SharePoint Web controls (you can also look at the blog post “Picking up the SharePoint Services Navigation Controls for a specific example and code). In essence, you make the entire site definition driven by Web parts so that you can change the entire appearance of the Web site in one fell swoop when you’re ready later. Check out the article, “A Sensible Framework for SharePoint Intranet Navigation,” to learn more about this approach.
Changing the Structure of the List
One of the beautiful things about a list definition is that you can define a rich set of predefined lists that already contains the fields and views that you need to solve a problem. Most of the list formats that SharePoint offers, with the notable exception of the issues list, are little more than a custom list defined with a set of predefined fields that make sense for a specific purpose. The contacts list is, as the name suggests, good for maintaining a list of contacts. The links list is good for capturing links, the tasks list is good for capturing tasks, and so on.
For this article’s purposes, you’re going to further modify the contacts list to add a new field. This new field will be designed to capture the type of the contact in the contact list. For instance, the contact can be: an acquaintance, a friend, a colleague, a competitor, a vendor, a customer, or some other kind of contact. Before you can add this field to the list definition, you have to create the CAML fragment that represents the field.
Because this is a choice field, the values are a bit more complicated. The basic format for a field is a single
The three basic attributes required for a
- Name: This is the InternalName used in SharePoint. It must be unique. The name is only seen by developers working on code that works with the list.
- Display Name: This is the name that users see for the field. It is displayed in data entry screens and as the header for views of the list.
- Type: This is the fundamental type of the field. For instance, Text, Note, URL, and Choice are all different fundamental types of fields.
When using a choice field, in addition to these attributes, you’ll also need the Format attribute to indicate the form of choice (DropDown), and the FillInChoice attribute which indicates whether the user can type in a response. Putting this all together, the CAML fragment for the field is:
Acquaintance Acquaintance Friend Colleague Competitor Vendor Customer Other
With the CAML fragment in hand, you can add the field to the list definition. The following steps show you how to add a field to a list definition:
- Open the SCHEMA.XML.
- Locate the ListMetaDataFields node.
- Before the closing tag of the
node, add the new node for the field that you want to add.
- Save the file.
- Perform an IISRESET.
- Create a new list from the list definition and verify that the field is present.
A Flexible Framework for Customization
SharePoint provides a extremely flexible framework for customizing the way that your lists look and work. You can change the structure of the list pages much like you can change the structure of the main Web part pages in a site definition. You can also control the Web parts on the page just as you can in a site definition. Further, you can control the types of fields that are created when the list is created. This means that you can develop nearly every kind of list that you can dream up.