JS Enhancements

The Sponge JavaScript API provides easy access to the most common SharePoint API, however its a lot more easy to use than the OOTB methods! Have a look at the following examples:

####Loading All Items Consider the following basic example. It gets the current list (if selected), loads all items from it and displays the item's title.

//this will get a reference to the list if the list is selected
var list = sponge.lists.getCurrentList();

//gets the items with the default query (all items)
var items = list.getItems(sponge.lists.getDefaultQuery());

//this will load the items (load and executeQueryAsync)
//Note: Before calling the .load() method in any way, 
//all objects will not be populated by sponge/SharePoint.
sponge.ctx.load(items, null,
	function() {
	    //iterate all items and display the title
	    for(var i = 0; i < items.length; i++) {
	      	console.log(items[i].get_item("Title"));
	    }
  	},
  	function(sender, args) {
    	//will display the error if something goes wrong
    	console.log(args.get_message());
  	}
);

####Loading a specific Item Now let's say you only want to load the Item with ID = 1 and only the "Title" Field of it...

var list = sponge.lists.getCurrentList();

//get item with ID = 1
var item = list.getItemById(1);

//load the item with field 'Title'
sponge.ctx.load(item, "Title",
	function() {
		console.log(item.get_item("Title"));
  	},
  	function(sender, args) {
    	console.log(args.get_message());
  	}
);

####Loading multiple Items with specific Field

var list = sponge.lists.getCurrentList();

//get item with ID = 1
var item1 = list.getItemById(1);

//get item with ID = 2
var item2 = list.getItemById(2);

//load the item with field 'Title'
sponge.ctx.load([item1, item2], "Title",
	function() {
		console.log(item1.get_item("Title"));
		console.log(item2.get_item("Title"));
  	},
  	function(sender, args) {
    	console.log(args.get_message());
  	}
);

####Loading multiple Items with multiple Fields Loading multiple objects with different Fields is also possible...

var list = sponge.lists.getCurrentList();

var objects = new Array();

//get the objects
var item1 = list.getItemById(1);
var item2 = list.getItemById(2);

//add the objects to the array
//this will load item1 with only the Title field
//and item2 with Title and Status field
objects.push( { data : item1, fields : "Title" });
objects.push( { data : item2, fields : ["Title", "Status"] });

//load the item with field 'Title'
sponge.ctx.load(objects, null,
	function() {
		console.log(item1.get_item("Title"));
		console.log(item2.get_item("Title") + " - " + item2.get_item("Status"));
  	},
  	function(sender, args) {
    	console.log(args.get_message());
  	}
);

####Loading the current User Loads the current User and log's his/her email address

var list = sponge.user.loadCurrentUser(function(usr) {
	//the usr object has now been loaded, and all properties can be used
	console.log(usr.get_email());
});

##Methods

###sponge.ctx

Method	Description
sponge.ctx.current	the SP.ClientContext.get_current() context, can be used to make any SP requests
sponge.ctx.web	the current SP.Web
sponge.ctx.load(object, fields, success, error)	loads the object with the given fields and executes the request. depending on the outcome, either the success or the error function will be called.
sponge.ctx.execute()	makes the request for all pending (loaded) objects.

###sponge.lists

Method	Description
sponge.lists.getCurrentList()	returns the current list object if selected, otherwise undefined.
sponge.lists.loadCurrentList(callback)	loads and returns the current list object (all properties are now accessible).
sponge.lists.getSelectedItemIds()	returns an array of the selected items in a list (checkbox or ECB dropdown).
sponge.lists.getSelectedItems()	returns an array of the selected items (as object) in a list.
sponge.lists.loadSelectedItems(callback)	loads and returns the selected items (As object) in a list.
sponge.lists.getDefaultQuery()	returns a default SP CAML Query (all items, no row limit) that can be used in the list.getItems method.

###sponge.common

Method	Description
sponge.common.executeCallback(callback)	executes the passed function if not undefined or null.
sponge.common.isArray(object)	checks whether the given object is an array.
sponge.common.format()	string.format function like in C#.
sponge.common.encodeXmlString(text)	xml encode's the given text, so its valid for SOAP calls.

###sponge.user

Method	Description
sponge.user.loadCurrentUser(callback)	loads the current logged in user, so all properties are accessible i.e user.get_email();

###sponge.logging

Method	Description
sponge.logging.name	sets the 'TeamName' of the ULS Log entry. Default = "sponge Logging Service".
sponge.logging.logMessage(message, stack, success, error)	logs an entry to the ULS log with 'message and stack', calls success or error callback methods based on outcome.
sponge.logging.logException(err, success, error)	logs an entry to the ULS log using the (JavaScript) exception 'err', calls success or error callback methods based on outcome.

Back to JavaScript API.