Project Description

Simplifies creation of SharePoint CAML queries for client-side scripts. Can be used with either SharePoint Client Object Model or SPServices.

Nuget:

PM> Install-Package CamlJs

TypeScript definitions:

PM> Install-Package camljs.TypeScript.DefinitelyTyped

Check out CamlJs-Console!

I created a Chrome extension for instant testing CamlJs queries against real lists, CamlJs-Console. The extension is open source and free. Available via Web Store or alternatively you can install it from the source code (see docs on GitHub).

What's new in Release 2.5

View element

View element is added! Scope attribute, ViewFields, Joins and ProjectedFields are supported. Joining lists via CamlJs is very easy. Here's the example:

var query = new CamlBuilder()
    .View(["Title","Country","Population"])
    .LeftJoin("Country","Country").Select("People","Population")
    .Query()
    .Where()
    .NumberField("Population").LessThan(10)
    .ToString();

Intellisense helps understanding the parameters:

And one more screenshot of intellisense:

So as you see, really simple: Join listName as Alias, Select Field as Alias, Select Field as Alias, etc. Then, use fields aliases in the main query. That's it! Corresponding Joins and ProjectedFields elements are generated automatically.

So the resulting generated CAML query will be the following:

<View>
    <ViewFields>
        <FieldRef Name="Title" />
        <FieldRef Name="Country" />
        <FieldRef Name="Population" />
    </ViewFields>
    <Joins>
        <Join Type="LEFT" ListAlias="Country">
            <Eq>
                <FieldRef Name="Country" RefType="ID" />
                <FieldRef Name="ID" List="Country" />
            </Eq>
        </Join>
    </Joins>
    <ProjectedFields>
        <Field ShowField="People" Type="Lookup" Name="Population" List="Country" />
    </ProjectedFields>
    <Query>
        <Where>
            <Lt>
                <FieldRef Name="Population" />
                <Value Type="Number">10</Value>
            </Lt>
        </Where>
    </Query>
</View>

No dependencies

CamlJs was dependent on some SharePoint components (Sys.StringBuilder and SP.XmlWriter). But many people had problems with that, so now CamlJs doesn't have any dependencies.

This enables opportunity to run CamlJs standalone, e.g. in SharePoint Apps without including heavy SP javascripts; and also to use CamlJs in SharePoint 2007. Though please remember that some CAML Query elements (e.g. <In>) were added only in SP2010.

Migration from 2.0 to 2.5

Please remember that some fields were marked as DEPRECATED in Release 2.0. In version 2.5, previously marked LookupIdField is removed. In next versions, the process will be continued.

If you're still using LookupIdField, replace it like this:

Old code example:

.LookupIdField("MyLookup").EqualTo(5)

Replace with:

.LookupField("MyLookup").Id().EqualTo(5)

ToCamlQuery()

Added ToCamlQuery method, that can be to finalize the query. But instead of string, ToCamlQuery will produce a ready-to-use SP.CamlQuery object, which you can then pass into list.getItems method.

Example project

Example project is now a SharePoint-hosted app with a simple interactive demo:

UserMultiField and LookupMultiField

UserMultiField and LookupMultiField weren't much tested in previous release, but now in 2.5 they are tested through and significantly improved. Now instead old EqualTo, NotEqualTo, Includes and NotIncludes operations (these are marked DEPRECATED), single operation "IncludesSuchItemThat" added.

 

So now it is possible to check condition against Id or against a value, cast to a specified type (same as with single-value lookups):

Internally, CAML Query is identical for MultiLookup and single-value Lookup columns, but hopefully this minor syntax improvement will help people better understand how SharePoint interprets this query.

---------------- end of release 2.5 news -------------

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()
        .UserField("AssignedTo").EqualToCurrentUser()
        .Or()
        .UserField("AssignedTo").IsInCurrentUserGroups()
        .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()
        .LookupField("Category").Id().In([2, 3, 10])
        .And()
        .DateField("ExpirationDate").LessThanOrEqualTo(CamlBuilder.CamlValues.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

CamlBuilder is not only readable and simple, but it also provides rich 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!

Intellisense and inline docs are even better if you use CamlJs with TypeScript.

Contribute

Any contributions are highly appreciated!

Last edited Oct 10 at 11:27 PM by omlin, version 21