AJAX Support

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Back to Developer Guide.

Table of Contents

• 1 Introduction

• 2 Client Side
  
  
  • 2.1 Dojo
  • 2.2 YUI

• 3 Servlet

• 4 Debugging

• 5 Examples

Introduction

This page outlines the AJAX support present in version 1.4 and later.

The client side support for making AJAX requests is provided by the Dojo Toolkit and YUI. The server side support consists of a servlet that provides access to configured managed beans.

Client Side

Dojo

To include the Dojo AJAX support on your page add the following lines:

</script>
</script>

If you are developing a JSF component there is also a utility method available which will write out the above statements, additionally ensuring they are only written once per page.

Utils.writeDojoScripts(FacesContext context, ResponseWriter out);

dojo.js is the main Dojo library, common.js contains the Alfresco utility functions, for example, a common error handling method and some DOM access helper methods.

To make the AJAX request, the dojo.io.bind() function is used. Using the invoke command example below the following code is required:

dojo.io.bind({
   method: 'post',
   url: getContextPath() + '/ajax/invoke/NodeInfoBean.sendInfo',
   content: { ticket: '123456789'},
   load: handleInfo,
   error: handleErrorDojo,
   mimetype: 'text/html'
});

Dojo has many more options that can be set when making requests, see their documentation for those. Most of the options above are self explanatory but they're explained below for completeness.

method: The HTTP method to use, either 'post' or 'get'

url: The URL for the request (can also contain query string parameters)

content: Parameters for the request

load: The function to callback when the request has completed, can either be a reference to a function defined elsewhere or an inline definition.

error: The function to callback when the request fails, you'll normally use handleErrorDojo which is the Alfresco error  handling function.

mimetype: Indicates how to deal with the response. NOTE: It doesn't actually matter what the content type of the response is, this simply tells Dojo internally what code path to use. This also does NOT set the content type of the HTTP request.

The signature for the load function handler is function handleInfo(type, data, evt). This method can then perform whatever action is required on the client side, for example, updating a value and applying a visual effect may be done as follows:

function handleInfo(type, data, evt)
{
   var elem = dojo.byId('some-element');
   elem.value = data;
   dojo.lfx.highlight(elem, '#ffff00', 3000, dojo.lfx.easeOut, null).play();
}

YUI

To include the YUI AJAX support on your page add the following lines:

</script>
</script>
</script>

If you are developing a JSF component there is also a utility method available which will write out the above statements, additionally ensuring they are only written once per page.

Utils.writeYahooScripts(FacesContext context, ResponseWriter out, String scripts);

yahoo-min.js is the base YUI library, connection-min.js provides the IO calls and common.js contains the Alfresco utility functions, for example, a common error handling method and some DOM access helper methods.

To make the AJAX request, the asyncRequest function is used. Using the invoke command example below the following code is required:

YAHOO.util.Connect.asyncRequest('GET | POST', getContextPath() + '/ajax/invoke/NodeInfoBean.sendInfo', 
   { 
      success: handleInfo,
      failure: handleErrorYahoo
   }, 
   null);

YUI has many more options that can be set when making requests, see their documentation] for those. The options shown above are explained below.

The first parameter should be set to 'GET' or 'POST' depending on the type of request you want. The second parameter is the URL to call, the third parameter is what YUI calls a 'callback' object and the last parameter is any post data you want to send.

The 'callback' object provides the functions to call upon success or failure of the AJAX request.

The signature for the success function handler is function handleInfo(response). This method can then perform whatever action is required on the client side, for example, updating the HTML of an element with the response data may be done as follows:

function handleInfo(response)
{
   var elem = document.getElementById('some-element');
   elem.innerHTML = response.responseText;
}

Servlet

As mentioned above a servlet (org.alfresco.web.app.servlet.ajax.AjaxServlet) is used for handling AJAX requests. The URL for the servlet takes the following form:

<host>/alfresco/ajax/<command>/<binding expression>

command can be either invoke or get.

binding expression is the part of a JSF binding expression between the #{ and }. When using the invoke command the expression will represent a JSF method binding expression and when the get command is used the expression will represent a JSF value binding expression.

For example to invoke the sendInfo() method on the NodeInfoBean you would use the following URL:

localhost:8080/alfresco/ajax/invoke/NodeInfoBean.sendInfo

Or to call the getInfo method on the same bean you would use the following URL:

localhost:8080/alfresco/ajax/get/NodeInfoBean.info

The invoke command (org.alfresco.web.app.servlet.ajax.InvokeCommand) is used to invoke arbitrary (no parameter) methods on any configured managed bean. This approach will probably used for most scenarios. The bean method that gets called when using the invoke command is responsible for writing the results to the JSF ResponseWriter object. This allows streaming responses i.e. you don't have to wait for the whole result to be built before sending it back to the client.

Currently, the response content type is always set to 'text/html', in a future release there will be a way for the method being called to specify what content type should be used for the response. If the method requires parameters these can be retrieved from the JSF ExternalContext object, this approach means it's easy to support AJAX in the servlet and portlet environments. Finally, the command sets up a transaction before calling the managed bean method and handles the commit and rollback scenarios.

The get command (org.alfresco.app.servlet.ajax.GetCommand) is provided to allow access to existing managed beans. The command itself is therefore responsible for handling the response as existing beans will have no knowledge of AJAX. The resulting object from the get call will be added directly to the response in String form and the response content type will always be set to 'text/html'.

The servlet will perform authentication checks before allowing execution of the managed bean method. As with other Alfresco servlets the ticket parameter can be tagged on to the URL as follows:

localhost:8080/alfresco/ajax/get/NodeInfoBean.info?ticket=123456789

Alternatively, if the servlet is called within a pre-authenticated session the credentials of the current user will be used. As always, if the user attempts to perform an action they don't have permission to do an Access Denied exception is thrown as usual.

The AJAX servlet is different than other Alfresco servlets in one way, if authentication fails the login page is not redirected to the appropriate HTTP error code is returned. This allows the client side to handle this scenario properly rather than receiving the HTML representing the login page, which could be perceived as a valid response!

Debugging

To enable debugging for the AJAX support add the following line to log4j.properties:

log4j.logger.alfresco.ajax=debug

Examples

The main use of AJAX in the web client are the Tree and OpenSearch sidebar plugins.

There is also a sample AJAX component available which is disabled by default as it's not production quality yet.

To enable the component add the following config to your web-client-config-custom.xml file:

<config>
   <client>
      <ajax-enabled>true</ajax-enabled>
   </client>
</config>

To see the component in action change to 'Browse View' and hover your mouse over the title of a space. You should see a summary panel fade into view and fade away when your mouse moves away from the space title.
Alfresco Explorer
Web Client Customization