Ajax Framework |
||||||||||||
Developer’s Guide Home
Installation and Configuration Common Concepts Components Index Border Layout Panel Calendar Chart Command Button Command Link Confirmation Data Table Date Chooser Day Table Drop Down Field Dynamic Image Folding Panel For Each Graphic Text Hint Label Input Text Input Textarea Layered Pane Popup Layer Popup Menu Select Boolean Checkbox Select Many Checkbox Select One Radio Spinner Suggestion Field Tabbed Pane Tab Set Tree Table Two List Selection Window Focus Load Bundle Scroll Position Ajax Framework Validation Framework Tag Reference API Reference |
IntroductionOpenFaces 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. Note Application-Wide ConfigurationYou 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. Session Expiration SettingsTo 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>
Ajax Progress Message SettingsWhen 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>
Page-Wide ConfigurationConfiguration 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. Session Expiration SettingsThe 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 also specify a JavaScript code that should be executed when the current session is expired. For more details please see the Ajax Request Lifecycle Events section. Please note that if the onsessionexpired event is specified together with "sessionExpiration" facet, first the JavaScript code specified in the onsessionexpired event is executed and then goes the logic specified by the "sessionExpiration" facet. However, if the JavaScript code specified for the onsessionexpired event returns false, the logic of DefaultSessionExpiration or SilentSessionExpiration components is not executed at all allowing the custom application code to handle session expiration in an application-specific way. Ajax Progress Message SettingsYou 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> Handling Ajax ErrorsWhen any error occurs while Ajax request is performed, a JavaScript alert message with information about the 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. Ajax Request Lifecycle EventsYou can specify Ajax-related client-side events using the following attributes of the <o:ajaxSettings> tag:
|
|||||||||||
© 2009 TeamDev Ltd. | ![]() |