CAML in Windows SharePoint Services 3.0 Definitions

Posted by Robert Holmes on 09/1/07 | SharePoint

In version 3.0 of Windows SharePoint Services (WSS) Microsoft has furthered its total commitment to xml technologies by taking it to an all new level. Sites and navigation are primarily expressed as a dialect of xml referred to Collaborative Application Markup Language, (alternatively referred to as jaml, just another markup language). The main distinguishing feature of CAML documents is that they conform to the wss.xsd schema. These files are used by the runtime when creating new sites, lists, and other content when using templates or definitions, and the markup you write in your features to add content, as you saw in the last article.

New Site Creation

A good place to start to see the place that CAML has in the grand scheme of things, is to go to the heart and soul of any SharePoint v3 site, %CommonProgramFiles%\Microsoft Shared\web server extensions\12. I will refer to this folder in the remainder of this article as 12Hive. The sample site that I am using is in fact a MOSS site, but the points made apply equally to both WSS 3.0 and MOSS.

Under 12Hive there are a number of folders that serve unique purposes in SharePoint serving up content, such as web pages, user controls, etc. The folder of particular interest is 12Hive\TEMPLATE. Here are all the site and list definitions, also, as you recall from the last article, where features are deployed. Since the first thing one does once a SharePoint is installed is to create sites, let's start there. If your folder is organized alphabetically then the first subfolder is 1033, or the code for whatever language(s) are installed.

The area of interest for our purposes is the XML folder, since what is in there determines what one sees when one goes to create a new site, and what options one has. In there you will find a file named WEBTEMP.XML. The root node of this document is: <Templates xmlns:ows="Microsoft SharePoint"> then one or more elements such as this one:

When you see _layouts in a SharePoint url, such as in the ImageUrl attribute in our example, that refers to the folder %12Hive%\TEMPLATE\LAYOUTS. You may not find everything that resolves to the _layouts folder in a url in that folder, and one reason it is rewritten in that way, is that some content may be language dependent, and so is in another subfolder named the same as that language code. For example I have a folder named %12Hive%\TEMPLATE\LAYOUTS\1033 that has the localized English content. Also some of the files may actual live in the folder for the Feature that originally gave life to the content.

<Template Name="STS" ID="1">
    <Configuration ID="0" Title="Team Site" Hidden="FALSE"
ImageUrl="/_layouts/images/stsprev.png" Description="A site for teams to quickly organize, author, and share information. It provides a document library, and lists for managing announcements, calendar items, tasks, and discussions." DisplayCategory="Collaboration" />
    ...
</Template>

What does it all mean you ask? The Name attribute of the parent element refers to where you will find the template in the %12Hive%\TEMPLATE\SiteTemplates folder. In our example there is a subfolder, sts, that has all the information, in the form of CAML files, to describe a template in such a way that SharePoint can use it to create a new site, or site collection. How it does that we will get into soon. For now let's get a more concrete sense of what this xml means by looking at the Configuration sub element. To see this, if you have access to a WSS 3.0 or MOSS site, go to start to create a new site. In the template selection section, select Team Site, under the Collaboration tab, and this is what you will see:

 From this graphic you can connect the content of the Configuration element with what you see here. First the name you see for the template is what is in the Title attribute, the text under the graphic for the template comes directly from the Description attribute, and, the tab under which you will find the template, is determined by the DisplayCategory attribute. In fact if you create a new template you want to expose on your site, when you add it to WEBTEMP.xml, and add a new value for this attribute, such as My Template, that tab will automagically appear with no additional configuration. Just to verify this change the DisplayCategory, or another of these attributes, for one of the items you find in this file, then after calling IISRESET, you will see that change the next time you try to create a new site. The ID attribute refers to the specific configuration in a site definition that will be used when the site is created, as we shall see later.

The last topic to address here is that you may notice that not all the choices you see when you create a new site are in the WEBTEMP.XML file. Where you will find references to these templates is in the other xml files that exist in this folder. For example on my MOSS installation there are an additional 5 files that expose the other templates that I am able to use to create new sites.

Site Definitions/Templates and CAML in SharePoint

As I mentioned above, the Name attribute of the Template element in WEBTEMP.XML refers to a folder under %12Hive%\TEMPLATE\SiteTemplates. For a folder to be useful as a site definition (template), at the least it must have a subfolder named Xml, that has a file named onet.xml, which is the actual definition of the site to create. The folder parent folder of Xml may have other folders and files, that are used in the new site, such as custom aspx, ascx, or InfoPath files, but these are not necessary. For example our sts example has two additional aspx files needed for the site definition to work.

What do the tokens $Resources:... mean?One thing you will notice looking over the definition files are quite a number of tokens of the format: '$Resources:core, ...'. What this refers to is that the %12Hive%\Resources folder has a number of .resx resource files. When a new web application is created, the resource files required for that install are copied to a subfolder of the application's folder, such as C:\Inetpub\wwwroot\wss\VirtualDirectories, named App_GlobalResources. These files, or at least the ones we are interested in, are xml files with a series of elements such as this one from core.resx:
 <data name="DistributionGroups_OwnerEmail">
    <value>Owner Email</value>
</data>
, so anywhere the token '$Resources:core, DistributionGroups_OwnerEmail' exists, will be replaced with the value of the value element, or 'Owner Email' in this example. Obviously this, among other things, allows for the use of culture specific verbiage.

Now let's go to the folder %12Hive%\TEMLATE\SiteTemplates\sts\xml, and open up the file ONET.XML, otherwise known as the site definition for the Team Sites template, as well as Blank Site, and Document Workspace, available from the first tab of the New SharePoint Site page of a default install of either MOSS or WSS. How does one definition serve multiple templates, and why?

The why of this architecture is quite straight forward: In creating templates often times there are certain pieces of functionality that tends to apply across templates, so when creating a definition you can define specific modules, or page, that works for work for more than one template. That means that when creating definitions one tradeoff is whether multiple templates are similar that the time saved is worth more than the value added by multiple definitions.

Now the how: Recall from what I wrote above, just below the graphic showing the template selection section of the New SharePoint Site page. In the ONET.XML file go to line 73, assuming that you have not already experimented by modifying the file, you will see this line:
   <Configuration ID="0" Name="Default">
followed by some more CAML, then on line 108 this:
   <Configuration ID="1" Name="Blank">
and then another similar example on line 126. If you refer back to WEBTEMP.XML you will see that the second template has STS for the name, telling SharePoint to go to the subfolder sts under %12Hive%\TEMLATE\SiteTemplates. In addition in the WEBTEMP.XML file there are three configuration nodes under Template node, so for example by selecting the option that says Team Sites, that has <Configuration ID="0" ..., what is within that node will then be activated.

So what is it that gets activated and how might we affect that? Within the <Configuration> node there is a <Lists> with multiple <List> nodes. If you refer back to the prior article you will see what the <List> nodes do. In short that code instructs SharePoint what lists to construct when the new site is created. Also note that under one of the <List> nodes there is a <Data> node that informs the runtime what data to populate that list with.

On line 92 there is a <Modules> node with a single <Module> node. In other definitions there are additional <Module> nodes if the author wishes to do so. The <File> node tells SharePoint that the file default.aspx will be provisioned with this site, then the other nodes configure that page. You can look at some other definitions to see what else can be done with Modules, and how content is provisioned with templates. For example, you may want to search through the subfolders in %12Hive%\TEMPLATE\SiteTemplates, look what the other types of content are included with the template(s) they define, and see how that gets done.

The final piece in the <Configuration> node are references to Features that get installed and activated on the new site. Also note that there is a list of documents templates to provision with the new site, in lines 13-70, and the opportunity to create new lists in the <ListTemplates> node.

As always the best places to look for deeper information on what the various options are, what the markup in the definitions that you look at means, are the SDK's, MSDN, the blogs, and a good general purpose search engine, such as www.live.com . Ultimately the best way to learn all this is to create your own. The best way to get started with that is to go to the templates folder, copy, then paste the sts folder into the same folder, rename the resulting folder, which should be 'Copy of sts', to something like 'MyDefinition'. The first thing you may want to do is to delete one of the lists, add a new one by finding its FeatureId, and type from the Features folder, change Title and even Url using values from the core.resx file. If you are feeling particularly adventurous, add a new list template. To use the new site templates, add a reference to them in a new file that you put into the same folder as WEBTEMP.XML, with the same structure, then after an IISRESET, it should appear in the New SharePoint Site page. For extra credit use a new name for the DisplayCategory attribute, such as MyTemplates, and see the new tab appear in the list. Of course make sure not to try this on a production site.

Other CAML Nodes

In the last article we looked at some nodes that can be used in the creation of Features. A good place to find more information is the online sdk here: http://msdn2.microsoft.com/en-us/library/ms460318.aspx.

Conclusion

An essential reference for creating CAML is the Windows SharePoint Services SDK. In there you can find all the possible elements and the options for all of them. Also you will want to try as many of the elements and attributes that you can by using IntelliSense, assuming that you reference the wss.xsd schema in your xml files. Plus make sure to check out the technical articles and How To's.

Want to learn more about Windows SharePoint Services?
 View SetFocus' SharePoint Training options.

About Robert Holmes:

Robert Holmes is a software developer from the Boston area working almost exclusively with Microsoft products for over ten years. Over that time he have worked extensively with Visual Basic, MS Access, and Office product development as an independent consultant for a variety of organizations of all sizes, in both the public and private sectors.

Over the last 4 years Robert has been heavily invlolved with .NET technologies as a developer, user group leader and presenter, the last two using SharePoint heavily as a collaboration, and application platform. Robert has been involved with the current version of SharePoint technology since the beta 1 days in February of 2006, and is currently involved in the deployment of MOSS at two medium sized companies. Robert is available for development work as well as mentoring and guidance.

Email Robert!