How to: Interact with Business Application Lists the AJAX Way

  • Article

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 (i.e., 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 Microsoft Office Live 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 an Office Live Small Business list

The Contact Map feature maps the business addresses from the Contacts list in Office Live Small Business Contact Manager. In order to accomplish this, it must first get a list of the contacts contained in the 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.js 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.js that are involved in the process:

  1. WssSoap.getAllListItems
  2. WssSoap.getListItems
  3. WssSoap.callSoap
  4. SoapRequest.sendRequest
  5. 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

  
var g_oWssSoap = null;                      // WssSoap object for making Windows SharePoint Services SOAP calls
function getContacts()
{
      g_oWssSoap.getAllListItems("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 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.

  1. 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.js 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);

    1. To finish the strUrl definition, the constructor for the Windows SharePoint Service SOAP object (in the olsharedlibv1 file) creates the URL of the Web service based on the Web context and the URL of 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;
}

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