https://github.com/andrei-markeev/camljs
Library for creating SharePoint CAML queries client-side. For JSOM, REST or SPServices.
https://github.com/andrei-markeev/camljs
sharepoint
Last synced: about 1 year ago
JSON representation
Library for creating SharePoint CAML queries client-side. For JSOM, REST or SPServices.
- Host: GitHub
- URL: https://github.com/andrei-markeev/camljs
- Owner: andrei-markeev
- License: ms-pl
- Created: 2017-04-08T15:45:11.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2022-12-06T17:51:05.000Z (over 3 years ago)
- Last Synced: 2024-04-13T17:05:28.961Z (about 2 years ago)
- Topics: sharepoint
- Language: TypeScript
- Homepage:
- Size: 5.5 MB
- Stars: 76
- Watchers: 11
- Forks: 22
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Installation
Nuget:
```
PM> Install-Package CamlJs
```
Npm:
```
npm install camljs
```
Also check out [CamlJs Console](https://github.com/andrei-markeev/camljs-console) - Chrome extension for testing queries with live preview against real lists.
## Usage
In browser:
```html
alert(new CamlBuilder().View().ToString());
```
In Node.js:
```js
var CamlBuilder = require('camljs');
console.log(new CamlBuilder().View().ToString());
```
ES2015 modules:
```js
import * as CamlBuilder from 'camljs';
console.log(new CamlBuilder().View().ToString());
```
## Basics
Let's assume we need to fetch all Google-related emails from a SharePoint list where your company stores archived project emails. To generate the corresponding query using CamlJs, you could use following javascript code:
```js
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 the following CAML code:
```xml
support@google.com
plus@google.com
[Google]
Google
```
It is also possible to generate SP.CamlQuery object, just change `.ToString()` to `.ToCamlQuery()`.
Another example:
```js
var 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...
```xml
2
3
10
```
## Dynamic queries
It's very easy to create dynamic queries with CamlJs by leveraging the `CamlBuilder.Expression()` construction.
It's like a standalone part of query that can be later used in the final `new CamlBuilder.Where()` or `new CamlBuilder.View()`.
```js
var categories = ["Category 1", "Category 2", "Category 3"];
var categoriesExpressions = categories.map(c => CamlBuilder.Expression().TextField("Category").EqualTo(c));
var caml = new CamlBuilder().Where()
.Any(categoriesExpressions),
.ToString();
```
Result:
```xml
Category 1
Category 2
Category 3
```
While `.Any()` generates `` clauses, `.All()` will generate ``.
## Elements support
CamlJs supports all Query elements that are [described on MSDN](http://msdn.microsoft.com/en-us/library/ms467521.aspx).
For example, seldom used Membership element:
```js
var caml = camlBuilder.Where()
.UserField("AssignedTo").EqualToCurrentUser()
.Or()
.UserField("AssignedTo").IsInCurrentUserGroups()
.GroupBy("ProductTitle")
.OrderBy("Priority").ThenBy("Title")
.ToString();
```
This code will generate following CAML:
```xml
```
## Joins
You can also create the upper-level View element as supported by SP.CamlQuery object.
Scope attribute, ViewFields, Joins and ProjectedFields are supported in this case.
Joining lists via CamlJs is very easy. Here's the example:
```js
var query = new CamlBuilder()
.View(["Title","Country","Population"])
.LeftJoin("Country","Country").Select("People","Population")
.Query()
.Where()
.NumberField("Population").LessThan(10)
.ToString();
```
The resulting generated CAML query will be the following:
```xml
10
```
## Modify existing queries
Often you need to modify existing query (e.g. that comes from an existing list view), rather than generate a completely new one.
This use case is also supported by CamlJs:
- `CamlBuilder.FromXml(xml)` method will create a CamlBuilder object from existing CAML string
- `ReplaceWhere` method then allows to replace 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:
```js
var xml = new CamlBuilder().View().Query().Where()
.UserField("Author").EqualToCurrentUser()
.ToString();
var query = CamlBuilder.FromXml(xml)
.ModifyWhere().AppendAnd()
.LookupField("Country").ValueAsText().BeginsWith("G");
```
Result:
```xml
G
```
## More examples
More query examples can be found under [tests](https://github.com/andrei-markeev/camljs/tree/master/tests) folder.
Also, check out [examples](https://github.com/andrei-markeev/camljs/tree/master/examples) folder for usage examples in SP Addins and SPFx projects.