Walkthrough

This short walkthrough will expose you to the main features of Caffeine. The goal is to quickly show you the primary uses of Caffeine to get you up and running quickly. Afterwards please look at the API documentation for more information.

Getting Started

Today Caffeine is a fairly light weight library. It’s primary function is to work with SharePoint’s web services from client-side Javascript. Over time it will be expanded to include additional abstractions for objects such as users, forms, and pages.

Important!!
Caffeine requires the Prototype Javascript library. Make sure you download prototype and include it wherever the Caffeine library is referenced.

To get started with Caffeine, simply add a reference to caffeine.js in your SharePoint page. This can be referenced from a Content Editor web part, part of a Master Page or Page Layout, or on any existing page through the use of SharePoint Designer. You can upload caffeine.js and prototype.js to a document library in your SharePoint site, or deploy it to the _layouts directory on your SharePoint server. The location is not important so long as you can reference it from your SharePoint page.

<script type='text/javascript' src='/sites/mysite/doclib/prototype.js'></script>
<script type='text/javascript' src='/sites/mysite/doclib/caffeine.js'></script>

Setting Context

Many functions in Caffeine need to know what site you wish to work with. If most of your work is going to be with a single SharePoint site, you can set the context for your work once so you don’t have to keep specifying the site URL. This is done by calling the Caffeine.setContext function:

// set the context for the current site
Caffeine.setContext('http://myserver/sites/mysite');

Call a Web Service

Next let’s call one of SharePoint’s web services. In this example we will call the UserGroup web service to get details on a particular user.

// set the context
Caffeine.setContext('http://myserver/sites/mysite');

// call the service
var ws = new Caffeine.WebServices.UserGroup();
ws.executeMethod(
    "GetUserInfo",
    { userLoginName: "DOMAIN\\username" },
    callback);

// handle the callback by alerting the results
function callback(output) {
    alert(output.httpResponse.responseText);
}

Let’s look at the previous example. First we set up the context so that Caffeine knew what site we were working in. Next, we instantiated a new instance of the UserGroup web service. All web services are instantiated this way. The Lists.asmx web service would be new Caffeine.WebServices.Lists(), SiteData.asmx would be new Caffeine.WebServices.SiteData() and so on. Also note that the constructor for each web service object also takes an optional url parameter. If this parameter is provided, Caffeine will use the value provided as the site Url instead of the current context.

After the UserGroup object was created we call the executeMethod method passing three parameters. The first parameter is the name of method to call. This value is case sensitive. The next parameter is an object containing all parameters to pass to the web service. The third parameter is a function which will handle the results of the web service call.

Working with Web Service results

More Examples
We’ve just gone through