Ajax Support

Introduction

The QuipuKit components use Ajax in cases when data should be dynamically loaded from the server after a page is loaded. The following components support Ajax-based dynamic data loading: DataTable, TreeTable, FoldingPanel, TabbedPane, DropDownField and SuggestionField.

Note that the QuipuKit components use Ajax only for those updates that are triggered by the components themselves (like paging and sorting in a DataTable or tab switching in a TabbedPane).

The QuipuKit components use Ajax by default. However, there are cases where Ajax cannot be used:

• Some browsers do not support all Ajax usage scenarios. This mainly concerns Opera and Safari browsers that don't support dynamic stylesheet manipulation.
• Some third-party components do not work correctly inside the components using Ajax.

To avoid these problems, you can disable Ajax support for any component. For more details on how to do it, please refer to our documentation on respective components. When Ajax support is turned off, the page is submitted whenever data update is needed, instead of making an Ajax request.

QuipuKit also provides an ability to customize the way of handling session expiration during Ajax requests, to customize the progress message and define Ajax related events. The way of handling session expiration and customizing progress message can be configured for the whole application by using the application-scope parameters in web.xml file or for a separate page.

Application-Wide Configuration

You can configure the way of handling session expiration during Ajax request and configure Ajax progress message for the whole application by specifying the application-scope context parameters in web.xml file. These parameters can be overridden by the AjaxSettings component for the separate page.

Handling Session Expiration for the Application

To specify the way of how session expiration during Ajax request is handled you should use the teamdev.jsf.ajax.sessionExpiration application-scope context parameter in web.xml file. This property has two possible values:

• "default" (default). The confirmation that asks the user to reload the page appears when the current session is expired.
• "silent". The page is reloaded when the current session is expired.

In order for the session expiration feature to work properly with MyFaces 1.2, add the following lines to the WEB-INF/web.xml file:

<context-param>
    <param-name>org.apache.myfaces.ERROR_HANDLING</param-name>
    <param-value>false</param-value>
</context-param>

Specifying Ajax Progress Message for the Application

When any Ajax request is in progress, the "Loading..." message appears in the upper-right corner of the screen. This message is displayed by default. You can configure this message for the whole application or for the particular page.

You can change the Ajax progress message for the whole application by specifying the teamdev.jsf.ajaxMessageHTML parameter in web.xml. This parameter should be specified as portion of HTML that will be shown in the upper-right corner on an Ajax request.

For example you can add the following code to web.xml:

<context-param>
  <param-name>teamdev.jsf.ajaxMessageHTML</param-name>
  <param-value><![CDATA[
    <div style="background: white;
                font: Tahoma 15pt normal;
                border: 1px solid black;">
      <img src="/testapp/images/progress.gif"/>
      Ajax request is currently in progress!
    </div>
  ]]></param-value>
</context-param>

Page-Wide Configuration

Configuration of all Ajax-related settings for the particular page can be done by using the AjaxSettings component in the page. To add the AjaxSettings component to a page, use the <q:ajaxSetting> tag. There should be only one <q:ajaxSetting> tag in the page.

The AjaxSettings component overrides the application-scope context parameters for the particular page. You can specify two facets for the <q:ajaxSettings> tag:

• "sessionExpiration" is used for handling session expiration for the page.
• "progressMessage" is used for specifying Ajax progress message.

The <q:ajaxSettings> tag also has attributes to configure Ajax-related events. For more information please see the Specifying Ajax-Related Client-Side Events section.

Handling Session Expiration for the Page

The way how session expiration during Ajax request is handled is configured by using the "sessionExpiration" facet of the AjaxSession tag. You can define one of the following tags in the "sessionExpiration" facet:

• <q:defaultSessionExpiration>. The confirmation that asks the user to reload the page when the current session is expired appears.
• <q:silentSessionExpiration>. The page is reloaded when the current session is expired.

The following example demonstrates the usage of the "sessionExpiration" facet. The page with this AjaxSettings tag is reloaded when the session is expired.

<q:ajaxSettings>
  <f:facet name="sessionExpiration">
    <q:silentSessionExpiration/>
  </f:facet>
</q:ajaxSettings>

You can also specify a JavaScript code that should be executed when the current session is expired. For more details please see the Specifying Ajax-Related Client-Side Events section.

Please note that if the onsessionexpired event is specified together with "sessionExpiration" facet, first the JavaScript code specified in the onsessionexpired event and then the logic from "sessionExpiration" facet is executed. However, if the JavaScript code specified for the onsessionexpired event returns false, the logic of DefaultSessionExpiration or SilentSessionExpiration components is not executed at all.

Specifying Ajax Progress Message for the Page

You can customize the Ajax progress message for a separate page by using the <q:defaultProgressMessage> tag. This tag should be declared in the "progressMessage" facet of the <q:ajaxSettings> tag.

You can customize text and image for the message and also apply style for the whole progress message. Text can be customized by using the text attribute of the <q:defaultProgressMessage> tag. The URL to the image file that is rendered before text in the progress message can be defined by the imageUrl attribute. To apply styles for the progress message, use the style and styleClass attributes.

Here is an example of using the DefaultProgressMessage component:

<q:ajaxSettings>
  <f:facet name="progressMessage">
    <q:defaultProgressMessage imageUrl="ajaxImage.png" text="Custom loading message"
                              style="color: green; border: 2px solid green;"/>
  </f:facet>
</q:ajaxSettings>

Handling Ajax Errors

When any error occurs while Ajax request is performed, a JavaScript alert message with information about error appears by default. You can change this behavior by specifying the onerror attribute of the AjaxSettings component. This attribute specifies JavaScript code that should be executed when an error occurs while performing an Ajax request. If the JavaScript code specified on the onerror attribute returns false, the default error message alert is not displayed.

Specifying Ajax-Related Client-Side Events

You can specify Ajax-related client-side events by using the following attributes of the AjaxSettings component: