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();