Collaborative Application Markup Language (CAML)

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.