caml4js

A declarative JavaScript library for creating SharePoint client-side CAML queries.

All Query elements mentioned in the CAML docs are supported by Caml4Js

Table of Contents

• Intallation
• Usage
• Basics
• Dynamic Where
• Utility Functions

Installation

Npm:

npm install caml4js --save

Npm TypeScript definitions:

npm install @types/caml4js --save-dev

Usage

In browser:

<script type="text/javascript" src="//caml4js.js"></script>

In node:

var caml4js = require('caml4js');

ES6 modules:

import { query, textField, where, or, userField, orderBy, groupBy, booleanField, and} from 'caml4js';

Basics

It's important to keep in mind the structure of CAML query and how Caml4Js tries to map it to code. The structure looks like this:

view/
  viewFields/
  aggregations/
  joins/
    join/
  projections/
  query/
    where/
    orderBy/
    groupBy/
  rowLimit/

Assume we want to fetch the Name and Population size from a SharePoint list where the country name is Ghana. To generate the CAML query using Caml4Js, you could use the following code:

let v = view(
            viewFields("Name","Population"),
            query(
                where(
                    textField("Name").equalTo("Ghana")
                )
            )
        )

Very simple, it follows the structure for CAML query we stated earlier. This will generate the following xml:

<View>
    <ViewFields>
        <FieldRef Name="Name" />
        <FieldRef Name="Population" />
    </ViewFields>
    <Query>
        <Where>
            <Eq>
                <FieldRef Name="Name"/>
                <Value Type="Text">Ghana</Value>
            </Eq>
        </Where>
    </Query>
</View>

To search using the Poulation field, we could write something like this:

let v = view(
            viewFields("Name","Population"),
            query(
                where(
                    numberField("Population").greaterThan(2000)
                )
            )
        )

If you want items where Country field is Ghana or USA:

let v = view(
            viewFields("Name","Population"),
            query(
                where(
                    or(
                        textField("Name").equalTo("Ghana"),
                        textField("Name").equalTo("USA")
                    )
                )
            )
        )

<View>
    <ViewFields>
        <FieldRef Name="Name" />
        <FieldRef Name="Population" />
    </ViewFields>
    <Query>
        <Where>
            <Or>
                <Eq>
                    <FieldRef Name="Name"/>
                    <Value Type="Text">Ghana</Value>
                </Eq>
                <Eq>
                    <FieldRef Name="Name"/>
                    <Value Type="Text">USA</Value>
                </Eq>
            </Or>
        </Where>
    </Query>
</View>

or

let v = view(
            viewFields("Name","Population"),
            query(
                where(
                    textField("Name").in(["USA","Ghana"])
                )
            )
        )

<View>
    <ViewFields>
        <FieldRef Name="Name" />
        <FieldRef Name="Population" />
    </ViewFields>
    <Query>
        <Where>
            <In>
                <FieldRef Name="Name" />
                <Values>
                    <Value Type="Text">USA</Value>
                    <Value Type="Text">Ghana</Value>
                </Values>
            </In>
        </Where>
    </Query>
</View>

Complex nested operators

Caml4Js makes it easy to generate complex queries.

let q = query(
            where(
                and(
                    and(
                        booleanField("Enabled").isTrue(),
                        or(
                            userField("Audience").includes(100),
                            userField("Audience").includes(101)
                        )
                    ),
                    or(
                        textField("Title").equalTo("Test Suites"),
                        and(
                            choiceField("Status").equalTo("Open"),
                            dateTimeField("Created").greaterThan("2019-01-01T00:00:00.000Z")
                        )
                    )
                )
            )
    )

<Query>
    <Where>
        <And>
            <And>
                <Eq>
                    <FieldRef Name="Enabled"/>
                    <Value Type="Integer">1</Value>
                </Eq>
                <Or>
                    <Eq>
                        <FieldRef Name="Audience"/>
                        <Value Type="UserMulti">100</Value>
                    </Eq>
                    <Eq>
                        <FieldRef Name="Audience"/>
                        <Value Type="UserMulti">101</Value>
                    </Eq>
                </Or>
            </And>
            <Or>
                <Eq>
                    <FieldRef Name="Title"/>
                    <Value Type="Text">Test Suites</Value>
                </Eq>
                <And>
                    <Eq>
                        <FieldRef Name="Status"/>
                        <Value Type="Choice">Open</Value>
                    </Eq>
                    <Gt>
                        <FieldRef Name="Created"/>
                        <Value Type="DateTime" IncludeTimeValue="TRUE">2019-01-01T00:00:00.000Z</Value>
                    </Gt>
                </And>
            </Or>
        </And>
    </Where>
</Query>

Membership

Let's find all items where the Author is the current user

let v = view(
            viewFields("Name","Population"),
            query(
                where(
                    userField("Author").equalToCurrentUser()
                )
            )
        )

<View>
    <ViewFields>
        <FieldRef Name="Name"/>
        <FieldRef Name="Population"/>
    </ViewFields>
    <Query>
        <Where>
            <Eq>
                <FieldRef Name="Author" LookupId="TRUE"/>
                <Value Type="Integer">
                    <UserID/>
                </Value>
            </Eq>
        </Where>
    </Query>
</View>

Joins

You can use Caml4Js for list joins and field projections to generate your CAML queries. Suppose we have lists Student and Result with a lookup column called Candidate. Joins

let v = view(
        viewFields("Grade","Name"),
        joins(
            join(JoinType.LEFT, "student", "Candidate","", [{ Name: "Name", Field: "Name"}])
        ),
        query(
            where(
                textField("Name").equalTo("John")
            )
        )
    )

<View>
    <ViewFields>
        <FieldRef Name='Name'/>
        <FieldRef Name='Grade'/>
    </ViewFields>
    <Joins>
        <Join Type='LEFT' ListAlias='student'>
            <Eq>
                <FieldRef Name='Candidate' RefType='Id'/>
                <FieldRef Name='ID' List='student'/>
            </Eq>
        </Join>
    </Joins>
    <ProjectedFields>
        <Field Name='Grade' Type='Lookup' List='student' ShowField='Grade'/>
    </ProjectedFields>
    <Query>
        <Where>
            <Eq>
                <FieldRef Name='Name'/>
                <Value Type='Text'>John</Value>
            </Eq>
        </Where>
    </Query>
</View>

Suppose we have an Orders, Customers and Cities lists. The Orders list has a CustomerName field that looks up to a Customers list, and that the Customers list has a CityName field that looks up to a Cities list.

Let's see how we can return all orders from an Orders list where the customer’s city is London.

let v = view(
        viewFields("CustomerCity"),
        joins(
            join(JoinType.LEFT, "customers", "CustomerName"),
            join(JoinType.LEFT, "customerCities", "CityName", [{ Name: "CustomerCity", Field: "Title" }],"customers"),
        ),
        query(
            where(
                textField("CustomerCity").equalTo("London")
            )
        )
    )

this will give us the following

<View>
    <ViewFields>
        <FieldRef Name="CustomerCity"/>
    </ViewFields>
    <Joins>
        <Join Type="LEFT" ListAlias="Customers">
            <Eq>
                <FieldRef Name="CustomerName" RefType="Id" />
                <FieldRef Name="ID" List="Customers"/>
            </Eq>
        </Join>
        <Join Type="LEFT" ListAlias="Cities">
            <Eq>
                <FieldRef Name="CityName" RefType="Id"/>
                <FieldRef Name="ID" List="Cities"/>
            </Eq>
        </Join>
    </Joins>
    <ProjectedFields>
        <Field Name="CustomerCity" Type="Lookup" List="Cities" ShowField="Title"/>
    </ProjectedFields>
    <Query>
        <Where>
            <Eq>
                <FieldRef Name="CustomerCity"/>
                <Value Type="Text">London</Value>
            </Eq>
        </Where>
    </Query>
</View>

Dynamic Where (WhereBuilder)

You can use WhereBuilder to generate a dynamic WHERE element.

    const builder = whereBuilder();
    builder.addQuery(booleanField("Enabled").isTrue());

    //somewhere in the code
    builder.addQuery(
        or(
            userField("Audience").includes(100),
            userField("Audience").includes(101)
        )
    );

    let v = view(
                viewFields("Name","Population"),
                query(
                    builder.toWhere()
                )
        );

this will give us

<View>
    <Query>
        <Where>
            <And>
                <Eq>
                    <FieldRef Name="Enabled"/>
                    <Value Type="Integer">1</Value>
                </Eq>
                <Or>
                    <Eq>
                        <FieldRef Name="Audience"/>
                        <Value Type="UserMulti">100</Value>
                    </Eq>
                    <Eq>
                        <FieldRef Name="Audience"/>
                        <Value Type="UserMulti">101</Value>
                    </Eq>
                </Or>
            </And>
        </Where>
    </Query>
</View>

WhereBuilder can be chained

builder.addQuery(booleanField("Enabled").isTrue())
        .addQuery(userField("Audience").includes(101))

Utility functions

encodeAsCDATA(s:string)

This function is used to encode textual data as CDATA that should not be parsed by an XML parser. The characters "<" and "&" are not allowed within XML elements. The "<" character will throw an error because the parser will interpret it as the start of a new element. The "&" character will throw an error because the parser will interpret it as the start of a character entity.

sanitizeQuery(s:string)

Removes line breaks from supplied query string