Introduction
Any developer who has opened the hood of the Windows SharePoint Services 3.0 (WSS 3.0) or Office SharePoint Server 2007 with the aim of customizing a site template has probably encountered Collaborative Application Markup Language (CAML).
CAML is an XML-based language, used by SharePoint, to define sites and lists, including fields, forms, and views. CAML features in front-end site definitions (SharePoint Server Templates), SOAP messages (SharePoint Web Services), and in code (SharePoint object model development) to provide flexible customization of SharePoint web sites.
If you are asking yourself what SharePoint is, have only used the SharePoint UI, or are interested in customizing SharePoint 2003 (WSS 2.0), then I’d advice you stop reading here. Please refer to the article titled “Windows SharePoint Services 3.0 Essentials” before reading this article.
Schema
SharePoint site definitions are the root of site customization on the server (as opposed to site templates – STP files created by front-end users). Site definitions exist as a number of ASP.NET content files (master pages, content pages, images etc), and XML files, containing metadata, used by SharePoint to facilitate site creation based on a particular template. These XML files are representative of the template schema – defining features, lists, forms, and views in a site template.
Site templates express schema content using the Custom Application Markup Language.
CAML Elements
CAML contains two major element types for site customization – Data Defining Elements and HTML Rendering Elements.
Data Defining Elements
Data Defining Elements facilitate field rendering and schema definition. A field is a column or attribute that users can add to lists. A list schema defines each list in SharePoint. The format of the list schema is XML-based using CAML – the following text is an example of a field element contained in a list element:
<List>
<MetaData>
<Fields>
<Field Type=“Counter” Name=”ID” />
</Fields>
</MetaData>
</List>
SharePoint defines the default field types in the FLDTYPES.XML file, located in C:Program FilesCommon FilesMicrosoft Sharedweb server extensions12TEMPLATEXML. A typical field type schema will contain behavior and display information for the field, for example:
<FieldType>
<Field Name=”TypeName”>Counter</Field>
<Field Name=”TypeDisplayName”>$Resources:core,fldtype_counter;</Field>
<Field Name=”InternalType”>Counter</Field>
<Field Name=”SQLType”>int</Field>
<Field Name=”ParentType”></Field>
<Field Name=”UserCreatable”>FALSE</Field>
<Field Name=”Sortable”>TRUE</Field>
<Field Name=”Filterable”>TRUE</Field>
<RenderPattern Name=”HeaderPattern”>
<HTML><![CDATA[<b>]]></HTML>
<Column/>
<HTML><![CDATA[</b>]]></HTML>
</RenderPattern>
<RenderPattern Name=”DisplayPattern”><Column/></RenderPattern>
<RenderPattern Name=”EditPattern”><Column/></RenderPattern>
</FieldType>
Field types typically contain rendering patterns, to render different HTML depending on the data type of the field in question and the display mode (display, edit new etc). Rendering patterns may contain raw HTML markup and/or schema data elements. For example, the header pattern in the above markup will render column data in bold for all counter type fields.
Note: Developers are advices not to edit the FLDTYPES.XML folder. Changes to this file may break SharePoint. Developers looking to create their own customized field types must define field metadata in the SCHEMA.XML file, located in the site template lists folder structure (see a future article about WSS 3.0 List Customization).
The following table lists the data defining elements for field types:
|
Name |
Data Type |
Description |
|
Column2Suffix |
Text |
Contains text to append to base column name |
|
DisplayPattern |
Note |
Contains HTML template for rendering field in display mode |
|
EditPattern |
Note |
Contains HTML template for rendering field in edit mode |
|
HeaderPattern |
Note |
Contains HTML template for rendering field column heading |
|
Name |
Text |
Name of internal data type |
|
NewPattern |
Note |
Contains HTML template for rendering new content in new form |
|
PreviewDisplayPattern |
Note |
SP Designer display mode |
|
PreviewEditPattern |
Note |
SP Designer edit mode |
|
PreviewNewPattern |
Note |
SP Designer new form mode |
|
Sortable |
Text |
TRUE or FALSE – allow sorting |
|
TypeName |
Text |
Name of field type |
|
SQLType |
Text |
Underlying SQL type |
|
SQLType2 |
Text |
When not blank, provides type of secondary column to create (URL field) |
The following table lists the data elements available for use in display mode patterns within field types:
|
Element |
Description |
|
Column |
Returns raw data for the field |
|
Column2 |
Returns raw data for the secondary field – used by link field types |
|
Escape |
Escape characters in a string |
|
FieldFilterOptions |
Used in the HeaderPattern to display filter drop down menus |
|
FieldPrefix |
Returns office namespace: urn:schema-microsoft-com:office:office# |
|
FieldRef |
Used in computed fields to refer to constituent fields |
|
FieldSortImageURL |
URL to column sort image |
|
FieldSortParams |
Returns sort direction ASC or DSC |
|
IfEqual |
Conditional rendering using two CAML expressions |
|
IfNew |
Returns TRUE if item is considered new |
|
ImagesPath |
URL to Images directory |
|
Limit |
Truncates text to a specific length |
|
LocaleInfo |
Transfers server locale info to the client to display and edit dates and numbers |
|
PageUrl |
Returns absolute encoded URL of current page |
|
Property |
Returns property in ForEach context |
|
ScriptQuote |
Render text as quotes |
|
TodayISO |
Today’s date as ISO |
For more detail information on CAML data elements, refer to the article at http://msdn2.microsoft.com/en-us/library/ms478072.aspx.
HTML Rendering Elements
HTML Rendering Elements facilitate page rendering. Pages based on a site definition – containing HTML rendering elements – can display dynamic content evaluated by SharePoint. The following example renders today’s date and the current user ID:
<ows:XML>
<Today/>
<UserID/>
</ows:XML>
Developers can distinguish HTML Render Elements from Data Defining Elements by the ows namespace prefix.
The following table lists the available rendering elements:
|
Element |
Description |
|
Batch |
Batch process commands within HTTP protocol |
|
Case |
Used inside a Switch or FieldSwitch statement |
|
Default |
Default field value |
|
Expr |
CAML expression used in Switch or FieldSwitch statements |
|
FieldSwitch |
Conditional rendering based on expression |
|
ForEach |
Enumerate collection of views or fields |
|
GetVar |
Returns variables in the current context of page rendering |
|
HTMLBase |
Returns string that sets the base element for the current page |
|
HttpHost |
URL of virtual server containing current web site |
|
HttpPath |
Path to OWSSVR.DLL |
|
HttpVDir |
Returns root directory of current site |
|
IfEqual |
Conditional rendering using two CAML expressions |
|
ListProperty |
Returns the value of a specified column in the Lists table in the database |
|
Now |
Renders the current time |
|
Project |
Top level element in ONET.XML |
|
ProjectProperty |
Returns global property of current team web site |
|
Property |
Returns property in ForEach context |
|
SetList |
Designates the current list |
|
SetVar |
Sets variables in the current page rendering context |
|
Switch |
Conditional rendering using CAML expression |
|
Today |
Renders today’s date |
|
URL |
Renders a URL |
|
View |
Defines a view in Windows SharePoint Services |
|
XML |
Used as an outer wrapper to denote section of CAML |
For more detail information on CAML HTML rendering elements, refer to the article at http://msdn2.microsoft.com/en-us/library/ms480526.aspx.