Add a Custom List to SharePoint – a foray into CAML

**** This article is for SharePoint 2003 ****
This article covers how to create a basic custom site definition, how to create a basic custom list definition, and how to display that custom list on the default page at site creation.

The instructions for each can stand alone, or you can use all steps in tandem.

These changes DO REQUIRE RESETTING OF IIS ON THE SERVER. So I recommend you do these changes first on a development server or a Virtual PC image, then modify your Production files in a scheduled down time or off hours.

 

Table of Contents

  1. Step 1: What exactly do you need to accomplish?
  2. Step 2: Create a new custom site definition
    1. The Definition Copy
    2. The WEBTEMP.XML Copy and Modification
    3. The Results
    4. Technical Resources
  3. Step 3: Create the custom list definition
    1. The Definition Copy
    2. The SCHEMA.XML Modification
    3. Adding the List to the ONET.XML file
    4. The Results
    5. Technical Resources
  4. Step 4: Add the custom list definition to the default page of a new SharePoint site
    1. Adding the List to the ONET.XML file Configuration and Module
    2. The Results
    3. Technical Resources
  5. Technical Resources: Composite List

Step 1: What exactly do you need to accomplish?

If you only need to add a custom list that will be available for creation purposes in all existing and new sites, you are in luck- this isn’t so hard. You can create a new list definition and make it available in the site definition so any user who selects “Create” on the Manage Content screen will see that custom list as an option to create from. You only need Step 3.

If you need to take it a step further and go ahead and create this list and have it display by default on the home page, you need to do a few extra steps and tell your end users that it will only apply to NEW sites created from that site definition, and will not retroactively apply to existing sites based off that site definition. Start below at Step 2.

Step 2: Create a new custom site definition since Microsoft doesn’t support modification of default site definitions

Or we are for demonstration purposes. I leave the selection of which files to modify in your environment up to you. If you already have a site definition in place for use, proceed to Step 3.

How to create a custom site definition (Hey, what is a site definition?)

 

The Definition Copy

The best way to create a custom site definition is to copy an existing default SharePoint site definition. There are so many files and lines of code involved it is much easier to copy and modify than to start from scratch. So first we will pick a default site definition to use as a base for our own custom site definition.

  1. Navigate to the following directory on your SharePoint server:
    Drive:Program FilesCommon FilesMicrosoft Sharedweb server extensions60TEMPLATE1033
  2. Select a default site definition to base your custom one off of. For WSS, select the STS site definition. For Portal, select the site definition that best mirrors your needs. Here is a list of default site definitions. For demonstration purposes lets use STS.
  3. Copy the site definition folder and paste it in the same directory (Drive:Program FilesCommon FilesMicrosoft Sharedweb server extensions60TEMPLATE1033).
  4. Rename the definition to describe the purpose of the definition. Rules for naming:
    • Use UPPERCASE letters for name.
    • For Portals, you must include SPS as the first three letters of the name.

    So for our demo, let’s name it PROJECT.

    The WEBTEMP.XML Copy and Modification

    The WEBTEMP.XML file contains the site definitions that are available on the Template Selection page for site creation. You never want to make modifications to the original WEBTEMP.XML file since upgrades and service packs can potentially overwrite any changes you have made. Instead you create a copy of the WEBTEMP.XML file and append a unique name on the end. At run time the compiler merges all the information in the WEBTEMP*.XML files. So now we need to create our own WEBTEMP.XML file for our custom site definition so it will be available on the Template Selection page.

  5. Navigate to the following directory on your SharePoint server:
    Drive:Program FilesCommon FilesMicrosoft Sharedweb server extensions60TEMPLATE1033XML
  6. Copy the WEBTEMP.XML file and paste it in the same directory (Drive:Program FilesCommon FilesMicrosoft Sharedweb server extensions60TEMPLATE1033XML).
  7. Rename the file by appending a unique name to the end of the existing name. You must keep the “WEBTEMP” as the first part of the name. I would suggest you make this unique name match your new site definition name. So with our demo file, we will name it WEBTEMPPROJECT.XML.
  8. Open your new XML file (WEBTEMPPROJECT.XML) in Notepad, an XML editor or a code editor. I used Visual Studio.
  9. Delete out all the code between the TEMPLATEStags.
  10. Insert the below code in-between the TEMPLATEStags.
    <Template Name=”PROJECT” ID=”10200″>
    <Configuration ID=”0″ Title=”Project Site” TYPE=”0″
    Hidden=”FALSE”
    ImageUrl=”/_layouts/images/stsprev.png”
    Description=”This template provides a project site.”>
    </Configuration>
    </Template>

    Notes about this code:

    TEMPLATE Element

    • The Name attribute must match your site definition folder name. It must match the name exactly and it is case sensitive. Use UPPERCASE.
    • The IDattribute must be unique and greater than 10,000.

      CONFIGURATION Element

    • ID is required and specifies a unique ID for the configuration.
    • Title is the name that appears on the Template Selection page. Your custom site definitions will appear under the default SharePoint list of Team Site, Document Workspace, etc.
    • Type is optional and identifies the configuration with a specific site definition.
    • Hidden specifies whether the site configuration appears as an option on the Template Selection page in SharePoint.
    • ImageURL is the large image you see on the Template Selection page. You can leave this as the default that SharePoint uses, or specify your own file. A way to use this would be to take a screenshot of the final site definition, create an image file suitable for the Template Selection screen, and specify that for this image so when the user is selecting a template upon site creation, they have a visual cue as to which template this one is.
    • Description is the text description that appears under the image on the Template Selection page. The description should describe the purpose or intended use of the template.

    So your resulting code should look like this:

  11. Save the file
  12. Restart IIS.

    The Results

  13. Go to your SharePoint site and create a new site. On the Template Selection page you should see your new site definition listed under Template. Note that when you create the new site, it will look exactly like the default WSS team site, since we have not applied any formatting or list changes to it our site definition yet.

Technical Resources

» Creating a Site Definition from an Existing Site Definition

Step 3: Create the custom list definition

If you are newly joining us here at Step 3, for demonstration purposes we have created a new site definition called PROJECT that is based off the STS site definition.

Now our client has asked us to create a custom list on the PROJECT site for all project managers to track project issues. There are specific fields they want included on this list. In this step we will create this list. An easy way to start this task is to ask or work with the client to first create a custom list on an existing SharePoint site (using the OOB Custom List option on the Create page). This will answer a lot of the attribute questions you will need to know before creating a custom list definition. Some other important information to gather is:

  • Name of the list – this should be generic and not site specific. For our example we will use “Project Issues“.
  • Description for the list – this appears on the Documents & Lists page, the Create page and the expanded view pages of the list. This description will be looked at a lot and should be useful. For our example we will use “Use the Project Issues list to keep track of issues that occur within the project that team members need to address.
  • Determine if they want to allow the end user the ability to delete any of the columns from the list on the site (this won’t effect all the sites, this just determines whether we lock down that column so you can’t delete it on a site by site basis).
  • Determine what column they want the list ordered by. For our example we will use Issue ID.

How to create a custom list definition (I would give you a handy link to what is a list definition, but I can’t find anywhere where MSFT defines it)

 

The Definition Copy

The best way to create a custom list definition is to copy an existing default SharePoint list definition. There are so many files and lines of code involved it is much easier to copy and modify than to start from scratch. So first we will pick a default list definition to use as a base for our own custom list definition.

  1. Navigate to the following directory on your SharePoint server IN your custom or selected site definition:
    Drive:Program FilesCommon FilesMicrosoft Sharedweb server extensions60TEMPLATE1033SITEDEFINITIONLISTS
  2. Select a default list definition to base your custom one off of. For a custom list, select the CUSTLIST list definition. For demonstration purposes lets use CUSTLIST.
  3. Copy the list definition folder and paste it in the same directory (Drive:Program FilesCommon FilesMicrosoft Sharedweb server extensions60TEMPLATE1033SITEDEFINITIONLISTS).
  4. Rename the definition to describe the purpose of the definition. Rules for naming:
    • Use UPPERCASE letters for name.

    So for our demo, let’s name it PROJECTISSUES.

    The SCHEMA.XML Modification

    The SCHEMA.XML file defines the views, forms, toolbar and special fields for lists that are created through the list definition. You never want to make modifications to any original SCHEMA.XML files since changes may break existing WSS sites and upgrades and service packs can potentially overwrite any changes you have made. Instead try to always use custom list definitions.

  5. In your new list definition directory, open the SCHEMA.XML file in Notepad, an XML editor or a code editor. I used Visual Studio.
    Drive:Program FilesCommon FilesMicrosoft Sharedweb server extensions60TEMPLATE1033SITEDEFINITIONLISTSLISTDEFINITION
  6. On line 4 you can personalize this list definition by modifying the Name, Title and Url in the LIST element. Copy the below code and paste it IN PLACE of the existing LISTtag:
    <List xmlns:ows=”Microsoft SharePoint” Name=”ProjectIssues” Title=”Project Issues” Direction=”0″ Url=”Lists/PROJECTISSUES” BaseType=”0″ >

    Lets go over which each attribute does:

    • Name – Required text for the internal name of the list
    • Title – Required text for the generic display name of the list
    • Direction – Required text that specifies the direction of the reading order of the list.
    • Url – Optional URL that specifies the path to the folder in the LISTS directory that contains the ASPX files to which the list definition applies.
    • BaseType – Optional text which can be set to integer or text.
    » LIST Element Syntax and Attributes (print this out or bookmark for your reference)

    So your resulting code should look like this:

     

  7. Each custom list requires a default description. Add the DefaultDescription element within the MetaDataelement.
    <DefaultDescription>Use the Project Issues list to keep track of issues that occur within the project that team members need to address.</DefaultDescription>

    So your resulting code should look like this:

     

  8. We create columns in the custom list by adding FIELD elements. In the first part of the SCHEMA.XML file, on or around line 8 you will see the FIELDS element. Inside of the FIELDS tags we will add FIELD elements. Notice the lack of “S” between the two names.
  9. From our requirements gathering, the client would like the following columns in the custom list:
    • Issue ID – Required numeric field that can’t be deleted
    • Title – Required single line of text field that can’t be deleted
    • Status – Required drop down menu of two choices, Open and Closed, that can’t be deleted.
    • Description – Required multiple lines of text field
    • Date Assigned – Optional date only field

    A FIELD element needs to be added for each needed column. You use attributes to dictate the details and actions of the field.

    Copy the below code and paste it in-between the FIELDS tags:

    <Field Name=”ISSUEID” Type=”Number” DisplayName=”Issue ID” Required=”TRUE” Sealed=”TRUE” />
    <Field Name=”Title” DisplayName=”Title” Required=”TRUE” Sealed=”TRUE” />
    <Field Name=”Status” Type=”Choice” DisplayName=”Status” Required=”TRUE” Sealed=”TRUE”>
    <CHOICES>
    <CHOICE>Open</CHOICE>
    <CHOICE>Closed</CHOICE>
    </CHOICES>
    </Field>
    <Field Name=”Description” Type=”Note” NumLines=”5″ DisplayName=”Description” Required=”TRUE” />
    <Field Name=”DateAssigned” Type=”DateTime” Format=”DateOnly” DisplayName=”Date Assigned” />

    Let’s go over what attributes we have used in the above code.

    • Name – Name of the field that must be unique.
    • Type – Data type of the field. This one is key, it is where you specify the behavior of the column (choice, text, date, attachment, link, etc.).
    • DisplayName – the displayed name for the field. This is the text used for the column heading.
    • Required – an entry for the field is required by the user.
    • Sealed – marks the field as irremovable in the Change Column page.
    • There are a few others mixed in that are necessary for the Type attribute, depending on which Type is being used.
    » FIELD Element Syntax and Attributes (print this out or bookmark for your reference)

    So your resulting code should look like this:

    Note: Within the available FIELD Element Syntax and Attributes you can set a field to be a Lookup. What the attributes do not tell you is that you don’t use the name of the list you want the Lookup field to reference, instead you use the GUID. This will pose a problem if you want this list definition to be included with new site creation because the GUID for lists change with every site. You will have to write a script to read the GUID of the target list and then populate this attribute in order for the Lookup field to work. If the list definition will only be used on an existing site, this will not be a problem.

     

  10. Another function of the SCHEMA.XML file is to define the views of the list. Views are the default view, the All Items view, and any other custom view you create in the SCHEMA.XML file that the user sees on the SharePoint site under the Select a Viewmenu. Views can also be created by the user through the list settings page, but these views are site specific and are stored in the database.To see the Views in the SCHEMA.XML file, search for “<View ” (make sure your search term has a space on the end). The first instance should look like this:
    <View BaseViewID=”0″ Type=”HTML”>

    This is the default view.

    The second instance should look like this:

    <View BaseViewID=”1″ Type=”HTML” WebPartZoneID=”Main” DisplayName=”All Items” DefaultView=”TRUE” Url=”AllItems.aspx” >

    This is the All Items view.

    We will be editing ViewFields in both the default and All Items views. The ViewFields element is a child element of View and is located many lines of code beneath the View tag. It would be a good idea to write down the line numbers for each View tag so when you add ViewFields you can verify you are adding them to the correct view. For our demonstration, the default view starts on line 22. The All Items view starts on line 230.

  11. Now that we have defined our fields, and located our views, we need to specify the fields within each view using the FieldRef element. Search for “<ViewFields>” in your SCHEMA.XML file. You should find two instances. The first instance is within the default view and should be below the first View tag and above the second. Refer to the line numbers you wrote down in the previous step to verify you are in the correct place. In our demonstration file, it is line 221. We will be editing the <FieldRef> tags that are children to the ViewFieldselement.

    Copy the below code and paste it IN PLACE OF the existing FieldRef tag:

    <FieldRef Name=”ISSUEID”></FieldRef>
    <FieldRef Name=”Title”></FieldRef>
    <FieldRef Name=”Status”></FieldRef>
    <FieldRef Name=”Description”></FieldRef>
    <FieldRef Name=”DateAssigned”></FieldRef>
    » FieldRef Element Syntax and Attributes (print this out or bookmark for your reference)

    So your resulting code should look like this:

    Repeat the same action with the second instance of the <ViewFields> element. The second instance is within the All Items view and should be below the second View tag. Refer to the line numbers you wrote down in the previous step to verify you are in the correct place. In our demonstration file, it is line 781.

    Note: If you want less fields to appear in the default view, identify which fields are not necessary and don’t include the corresponding <FieldRef> tag in the default view, which is the first instance referenced above.

  12. Save the SCHEMA.XMLfile.

    Adding the List to the ONET.XML file

    In order to display the list as an option on the Create page in SharePoint, you need to specify the new list within the ListTemplate element of the ONET.XML file for your site definition.

  13. Navigate to the following directory on your SharePoint server:
    Drive:Program FilesCommon FilesMicrosoft Sharedweb server extensions60TEMPLATE1033SITEDEFINITIONXML
  14. Open ONET.XML file in Notepad, an XML editor or a code editor. I used Visual Studio.
  15. We specify new lists by adding LISTTEMPLATE elements as children to the LISTTEMPLATES element. In the ONET.XML file, search for “<ListTemplates>“. On or around line 29 you will see the LISTTEMPLATES element where we will add the new LISTTEMPLATE element. Notice the lack of “S” between the two names. Reference the below image to see where you should be in your ONET.XML file.

    Copy the below code and paste it after the last LISTTEMPLATE tag:

    <ListTemplate Name=”PROJECTISSUES” DisplayName=”Project Issues” Type=”999″ BaseType=”0″ OnQuickLaunch=”TRUE” SecurityBits=”11″ Description=”Use the Project Issues list to keep track of issues that occur within the project that team members need to address.” Image=”/_layouts/images/itgen.gif”></ListTemplate>

    Let’s go over what attributes we have used in the above code.

    • Name – Required text that specifies the internal name of the list definition.
    • DisplayName – Required text that specifies the display name of the list definition.
    • Type – Numerical ID that identifies the list. The ID needs to be unique and be less than 1,000.
    • BaseType – Required integer that specifies the default schema for lists created from this definition.
    • OnQuickLaunch – Specifies whether or not to display this list on the Quick Launch Bar.
    • SecurityBits– Defines read, write and schema design security.
      • First bit is Read access – 1 allows all users Read access to all items; 2 allows users Read access to only those items they create.
      • Second bit is Write access – 1 allows all users to modify all items; 2 allows users to modify only items they create; 4 prevents users from modifying the list.
    • Description – Provides a description of the list definition.
    • Image – Specifies the icon used to represent the list.
    » ListTemplate Element Syntax and Attributes (print this out or bookmark for your reference)

    So your resulting code should look like this:

  16. Save the ONET.XML file.
  17. Restart IIS.

    The Results

  18. Go to your SharePoint site and create a new site. On the Template Selection page you should see your new site definition listed under Template.

Technical Resources

» Creating a List Definition

Step 4: Add the custom list definition to the default page of a new SharePoint site

We now have a custom site definition, and a custom list definition. Next we can setup the site to display the list upon site creation. We do this by editing the Configuration element within the ONET.XML file.

How to add a list for display on site creation

  1. Navigate to the following directory on your SharePoint server:
    Drive:Program FilesCommon FilesMicrosoft Sharedweb server extensions60TEMPLATE1033SITEDEFINITIONXML
  2. Open the ONET.XML file in Notepad, an XML editor or a code editor. I used Visual Studio.
  3. We add new lists to the default page by adding a LIST element as child to the CONFIGURATION element, which is a child to the CONFIGURATIONSelement. Notice the lack of “S” between the two names.In the ONET.XML file, search for “<Configurations>“. On or around line 1074 you will see the <Configurations> opening tag. Couple of lines below that is the <Configuration> element for the default page. The children of this tag are all the instances of lists that are created upon site creation. This is where we will add our new list. We will add another LIST element in the parent LISTS element. This is the same LIST element we were working with before in the SCHEMA.XML modification in Step 3.

    Copy the below code and paste it in addition to the existing LIST tags:

    <List Title=”Project Issues” Type=”999″ />
    » LIST Element Syntax and Attributes (print this out or bookmark for your reference)

    So your resulting code should look like this:

     

  4. Now we need to use the MODULES element to define the URL of the file to include as a part of our definition. The MODULES element is used in two places in the ONET.XML file, once in every CONFIGURATION element to declare modules, and then on its own outside of the CONFIGURATION node. We will be using a VIEW element inside of the MODULESelement that is NOT inside the CONFIGURATION node.In the ONET.XML file, search for “<Modules>“. You should get a lot of results. The last result should be on or around line 1222.

    Copy the below code and paste it after the second VIEW tag, which is a child of FILE:

    <View List=”999″ BaseViewID=”0″ WebPartZoneID=”Left” WebPartOrder=”3″/>

    Let’s go over what attributes we have used in the above code.

    • List – Optional integer that specifies the type of list as defined in ONET.XML.
    • BaseViewID – Optional integer that specifies the base view ID.
    • WebPartZoneID – Optional text that specifies the zone for the web part.
    • WebPartOrder – Optional integer that specifies the vertical positioning of the web part withing the specified zone.

    WebPartZoneID and WebPartOrder control the display location of the list. Alter these values to move the list around the page.

    » View Element Syntax and Attributes (print this out or bookmark for your reference)

    So your resulting code should look like this:

  5. Save the ONET.XML file.
  6. Restart IIS.

    The Results

  7. Create a new SharePoint site based off the selected site definition. Your new list will now appear on the default page.

Technical Resources

» Using Configurations
» Using Modules to Add Files to a Site Definition

Technical Resources: Composite List

» Creating a List Definition
» Creating a Site Definition from an Existing Site Definition
» Using Configurations
» Using Modules to Add Files to a Site Definition

» FIELD Element Syntax and Attributes
» FieldRef Element Syntax and Attributes
» LIST Element Syntax and Attributes
» ListTemplate Element Syntax and Attributes
» View Element Syntax and Attributes

 

Dustin Miller and Heather Solomon from SharePoint Experts