Interact with Lists the AJAX Way

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

You can use the AJAX, or Asynchronous JavaScript and XML, design approach and set of techniques to deliver a highly interactive, desktop-like user experience for applications designed for Microsoft Office Live Small Business. AJAX achieves this interactivity by having parts of a page reload, instead of the entire page, in response to user input. Small amounts of data are exchanged with the server behind the scenes, and the application remains usable by the site visitor.

AJAX builds on open standards that are widely available as native features (that is, without plug-ins) in popular browsers. AJAX's incremental update techniques are obtained through built-in features such as JavaScript and the XMLHttpRequest API. For more information about AJAX, see the Open AJAX Alliance whitepapers.

The Contact Map code sample is a good example of the use of AJAX techniques to access data from a list contained in Office Live Small Business applications. This example uses JavaScript and the XMLHttpRequest API to enable a rich user interface that enables users to interact with the application while the browser is communicating with the server.

Get Data from a Microsoft Office Live List

The Contact Map code sample maps the business addresses from the Business Contacts list in Contact Manager. In order to accomplish this, it must first get a list of the contacts contained in the Business Contacts list. The JavaScript code in this code sample makes an XML Http request to a Microsoft Windows SharePoint Services Web service to facilitate the process.

The file olsharedlibv1.jsx is included as part of this code sample, and contains the WssSoap function which is designed to aid in making SOAP requests. One of the methods included for this function is getAllListItems. The process that begins with this method ends with an XML HTTP request to the GetListItems method of the Lists Web service in Windows SharePoint Services to get all of the items in a given list. Following are the methods in the file olsharedlibv1.jsx that are involved in the process:

• WssSoap.getAllListItems

• WssSoap.getListItems

• WssSoap.callSoap

• SoapRequest.sendRequest

• SoapRequest.send

WssSoap.getAllListItems

The getAllListItems method starts the process of requesting the data. This method calls WssSoap.getListItems, passing the list name and the field name(s) for the data we are requesting.

Syntax

WssSoap.prototype.getAllListItems = function(strListName, vFields, fCallback)

Parameters

Name	Required/Optional	Data Type	Description
strListName	Required	string	Name of the source list.
vFields	Required	array of strings	Array of field names to get back from the list items.
fCallback	Required	string	Callback function to execute on completion.

Example

// The web context to use is Contact Manager
var strWebContext = document.location.protocol + "//" + 
                    document.location.hostname + "/WebBCM";
// WssSoap object for making Windows SharePoint Services SOAP calls
var g_oWssSoap = null;
g_oWssSoap = new WssSoap(strWebContext);

function getContacts()
{
      g_oWssSoap.getAllListItems("Business Contacts", 
            new Array("ID", "Title", "FirstName", "WorkCity", 
                      "WorkState", "WorkPhone", "Email"), 
                      onGetContactResults);
}

WssSoap.getListItems

The getAllListItems method calls the getListItems method to package the information needed by the callSoap method. The SOAP service that is called, using this method, is the GetListItems SOAP service in Windows SharePoint Services.

Syntax

WssSoap.prototype.getListItems = function(strListName, strViewName, strQuery, strViewFields, strRowLimit, strQueryOptions, strWebID, fCallback)

Parameters

Name	Required/Optional	Data Type	Description
strListName	Required	string	String that contains either the title or the GUID for the list.
strViewName	Optional	string	String that contains the GUID for the view to use for default view attributes.
strQuery	Required	string	Query that determines which records are returned.
strViewFields	Required	string	Specifies which fields to return in the query and in what order.
strRowLimit	Optional	string	Number of items to display before paging begins.
strQueryOptions	Required	string	An XML fragment for the various properties of the SPQuery object.
strWebID	Optional	string	The site ID, if the list belongs to another site.
fCallBack	Required	string	The callback function to execute on completion.

Example

The Contact Map sample includes the constructQueryParameter, constructViewFieldsParameter, and constructQueryOptionsParameter methods to build the parameters necessary for the getListItems method. These methods are beyond the scope of this article, but can be viewed in the olsharedlibv1 file of this sample.

var strQuery = this.constructQueryParameter(null);
var strViewFields = this.constructViewFieldsParameter(vFields);
var strQueryOptions = this.constructQueryOptionsParameter(null, null,   null, false, null, null);
this.getListItems(strListName, null, strQuery, strViewFields, null, strQueryOptions, null, fCallback);

WssSoap.callSoap

The callSoap method creates the vParameters value needed by the sendRequest method to set the SOAP properties.

Syntax

WssSoap.prototype.callSoap = function(strUrl, strAction, vParameters, fCallback)

Parameters

Name	Required/Optional	Data Type	Description
strUrl	Required	string	The URL for the Web service.
strAction	Required	string	The method to call.
vParameters	Required	array of pairs	The array of name-value pairs for the parameter name and values.
fCallBack	Required	string	The callback function to execute on completion.

Example

The getListItems method calls the callSoap method, using parameters passed from getAllListItems.

As the first step in defining the strUrl parameter, which is the URL for the Windows SharePoint Services Lists Web service, a function in the maps.jsx file sets the Web context and creates a global Windows SharePoint Services SOAP object with this Web context.

var strWebContext = document.location.protocol + "//" + document.location.hostname + "/WebBCM";        
var g_oWssSoap = null;                      // WssSoap object for making WSS SOAP calls
g_oWssSoap = new WssSoap(strWebContext);

To finish the strUrl definition, the constructor for the Windows SharePoint Service SOAP object (in the olsharedlibv1 file) creates the URL for the Web service based on the Web context and the URL for the Lists Web service.

this.eWssWebServices = LISTSASMX : "_vti_bin/lists.asmx",
this.setWebContext(strWebContext);

WssSoap.prototype.setWebContext = function(strWebContext)
{
    this.strListsAsmx = strWebContext + "/" + this.eWssWebServices.LISTSASMX;
}

The getListItems function defines the vParameters parameter and calls the callSoap method for this WssSoap object.

var vParameters = new Array();
vParameters["listName"] = strListName;
vParameters["viewName"] = strViewName;
vParameters["query"] = strQuery;
vParameters["viewFields"] = strViewFields;
vParameters["rowLimit"] = strRowLimit;
vParameters["queryOptions"] = strQueryOptions;
vParameters["webID"] = strWebID;

this.callSoap(this.strListsAsmx, "GetListItems", vParameters, fCallback);

SoapRequest.sendRequest

The sendRequest method sets the soapAction and soapEnvelope properties to prepare for the post to the Web service.

Syntax

SoapRequest.prototype.sendRequest = function(strUrl, strAction, strXmlNS, vParameters, fCallback)

Parameters

Name	Required/Optional	Data Type	Description
strUrl	Required	string	The URL for the Web Service.
strAction	Required	string	The method to call.
strXmlNS	Required	string	The XML namespace for the method.
vParameters	Required	array of pairs	The array of name-value pairs for the parameter names and values.
fCallBack	Required	string	The callback function to execute on completion.

Return Value

The sendRequest method returns the XML HTTP request object from the send method so the caller can look at the response.

Example

The callSoap method calls sendRequest, passing the same parameters it received in the callSoap example above.

var oSoapRequest = new SoapRequest();
oSoapRequest.sendRequest(strUrl, strAction, this.strSoapNS, vParameters, fCallback);

SoapRequest.send

The send method creates the new XML HTTP request object and performs a post to the Lists Web service. The combination of this XML HTTP request and the JavaScript code provides the AJAX functionality improvements demonstrated in this code sample.

Syntax

SoapRequest.prototype.send = function()

Return Value

If synchronous, returns the XML HTTP request object so the caller can look at the response.

Example

return this.send();

See Also

Concepts

Business Contacts Schema

Contact Map Code Sample