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.7
- New type of field - ModStatField
- Fixed bug with boolean field EqualTo operation
What's new in Release 2.6
- Now it is possible to use CamlJs for modifying existing CAML queries:
- FromXml method will create a CamlBuilder object from existing CAML string
- ReplaceWhere method allows to replace <Where> clause with one generated by CamlJs
- ModifyWhere().AppendAnd() will add new conditions to existing query using "And" operator
- ModifyWhere().AppendOr() will add new conditions to existing query using "Or" operator
Example:
![]()
- Added Query().GroupBy(...) and Query().OrderBy(...)
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><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.
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><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
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!
