spJsom is a library that simplies usage of the SharePoint Client Side Object Model (JavaScript/JSOM). Using a fluent API, the library allows chaining multiple commands together with conditions and progress monitoring. Goals of this library are: - Simp
javascript
var context = SP.ClientContext.get_current();
new spJsom.Fluent()
.withContext(context)
.user.getCurrentUserProfileProperties()
.execute()
.fail(function(sender, args) {
console.error(args.get_message());
})
.done(function(results) {
console.log(results);
console.log("Your profile properties", results[0].result[0]);
});
`
TypeScript Examples
For more examples, including more complex scenarios with multiple commands,
see TypeScript examples
JavaScript Examples
Coming soon!
Dependencies
jQuery must be loaded as the library uses jQuery Promises.
Usage
Install - npm
npm i spjsomfluent --save
Importing spJsom
`
import * as spJsom from "spjsomfluent"
`
Development commands - NodeJs
$3
npm install
$3
npm run debug
$3
npm run release
$3
npm run dev
Getting started using the sample app for TypeScript and WebPack
1. Clone the repository and copy the sampleApp folder to your own location. git clone https://github.com/TjWheeler/spJsomFluent
2. run npm install from the sampleApp folder you copied using a Node Shell
3. run npm run debug to build the sample app. (The development commands listed above are valid for this app too.)
4. Upload the resulting .js and .js.map to SharePoint or use Fiddlers autoresponder to a location of your chosing. eg; /style library/myApp
5. Add a script reference in a Script Editor web part:
6. Modify the app as needed (use npm run dev to watch the file updates you make and immediately rebuild)
Note: The default sample app is designed to create a List called MyList1 and a single list item.
Once the script is loaded, it will execute as soon as SP.js is loaded.
Events
To monitor activity there are 2 events you can wire up to. These are:
1. onExecuting(commandName, step, totalSteps)
2. onExecuted(commandName, success, results)
onExecuting
To show progress, this method will give you the details you need.
`typescript
.onActionExecuting((actionName:string, current:number, total:number) => {
let progress = Math.ceil(100 * current / total);
console.log(Executing: ${actionName}, we are ${progress}% through.);
})
`
onExecuted
`typescript
.onActionExecuted((actionName:string, success:boolean, results: Array) => {
console.log( Executed: ${actionName}:${success});
if (!success) {
console.error(actionName, results);
}
})
`
Commands
whenTrue & whenFalse
These commands .whenTrue() and .whenFalse() are a conditional check. They take the value from the previous step then compare it with True/False to determine if execution of the chain should continue.
For example:
`
.permission.hasWebPermission(SP.PermissionKind.createSSCSite, context.get_web())
.whenTrue() //stops executing the chain if the user doesn't have permission
`
Note that the when commands do not reject a promise even when their condition is not met. The chain of execution simply stops at that point.
when
You can supply your own predicate to determine if execution of the chain should continue.
For example:
`javascript
.listItem.get(context.get_web(), "MyList", 1)
.when(function(listItem) {
if(listItem.get_item("Title") === "My Title") {
return true; //the chain execution will continue
}
return false; //the chain execution will stop
})
`
The result of the previous step is passed into the when predicate allowing you the opportunity to evaluate the result and continue or stop.
whenAll
Similar to when, but instead of the previous steps result being passed in, an array with all previous steps are passed to the predicate.
`javascript
...
.listItem.get(context.get_web(), "MyList", 1)
.whenAll(function(results) {
var listItem = results[0];
if(listItem.get_item("Title") === "My Title") {
return true; //the chain execution will continue
}
return false; //the chain execution will stop
})
`
File Commands
Fluent API spJsom.file
| Command | Result | Description | Example |
| ------------- | ------------- | ------------- | ------------- |
| get(serverRelativeUrl: string) | SP.File | Get a file from a document library | get(_spPageContextInfo.siteServerRelativeUrl + "/documents/doc.docx") |
| getListItem(serverRelativeUrl: string) | SP.ListItem | Get the list item for the file | getListItem(_spPageContextInfo.siteServerRelativeUrl + "/documents/doc.docx") |
| checkIn(web: SP.Web, serverRelativeUrl: string, comment: string, checkInType: SP.CheckinType) | SP.File | Check in a file | checkIn(SP.ClientContext.get_current().get_web(), _spPageContextInfo.webServerRelativeUrl + '/pages/mypage.aspx', "Checked in by spJsomFluent", SP.CheckinType.majorCheckIn) |
List Commands
Fluent API spJsom.list
| Command | Result | Description | Example |
| ------------- | ------------- | ------------- | ------------- |
| create(web: SP.Web, listName: string, templateId: number) | SP.List | Create new list | create(context.get_web(), "My Task List", 107) |
| exists(web: SP.Web, listName: string) | boolean | Check if the list exists | exists(context.get_web(), "My List") |
| delete(web: SP.Web, listName: string) | void | Delete a list | delete(context.get_web(), "My List") |
| get(web: SP.Web, listName: string) | SP.List | Get a list | get(context.get_web(), "My List") |
| addContentTypeListAssociation(web: SP.Web, listName: string, contentTypeName: string)| SP.ContentType | Adds a Content Type to a List. Resolves the new associated list content type. | addContentTypeListAssociation(context.get_web(), "My List", "My Content Type Name") |
| removeContentTypeListAssociation(web: SP.Web, listName: string, contentTypeName: string) | void | Removes a Content Type associated from a list. | removeContentTypeListAssociation(context.get_web(), "My List", "My Content Type Name") |
| setDefaultValueOnList(web: SP.Web, listName: string, fieldInternalName: string, defaultValue: any) | void | Sets a default value on a field in a list | setDefaultValueOnList(context.get_web(), "My Task List", "ClientId", 123)|
| setAlerts(web: SP.Web, listName: string, enabled: boolean)| void | Enable email alerts on a list. Note: will not work for 2010/2013. | setAlerts(context.get_web(), "My Task List", true) |
ListItem Commands
Fluent API spJsom.listItem
| Command | Result | Description | Example |
| ------------- | ------------- | ------------- | ------------- |
| update(listItem: SP.ListItem, properties: any) | SP.ListItem | Update a list item with properties| update(listItem, { 'Title': 'Title value here', ClientId: 123 }) |
| createWithContentType(web: SP.Web, listName: string, contentTypeName: string, properties: any) | SP.ListItem | Create a list item, specifying the Content Type | createWithContentType(context.get_web(), "My list", "My Content Type Name", { 'Title': 'Title value here', ClientId: 123 })|
| create(web:SP.Web, listName: string, properties: any) | SP.ListItem | Create a list item with properties| update(listItem, { 'Title': 'Title value here', ClientId: 123 }) |
| get(web: SP.Web, listName: string, id: number, viewFields: Array = null) | SP.ListItem | Get the listitem using the ID with optional view fields | get(context.get_web(), "MyList", 1, ["ID", "Title"]) |
| getFileListItem(serverRelativeUrl: string, viewFields: Array = null) | SP.ListItem | Get the listitem for a File using the ID with optional view fields | getFileListItem("/sites/site/documents/mydoc.docx", ["ID", "Title", "FileLeafRef"]) |
| deleteById(web: SP.Web, listName: string, id: number) | void | Delete List Item | deleteById(context.get_web(), "MyList", 7) |
| query(web: SP.Web, listName: string, viewXml: string) | SP.ListItemCollection | Execute a query using supplied CAML.| query(context.get_web(), "MyList", "1 2 ") |
Navigation Commands
Fluent API spJsom.navigation
| Command | Result | Description | Example |
| ------------- | ------------- | ------------- | ------------- |
| createNode(web: SP.Web, location: NavigationLocation, title: string, url: string, asLastNode: boolean = true) | SP.NavigationNode | Create new navigation node | createNode(context.get_web(), NavigationLocation.Quicklaunch, "Test Node", "/sites/mysite/pages/default.aspx") |
| deleteAllNodes(web: SP.Web, location: NavigationLocation) | void | Delete all navigation nodes for the web | deleteAllNodes(context.get_web(), NavigationLocation.Quicklaunch) |
| deleteNode(web: SP.Web, location: NavigationLocation, title:string ) | void|Delete all navigation nodes that match the supplied title for the web|deleteNode(context.get_web(), NavigationLocation.Quicklaunch, "My link title")|
| setCurrentNavigation(web: SP.Web, type: NavigationType, showSubsites: boolean = false, showPages:boolean = false)|void| Set navigation for the web | setCurrentNavigation(context.get_web(), 3, true, true) |
Note: Taxonomy based navigation is not currently supported
Permission Commands
Fluent API spJsom.permission
| Command | Result | Description | Example |
| ------------- | ------------- | ------------- | ------------- |
| hasWebPermission(permission: SP.PermissionKind, web: SP.Web) | boolean| Check if the current user has specified Web permission| hasWebPermission(SP.PermissionKind.createSSCSite, context.get_web()) |
| hasListPermission(permission: SP.PermissionKind, list: SP.List)|boolean|Check if the current user has specified List permission| hasListPermission(SP.PermissionKind.addListItems, context.get_web().get_lists().getByTitle("MyList")) |
| hasItemPermission(permission: SP.PermissionKind, item: SP.ListItem) |boolean|Check if the current user has specified ListItem permission | hasItemPermission(SP.PermissionKind.editListItems, context.get_web().get_lists().getByTitle("MyList").getItemById(0)) |
Fluent API spJsom.web
Publishing Page Commands
Fluent API spJsom.publishingPage
| Command | Result | Description | Example |
| ------------- | ------------- | ------------- | ------------- |
| create(web: SP.Web, name: string, layoutUrl: string) | SP.Publishing.PublishingPage |Creates a new publishing page. | .publishingPage.create(SP.ClientContext.GetCurrent().get_web(), "Home.aspx", _spPageContextInfo.siteServerRelativeUrl + "/_catalogs/masterpage/BlankWebPartPage.aspx") |
| getLayout(serverRelativeUrl:string) | SP.ListItem | Gets a page layout | |
User Commands
Fluent API spJsom.user`