OpenFaces library has a range of Ajax-powered features built-in into components themselves, and various means for introducing generic inter-component Ajax-based interactions. The generic Ajax support is provided by the appropriate attributes in the OpenFaces command components, such as <o:commandButton>, <o:commandLink>, <o:menuItem>, and <o:captionButton>. In addition to this, there's a generic mechanism provided by the Ajax component. This is a non-visual component that can be attached to any other JSF component to reload other components when some particular event occurs. Actually the Ajax component has a wider purpose than just reloading components which makes it possible to perform dynamic page updates to meet a wide range of scenarios that require Ajax page updates. Please see the Ajax component documentation page for the detailed information on its capabilities and usage instructions.
The OpenFaces components that have built-in Ajax features are configured to use Ajax by default. This is acceptable for the majority of cases, though it is sometimes needed to disable Ajax support for a particular component. This can be done on a per-component basis. Please refer to a documentation on respective components for instructions on disabling Ajax. When Ajax support is turned off, the page is submitted whenever data update is needed, instead of making an Ajax request.
OpenFaces also provides an ability to customize various aspects of Ajax processing such as Ajax progress message, the way of handling session expiration during Ajax requests, and receiving notifications of 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 on a page-wide level using the AjaxSettings component.
As described in the subsections below, the AjaxRequest class gives a programmatic control over some aspects of Ajax requests. An instance of the AjaxRequest class corresponding to the current Ajax request can be received using the static AjaxRequest.getInstance() function. This function returns null if the current request is not an OpenFaces Ajax request.
Besides executing server actions and reloading components, the OpenFaces Ajax framework allows passing the application-specific data along with any Ajax request. The value that is returned to the client side along with the Ajax request is called the ajaxResult value. ,The application action handlers can use one of the following three approaches for specifying the ajaxResult value:
The ajaxResult value, can have one of the following types:
The list of components that should be reloaded during the Ajax request is usually specified with the render attriute of a component which triggers the Ajax request (e.g. in the <o:ajax>, or <o:commandButton> tag). Nevertheless it is also possible to add more reloaded components programmatically during the Ajax request itself. To do this, the Ajax event processing code should use one of the addReloadedComponent functions of the AjaxRequest class. This function receives either client Id of the reloaded component or the UIComponent reference.
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.
To specify the way of how session expiration during Ajax request is handled you should use the org.openfaces.ajax.sessionExpiration application-scope context parameter in web.xml file. This property has two possible values:
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>
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 org.openfaces.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>org.openfaces.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>
Configuration of all Ajax-related settings for the particular page can be done by placing the AjaxSettings component on the page. To add the AjaxSettings component to a page, use the <o:ajaxSetting> tag. There should be only one <o:ajaxSetting> tag on the page.
The AjaxSettings component overrides the application-scope context parameters for the particular page. You can specify two facets for the <o:ajaxSettings> tag:
The <o:ajaxSettings> tag also has attributes to configure Ajax-related events. For more information please see the Ajax Request Lifecycle Events section.
The way how session expiration during Ajax requests is handled can be configured using the "sessionExpiration" facet of the <o:ajaxSetting> tag. You can define use of the following tags in the "sessionExpiration" facet:
The following example demonstrates the usage of the "sessionExpiration" facet. The page with this AjaxSettings tag is reloaded when the session is expired.
<o:ajaxSettings> <f:facet name="sessionExpiration"> <o:silentSessionExpiration/> </f:facet> </o:ajaxSettings>
You can customize the Ajax progress message for a separate page by using the <o:defaultProgressMessage> tag. This tag should be declared in the "progressMessage" facet of the <o:ajaxSettings> tag.
This tag lets you can customize a text and an image, and a style for the progress message. The text can be customized using the text attribute of the <o:defaultProgressMessage> tag. The URL to the image file that is displayed besides the text can be specified using the imageUrl attribute. To apply styles for the progress message, use the style and styleClass attributes.
You can customize the position of the Ajax progress message using the horizontalAlignment (accepts "left", "center", and "right" values), and the verticalAlignment (accepts "top", "center", and "bottom" values).
It is possible to shade contents of the browser window while Ajax request is in progress to prevent mouse operations with the document until the request finishes. This can be done by setting the fillBackground attribute to true. Style, transparency level and transparency transition period for the background layer of Ajax progress message can be customized with the backgroundStyle/backgroundClass, backgroundTransparency, and backgroundTransparencyTransitionPeriod attributes respectively.
Here is an example of using the DefaultProgressMessage component:
<o:ajaxSettings> <f:facet name="progressMessage"> <o:defaultProgressMessage imageUrl="ajaxImage.png" text="Custom loading message" style="color: green; border: 2px solid green;"/> </f:facet> </o:ajaxSettings>
You can specify Ajax-related client-side events using the following attributes of the <o:ajaxSettings> tag:
Please be aware of the following limitations when using the Ajax-enabled components:
|© 2010 TeamDev Ltd.|