spjsomfluent v0.1.30

spJsomFluent

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:

• Simply using the CSOM
• Avoid nesting promises
• Reduce boiler plate code
• Provide an easy to read syntax
• Speed up development

This solution can be used in TypeScript or plain JavaScript projects.

Repository: https://github.com/TjWheeler/spJsomFluent

Examples

A quick example

In this example we are get getting the current user profile properties. All the difficulty behind loading the correct scripts and calling the PeopleManager are handled for you.

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

Install modules

npm install

Run the dev build

npm run debug

Run the production build

npm run release

Watch the dev configuration, and recompile as files change

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: ​​​<script src="https://yoursharepoint.sharepoint.com/sites/yoursite/style library/myApp/myApp.js"></script>
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.

.onActionExecuting((actionName:string, current:number, total:number) => {
    let progress = Math.ceil(100 * current / total);
    console.log(`Executing: ${actionName}, we are ${progress}% through.`);
})
            

onExecuted

.onActionExecuted((actionName:string, success:boolean, results: Array<any>) => {
    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:

.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.

...
.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

List Commands

Fluent API spJsom.list

ListItem Commands

Fluent API spJsom.listItem

Navigation Commands

Fluent API spJsom.navigation

Note: Taxonomy based navigation is not currently supported

Permission Commands

Fluent API spJsom.permission

Fluent API spJsom.web

Publishing Page Commands

Fluent API spJsom.publishingPage

User Commands

Fluent API spJsom.user

Web Commands

Note: for template ids check out: See: https://blogs.technet.microsoft.com/praveenh/2010/10/21/sharepoint-templates-and-their-ids/