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
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 will help to understand the parameters:
And one more screenshot of intellisense:
This code generates the following CAML query:
<View><ViewFields><FieldRefName="Title"/><FieldRefName="Country"/><FieldRefName="Population"/></ViewFields><Joins><JoinType="LEFT"ListAlias="Country"><Eq><FieldRefName="Country"RefType="ID"/><FieldRefName="ID"List="Country"/></Eq></Join></Joins><ProjectedFields><FieldShowField="People"Type="Lookup"Name="Population"List="Country"/></ProjectedFields><Query><Where><Lt><FieldRefName="Population"/><ValueType="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.
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:
Replace with:
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, so 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 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><FieldRefName="Email"/><ValueType="Text">support@google.com</Value></Eq><Or><Eq><FieldRefName="Email"/><ValueType="Text">plus@google.com</Value></Eq><Or><BeginsWith><FieldRefName="Title"/><ValueType="Text">[Google]</Value></BeginsWith><Contains><FieldRefName="Content"/><ValueType="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><FieldRefName="AssignedTo"/><ValueType="Integer"><UserID/></Value></Eq><MembershipType="CurrentUserGroups"><FieldRefName="AssignedTo"/></Membership></Or></Where><GroupBy><FieldRefName="ProductTitle"/></GroupBy><OrderBy><FieldRefName="Priority"/><FieldRefName="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><FieldRefName="Category"LookupId="True"/><Values><ValueType="Integer">2</Value><ValueType="Integer">3</Value><ValueType="Integer">10</Value></Values></In><Leq><FieldRefName="ExpirationDate"/><ValueType="Date"><Now/></Value></Leq></And></Where><OrderBy><FieldRefName="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!