Project Description

Simplifies creation of SharePoint CAML queries for client-side scripts. Intended to be used with SharePoint Client Object Model.

Basics

To start with, let's assume we need to fetch all Google-related letters from some mailbox list, using SharePoint Client Object Model. To generate the corresponding query using Caml Builder, you could use following javascript code:

    var camlBuilder = new CamlBuilder();

    var caml = camlBuilder.Where()
        .TextField("Email").EqualTo("support@google.com")
        .Or()
        .TextField("Email").EqualTo("plus@google.com")
        .Or()
        .TextField("Title").BeginsWith("[Google]")
        .Or()
        .TextField("Content").Contains("Google")
        .ToString();

This will generate expected CAML:

<Where>
  <Or>
    <Eq>
      <FieldRef Name="Email" />
      <Value Type="Text">support@google.com</Value>
    </Eq>
    <Or>
      <Eq>
        <FieldRef Name="Email" />
        <Value Type="Text">plus@google.com</Value>
      </Eq>
      <Or>
        <BeginsWith>
          <FieldRef Name="Title" />
          <Value Type="Text">[Google]</Value>
        </BeginsWith>
        <Contains>
          <FieldRef Name="Content" />
          <Value Type="Text">Google</Value>
        </Contains>
      </Or>
    </Or>
  </Or>
</Where>

, which then could be used in SP.CamlQuery.

Very good so far, and have a look at some other examples!

First of all, cannot resist to mention, that CamlBuilder covers almost all Query elements, described at MSDN.

For example, seldom used Membership element:

    var caml = camlBuilder.Where()
        .IntegerField("AssignedTo").EqualTo("{UserID}")
        .Or()
        .UserField("AssignedTo").Membership.CurrentUserGroups()
        .GroupBy("ProductTitle")
        .OrderBy("Priority").ThenBy("Title")
        .ToString();

This code will generate following CAML:

<Where>
  <Or>
    <Eq>
      <FieldRef Name="AssignedTo" />
      <Value Type="Integer">
        <UserID />
      </Value>
    </Eq>
    <Membership Type="CurrentUserGroups">
      <FieldRef Name="AssignedTo" />
    </Membership>
  </Or>
</Where>
<GroupBy>
  <FieldRef Name="ProductTitle" />
</GroupBy>
<OrderBy>
  <FieldRef Name="Priority" />
  <FieldRef Name="Title" />
</OrderBy>

The last example at this section:

    caml = camlBuilder.Where()
        .LookupIdField("Category").In([2, 3, 10])
        .And()
        .DateField("ExpirationDate").LessThanOrEqualTo("{Now}")
        .OrderByDesc("ExpirationDate")
        .ToString()

As you see, the code is pretty clean and readable. The resulting CAML is much more awkward, especially if you imagine it in javascript strings dress, without indentation and highlighting...

<Where>
  <And>
    <In>
      <FieldRef Name="Category" LookupId="True" />
      <Values>
        <Value Type="Integer">2</Value>
        <Value Type="Integer">3</Value>
        <Value Type="Integer">10</Value>
      </Values>
    </In>
    <Leq>
      <FieldRef Name="ExpirationDate" />
      <Value Type="Date">
        <Now />
      </Value>
    </Leq>
  </And>
</Where><OrderBy>
  <FieldRef Name="ExpirationDate" Ascending="False" />
</OrderBy>

Usability

Besides of readability, CamlBuilder pretends to be very handy in development, because you can use intellisense and inline documentation:

This will help to catch a bunch of errors when writing code, and surely prevent from typos and misunderstandings, so the benefits could be really magnificient!

Contribute

Any contributions are highly appreciated!

Last edited Sep 1, 2011 at 10:54 PM by omlin, version 6