Ajax4jsf Developer Guide

Ajax4jsf leverages JavaServer Faces framework including lifecycle, validation, conversion facilities and management of static and dynamic resources. Ajax4jsf rich components with built-in AJAX support and a highly customizable look-and-feel can be easily incorporated into JSF applications.

Ajax4jsf allows to:

Intensify the whole set of JSF benefits while working with AJAX. Ajax4jsf is fully integrated into the JSF lifecycle. While other frameworks only give you access to the managed bean facility, Ajax4jsf advantages the action and value change listeners, as well as invokes server-side validators and converters during the AJAX request-response cycle.

Add AJAX capability to existing JSF applications. The framework is implemented by using a component library. The library sets AJAX functionality into existing pages, so there is no need to write any JavaScript code or to replace existing components with new AJAX one. Ajax4jsf enables page-wide AJAX support instead of the traditional component-wide support and it gives the opportunity to define the event on the page. An event invokes an AJAX request and areas of the page which are synchronized with the JSF Component Tree after changing the data on the server by AJAX request in accordance with events fired on the client.

Write your own custom rich components with built-in AJAX support. In the near future, a full Component Development Kit (CDK) for Ajax4jsf will be realized. The CDK includes a code-generation facility and a templating facility using a JSP-like syntax. These capabilities help to avoid a routine process of a component creation. The component factory works like a well-oiled machine allowing the creation of first-class rich components with built-in AJAX functionality even more easily than the creation of simpler components by means of the traditional coding approach.

Package resources with application Java classes. In addition to its core, AJAX functionality of Ajax4jsf provides an advanced support for the different resources management: pictures, JavaScript code, and CSS stylesheets. The resource framework makes possible to pack easily these resources into Jar files along with the code of your custom components.

Easily generate images on-the-fly. Resource framework can generate images on-the-fly so that it becomes possible to create images using the familiar approach of the "Java Graphics2D" library.

Create a modern rich user interface look-and-feel with skins-based technology. Ajax4jsf provides a skinnability feature that allows easily define and manage different color schemes and other parameters of the UI with the help of named skin parameters. Hence it is possible to access the skin parameters from JSP code and the Java code (e.g. to adjust generated on-the-fly images based on the text parts of the UI).

Note:

skinnability is not an equivalent of traditional CSS, but a complement.

Test and create the components, actions, listeners, and pages at the same time. An automated testing facility is in our roadmap for the near future. This facility will generate test cases for your component as soon as you develop it. The testing framework will not just test the components, but also any other server-side or client-side functionality including JavaScript code. What is more, it will do all of this without deploying the test application into the Servlet container.

Ajax4jsf components come ready to use out-of-the-box, so developers save their time and immediately gain the advantage of the mentioned above features in Web applications creation. As a result, usage experience can be faster and easily obtained.

Chapter 2. Technical Requirements

Ajax4jsf is an open architecture framework developed to be compatible with widespread environments.

This is what you need to start working with Ajax4jsf:

Java
JavaServer Faces
Java application server or servlet container
Browser (on client side)

2.1. Supported Java Versions

JDK 1.4 - 1.6

2.2. Supported JavaServer Faces Implementations

Sun JSF 1.1 RI - 1.2
MyFaces 1.1.1 - 1.1.5
Facelets JSF 1.1.1 - 1.2

2.3. Supported Servers

Apache Tomcat 4.1 - 6
IBM Web Sphere 5.1 - 6
BEA Web Logic 8.1 - 9
Oracle AS/OC4J 10.1.3
Resin 3.0
Jetty 5.1.X
Sun Application Server 8 (J2EE 1.4)
Glassfish (J2EE 5)
JBoss 3.2 - 4.x
Sybase EAServer 6.0.1

2.4. Supported Browsers

Internet Explorer 5.5 - 7
Firefox 1.5 - 2.0
Opera 8.5 - 9.0
Netscape 7.0
Safari 2.0
Conqueror 3 and higher

This list is composed basing on reports received from our users. We assume the list can be incomplete and absence of your environment in the list doesn't mean incompatibility.

We appreciate your feedback on platforms and browsers that aren't in the list but are compatible with Ajax4jsf. It helps us to keep the list up-to-date.

Chapter 3. Settings for different environments

Ajax4jsf comes with support for all tags (components) included in the JavaServer Faces specification. To add Ajax4jsf capabilities to an existing JSF project you should just put the Ajax4jsf libraries into the lib folder of the project and add filter mapping. The behavior of the existing project doesn't change just because of Ajax4jsf.

3.1. Web Application Descriptor parameters

These parameters help with development and increase the flexibility of Ajax4jsf use.

Table 3.1. Initialization Parameters

Name	Default	Description
org.ajax4jsf.LOGFILE	none	The is an URL to an application or a container log file (if possible). If this parameter is set, a content from the given URL will be shown on a Debug error page in the iframe window
org.ajax4jsf.VIEW_HANDLERS	none	Is a comma-separated list of custom "ViewHandler" instances for inserting in chain. Handlers are inserted in the given order. So must be used if the order of them is important. No need to define ajax4jsf handler there, as it will be always the first.
org.ajax4jsf.CONTROL_COMPONENTS	none	Is a comma-separated list of names for a component as a special control case, such as messages bundle loader, alias bean components, etc. Is a type of component got by a reflection from the static field COMPONENT_TYPE. For components with such types encode methods always are called in rendering AJAX responses, even if a component isn't in an updated part
org.ajax4jsf.ENCRYPT_RESOURCE_DATA	false	For generated resources, such as encrypt generation data, it's encoded in the resource URL. For example, URL for an image generated from the mediaOutput component contains a name of a generation method, since for a hacker attack, it is possible to create a request for any JSF baked beans or other attributes. To prevent such attacks, set this parameter to true in critical applications (works with JRE > 1.4)
org.ajax4jsf.ENCRYPT_PASSWORD	random	Is a password for encrypt resources data. If isn't set, random password is used
org.ajax4jsf.SKIN	DEFAULT	Is a name of a skin used in an application. It can be a literal string with a skin name, or the EL expression (#{...}) pointed to a String property (skin name) or a property with the type org.ajax4jsf.framework.skin. Skin in last case, this instance will be used as a current skin
org.ajax4jsf.COMPRESS_SCRIPT	true	It doesn't allow A4J to reformat JavaScript files (makes it impossible to debug)

Table 3.2. org.ajax4jsf.Filter Initialization Parameters

Name	Default	Description
log4j-init-file	-	Is a path (relative to web application context) to the log4j.xml configuration file, it can be used to setup per-application custom logging
enable-cache	true	Enables caching of framework-generated resources (Javascript, CSS, images, etc). For debug purposes - development custom JavaScript or Style - prevent to use old cached in browser
forceparser	true	Forces parsing by a filter HTML syntax checker on any JSF page. If false, only AJAX responses are parsed to syntax check and conversion to well-formed XML. Setting to false improve performance, but can provide visual effects on AJAX updates

3.2. Sun JSF RI

Ajax4jsf works with any implementation of JSF (both JSF 1.1 and JSF 1.2) and with most JSF component libraries without any additional settings. For more information look at:

java.sun.com

3.3. Apache MyFaces

Ajax4jsf works with all Apache MyFaces versions (1.1.1 - 1.1.5) including specific libraries like Tomahawk Sandbox and Trinidad (the previous ADF Faces). However, there are some considerations to take into account for configuring applications to work with MyFaces and Ajax4jsf.

There are some problems with different filters defined in the web.xml file clashing. To avoid these problems, the Ajax4jsf filter must be the first one among other filters in the web.xml configuration file.

For more information look at:http://myfaces.apache.org

There's one more problem while using MyFaces + Seam. If you use this combination you should use <a4j:page> inside <f:view> (right after it in your code) wrapping another content inside your pages because of some problems in realization of <f:view> in myFaces.

The problem is to be overcome in the nearest future.

3.4. Facelets Support

A high-level support for Facelets is one of our main support features. When working with Ajax4jsf, there is no difference what release of Facelets is used.

You should also take into account that some JSF frameworks such as Facelets use their own ViewHandler and need to have it first in the chain of ViewHandlers and the Ajax4jsf AjaxViewHandler is not an exception. At first Ajax4jsf installs its ViewHandler in any case, so in case of two frameworks, for example Ajax4jsf + Facelets, no changes in settings are required. Although, when more then one framework (except Ajax4jsf) is used, it's possible to use the VIEW_HANDLERS parameter defining these frameworks view handlers according to its usage order in it. For example, the declaration:

Example:

    <context-param>
      <param-name>org.ajax4jsf.VIEW_HANDLERS</param-name>
      <param-value>com.sun.facelets.FaceletViewHandler</param-value>
    </context-param>

says that Facelets will officially be the first, however AjaxViewHandler will be a little ahead temporarily to do some small, but very important job.

Note:

In this case you don't have to define FaceletViewHandler in the WEB-INF/faces-config.xml.

3.5. JBoss Seam Support

Ajax4jsf 1.1 now works out-of-the-box with JBoss Seam and Facelets running inside JBoss AS 4.0.4 and higher. There is no more shared JAR files needed. You just have to package the Ajax4jsf library with your application.

Your web.xml still must be like this:

web-app version="2.4" 
    xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

   <!-- Seam -->
   <listener>
       <listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
   </listener>

   <!--  ajax4jsf -->
   <filter>
       <display-name>Ajax4jsf Filter</display-name>
       <filter-name>ajax4jsf</filter-name>
       <filter-class>org.ajax4jsf.Filter</filter-class>
   </filter>
   <filter-mapping>
      <filter-name>ajax4jsf</filter-name>
      <url-pattern>*.seam</url-pattern>
   </filter-mapping>

   <!-- Propagate conversations across redirects -->
   <filter>
       <filter-name>Seam Redirect Filter</filter-name>
       <filter-class>org.jboss.seam.servlet.SeamRedirectFilter</filter-class>
   </filter>
   <filter-mapping>
       <filter-name>Seam Redirect Filter</filter-name>
       <url-pattern>*.seam</url-pattern>
   </filter-mapping>
   
  <filter>
    <filter-name>Seam Exception Filter</filter-name>
    <filter-class>org.jboss.seam.servlet.SeamExceptionFilter</filter-class>
  </filter>

  <filter-mapping>
      <filter-name>Seam Exception Filter</filter-name>
      <url-pattern>*.jsf</url-pattern>
  </filter-mapping>
  
  <!-- JSF --> 
  <context-param>
    <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
    <param-value>client</param-value>
   </context-param> 
     
  <context-param>
  <param-name>org.ajax4jsf.VIEW_HANDLERS</param-name>
  <param-value>com.sun.facelets.FaceletViewHandler</param-value>
  </context-param>
  
  <context-param>
    <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
    <param-value>.xhtml</param-value>
  </context-param>
  <context-param>
    <param-name>facelets.REFRESH_PERIOD</param-name>
    <param-value>2</param-value>
  </context-param>
  <context-param>
    <param-name>facelets.DEVELOPMENT</param-name>
    <param-value>true</param-value>
  </context-param>
  <context-param>
    <param-name>com.sun.faces.validateXml</param-name>
    <param-value>true</param-value>
  </context-param>
  <context-param>
    <param-name>com.sun.faces.verifyObjects</param-name>
    <param-value>true</param-value>
  </context-param>
  <context-param>
    <param-name>org.ajax4jsf.SKIN</param-name>
    <param-value>DEFAULT</param-value>
  </context-param>
  
  <servlet>
      <servlet-name>Faces Servlet</servlet-name>
      <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
      <load-on-startup>1</load-on-startup>
  </servlet>

  <!-- Faces Servlet Mapping -->
  <servlet-mapping>
      <servlet-name>Faces Servlet</servlet-name>
      <url-pattern>*.seam</url-pattern>
  </servlet-mapping>

  <!-- MyFaces -->
  <listener>
      <listener-class>org.apache.myfaces.webapp.StartupServletContextListener</listener-class>
  </listener>    
</web-app>

Only one issue still persists while using Seam with MyFaces. Look at myFaces part of this section.

3.6. Portlet Support

Portlets have support since version Ajax4jsf 1.1.1. Provide your feedback on compatible with Ajax4jsf if you face some problems.

3.7. Sybase EAServer

The load-on-startup for the Faces Servlet had to be set to 0 in web.xml.

Example:

...
      <servlet>
          <servlet-name>Faces Servlet</servlet-name>
          <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
          <load-on-startup>0</load-on-startup>
    </servlet>
...

This is because, EAServer calls servlet init() before the ServletContextInitializer. Not an EAServer bug, this is in Servlet 2.3 spec.

Chapter 4. Getting Started with Ajax4jsf

4.1. Environment

To use Ajax4jsf framework you need JDK 1.4 or higher, any JSF implementation and your favorite Servlet Container. To read more on the Environments, see further chapters.

Ajax4jsf is designed in an easy-to-use way, so that you should do only a few simple steps to get AJAX functionality in your JSF application.

4.2. Downloading Ajax4jsf

The latest release of Ajax4jsf is available for download at:

http://labs.jboss.com/portal/jbossajax4jsf/downloads

in the Ajax4jsf project area under JBoss.

4.3. Installation

Note:

Starting from Ajax4jsf 1.1.1, the oscache library is not required to be in the classpath anymore.

Unzip "ajax4jsf.zip" file to the chosen folder.
Copy "ajax4jsf.jar" and "oscache-2.3.2.jar" files into the "WEB-INF/lib" folder of your application.

Add the following content into the "WEB-INF/web.xml" file of your application:

<filter> 
  <display-name>Ajax4jsf Filter</display-name> 
  <filter-name>ajax4jsf</filter-name> 
  <filter-class>org.ajax4jsf.Filter</filter-class> 
 </filter> 
 <filter-mapping> 
  <filter-name>ajax4jsf</filter-name> 
   <servlet-name>Faces Servlet</servlet-name>
   <dispatcher>REQUEST</dispatcher>
   <dispatcher>FORWARD</dispatcher>
   <dispatcher>INCLUDE</dispatcher>
 </filter-mapping>

Note:

You can copy and paste the above text from the "README.txt" file.

Add the following line for each JSP page of your application where you are going to bring in AJAX functionality.
```
  <%@ taglib uri="https://ajax4jsf.dev.java.net/ajax" prefix="a4j"%>
```
For XHTML pages:
```
<xmlns:a4j="https://ajax4jsf.dev.java.net/ajax">
```

4.4. Simple AJAX Echo Project

In our JSF project you need only one JSP page that has a form with a couple of child tags: <h:inputText> and <h:outputText> .

This simple application let you input some text into the <h:inputText> , send data to the server, and see the server response as a value of <h:outputText> .

4.4.1. JSP Page

Here is the necessary page (echo.jsp):

    <%@ taglib uri="https://ajax4jsf.dev.java.net/ajax" prefix="a4j"%>
    <%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
    <%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
    <html>
      <head>
        <title>repeater </title> 
      </head>
      <body>
        <f:view>
          <h:form>
            <h:inputText size="50" value="#{bean.text}" > 
              <a4j:support event="onkeyup" reRender="rep"/>
            </h:inputText>
            <h:outputText value="#{bean.text}" id="rep"/>
          </h:form>
        </f:view>
      </body>
    </html>

The only line that distinguishes this page from a "regular" JSF one is

<a4j:support event="onkeyup" reRender="rep"/>

The line adds an AJAX support to the parent <h:inputText> tag. This support is bound to "onkeyup" JavaScript event, so that each time when this event is fired on the parent tag, our application sends an AJAX request to the server. It means that the text field pointed to our managed bean property contains up-to-date value of our input.

The value of "reRender" attribute of the <a4j:support> tag defines which part(s) of our page is (are) to be updated. In this case, the only part of the page to update is the <h:outputText> tag because its ID value matches to the value of "reRender" attribute. As you see, it's not difficult to update multiple elements on the page, only list their IDs as the value of "reRender".

4.4.2. Data Bean

In order to build this application, you should create a managed bean:

package demo;
	  
public class Bean {
	private String text;
	public Bean() {
	}
	public String getText() {
		return text;
	}
	public void setText(String text) {
		this.text = text;
	}
}

4.4.3. faces-config.xml

Next, it's necessary to register your bean inside of the faces-config.xml file:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD  JavaServer Faces Config 1.1//EN"
    "http://java.sun.com/dtd/web-facesconfig_1_1.dtd">
    <faces-config>
      <managed-bean>
        <managed-bean-name>bean</managed-bean-name>
        <managed-bean-class>demo.Bean</managed-bean-class>
        <managed-bean-scope>request</managed-bean-scope>
        <managed-property>
          <property-name>text</property-name>
          <value/>
        </managed-property>
      </managed-bean>
    </faces-config>

Note:

Nothing that relates directly to Ajax4jsf is required in the configuration file.

4.4.4. Web.xml

It is also necessary to add jar files (see installation chapter) and modify the "web.xml" file:

    <?xml version="1.0"?>
    <web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee  http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
      
      <display-name>a4jEchoText</display-name>
      <context-param>
        <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
        <param-value>server</param-value>
      </context-param>
      <filter> 
		<display-name>Ajax4jsf Filter</display-name> 
		<filter-name>ajax4jsf</filter-name> 
		<filter-class>org.ajax4jsf.Filter</filter-class> 
	  </filter> 
	  <filter-mapping> 
	    <filter-name>ajax4jsf</filter-name> 
		<servlet-name>Faces Servlet</servlet-name>
		<dispatcher>REQUEST</dispatcher>
		<dispatcher>FORWARD</dispatcher>
		<dispatcher>INCLUDE</dispatcher>
	   </filter-map>
       <listener>
        <listener-class>
          com.sun.faces.config.ConfigureListener
        </listener-class>
      </listener>
      
      <!-- Faces Servlet -->
      <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>
          javax.faces.webapp.FacesServlet
        </servlet-class>
        <load-on-startup>1</load-on-startup>
      </servlet>
      
      <!-- Faces Servlet Mapping -->
      <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>*.jsf</url-pattern>
      </servlet-mapping>
      <login-config>
        <auth-method>BASIC</auth-method>
      </login-config>
    </web-app>

Now your application should work.

4.4.5. Deployment

Finally, you should be able to place this application on your Web server.To start your project, point your browser at http://localhost:8080/a4jEchoText/echo.jsf

4.5. Other Relevant Resources

Introduction to Ajax4Jsf - Sample Application by Shunmuga Raja

Chapter 5. Basic concepts of the Ajax4jsf Framework

5.1. Introduction

The framework is implemented as a component library which adds AJAX capability into existing pages, so you don't need to write any JavaScript code or to replace existing components with new AJAX widgets. Ajax4jsf enables page-wide AJAX support instead of the traditional component-wide support. So, you can define the event on the page that invokes an AJAX request and the areas of the page that should be synchronized with the JSF Component Tree after the AJAX request changes the data on the server according to the events fired on the client.

Next Figure shows how it works:

Figure 5.1. Request Processing flow

Ajax4jsf allows to define (by means of JSF tags) different parts of a JSF page you wish to update with an AJAX request and provide a few options to send AJAX requests to the server. Also JSF page doesn't change from a "regular" JSF page and you don't need to write any JavaScript or XMLHttpRequest objects by hands, everything is done automatically.

5.2. Architecture Overview

Next figure lists several important elements of the Ajax4jsf framework

Figure 5.2. Ajax4jsf component structure

Ajax Filter. To get all benefits of Ajax4jsf, you should register an AJAX Filter in web.xml file of your application.The AJAX Filter recognizes multiple request types. The sequence diagram on Figure 3 shows the difference in processing of a "regular" JSF request and an AJAX request.

In the first case the whole JSF tree will be encoded, in the second one option it depends on the "size" of the AJAX region (you can define AJAX region by using the <a4j:region>). As you can see, in the second case the filter parses the content of an AJAX response before sending it to the client side.

Have a look at the next picture to understand these two ways:

Figure 5.3. Request Processing sequence diagram

In both cases, the information about required static or dynamic resources that your application requests is registered in the ResourseBuilder class.

When a request for a resource comes (Figure 4), the AJAX filter checks the Resource Cache for this resource and if it is there, the resource is sent to the client. Otherwise, the filter searches for the resource among those that are registered by the ResourceBuilder. If the resource is registered, the AJAX filter will send a request to the ResourceBuilder to create (deliver) the resource.

Next Figure shows the ways of resource request processing.

Figure 5.4. Resource request sequence diagram

AJAX Action Components. There are four AJAX Action Components: AjaxCommandButton, AjaxCommandLink, AjaxPoll and AjaxSupport. You can use them to send AJAX requests from the client side.

AJAX Containers. AjaxContainer is an interface that describes an area on your JSF page that should be decoded during an AJAX request. AjaxViewRoot and AjaxRegion are implementations of this interface.

JavaScript Engine. Ajax4jsf JavaScript Engine runs on the client-side. It knows how to update different areas on your JSF page based on the information from the Ajax response. Do not use this JavaScript code directly, as it is available automatically.

5.3. Limitations and Rules

In order to create AJAX4JSF applications properly, keep the following points in mind:

The AJAX framework should not append or delete, but only replace elements on the page. For successful updates, an element with the same ID as in the response must exist on the page. If you'd like to append any code to a page, put in a placeholder for it (any empty element). For the same reason, it's recommended to place messages in the "AjaxOutput" component (as no messages is also a message).
Don't use <f:verbatim> for self-rendered containers, since this component is transient and not saved in the tree.
AJAX requests are made by XMLHttpRequest functions in XML format, but this XML bypasses most validations and the corrections that might be made in a browser. So, create only a strict standards-compliant code for HTML and XHTML, without skipping any required elements or attributes. Any necessary XML corrections are automatically made by the XML filter on the server, but lot's of unexpected effects can be produced by an incorrect HTML code.

5.4. How To...

5.4.1. Send an AJAX request

There are different ways to send AJAX requests from your JSF page. You may use <a4j:commandButton>, <a4j:commandLink>, <a4j:poll> or <a4j:support> tags.

All these tags hide the usual JavaScript activities that are required for an XMHttpRequest object building and an AJAX request sending. Also, they allow you to decide which components of your JSF page are to be re-rendered as a result of the AJAX response (you can list the IDs of these components in the "reRender" attribute).

<a4j:commandButton> and <a4j:commandLink> tags are used to send an AJAX request on "onclick" JavaScript event.

<a4j:poll> tag is used to send an AJAX request periodically using a timer.

The <a4j:support> tag allows you to add AJAX functionality to standard JSF components and send AJAX request onto a chosen JavaScript event: "onkeyup", "onmouseover", etc.

Most important attributes of components that provide AJAX request calling features are:

"reRender" attribute as it was mentioned before specifies components to be reRendered after AJAX response. The attribute can be specified using EL expression and formed dynamicaly on the server side (see FAQ chapter).
"RequestDelay" attribute is used for a requests frequency regulation.

<h:inputText size="50" value="#{bean.text}">
        <a4j:support event="onkeyup" RequestDelay="3"/>
</h:inputText>

So every next request from the frequent keyboard events will be delayed on 3 ms to reduce the number of requests.

"EventsQueue" is a queue that stores the next request.
"LimitToList" attribute is used to regulate updatable regions. Setting it to true limits the updatable areas only to ones specified in a reRender list, in other case all Output Panels of the region are updated.
"ajaxSingle" attributes specify regions to be sent with a request, if "false" it is a full region, in other case it's is only a control caused event.

5.4.2. Decide What to Send

You may describe a region on the page you wish to send to the server, in this way you can control what part of the JSF View is decoded on the server side when you send an AJAX request.

The easiest way to describe an AJAX region on your JSF page is to do nothing, because the content between the <f:view> and </f:view> tags is considered the default AJAX region.

You may define multiple AJAX regions on the JSF page (they can even be nested) by using the <a4j:region> tag.

If you wish to render the content of an AJAX response outside of the active region then the value of the "renderRegionOnly" attribute should be set to "false". Otherwise, your AJAX updates are limited to elements of the active region.

5.4.3. Decide What to Change

Using IDs in the "reRender" attribute to define "AJAX zones" for update works fine in many cases.

But you can not use this approach if your page contains, e.g. a <f:verbatim> tag and you wish to update its content on an AJAX response.

The problem with the <f:verbatim/> tag as described above is related to the value of the transientFlag of JSF components. If the value of this flag is true, the component must not participate in state saving or restoring of process.

In order to provide a solution to this kind of problems, Ajax4jsf uses the concept of an output panel that is defined by the <a4j:outputPanel> tag. If you put a <f:verbatim> tag inside of the output panel, then the content of the <f:verbatim/> tag and content of other panel's child tags could be updated on AJAX response. There are two ways to control this:

By setting the "ajaxRendered" attribute value to "true".
By setting the "reRender" attribute value of an Action Component to the output panel ID.

5.5. Request Errors and Session Expiration Handling

Ajax4jsf allows to redefine standard handlers responsible for processing of different exceptional situations. It helps to define own JavaScript, which is executed when this situations occur.

5.5.1. Request Errors Handling

To execute your own code on the client in case of an error during AJAX request, it's necessary to redefine the standard "A4J.AJAX.onError " method:

A4J.AJAX.onError = function(req,status,message) { 
          // Custom Developer Code 
};

The function defined this way accepts as parameters:

req - a params string of a request that calls an error
status - the number of an error returned by the server
message - a default message for the given error

Thus, it's possible to create your own handler that is called on timeouts, inner server errors, and etc.

5.5.2. Session Expired Handling

Beginning with Ajax4jsf version 1.0.5 it's possible to redefine also the "onExpired" framework method that is called on the "Session Expiration" event.

Example:

A4J.AJAX.onExpired = function(loc,expiredMsg){ 
          // Custom Developer Code 
};

Here the function receives in params:

loc - URL of the current page (on demand can be updated)
expiredMsg - a default message on "Session Expiration" event.

Note:

Until the version 1.0.5 the method can't be redefined on "Session Expiration", a confirmation dialog with a request for view reloading was always called.

5.6. FAQ

5.6.1. What should I change on the server side?

As it was mentioned before, the list of zones to be reRendered can be specified as EL expression. But there is a question that must be specified more exactly.

The list of Ids is formed during beforePhase of RENDER_RESPONSE. Therefore, in this case one can point reRender to the Set type Bean's property and fill the Set during a tracking request.

It's the way to form a list of updatable areas dynamically.

5.6.2. How to check sending request conditions? Custom JavaScript before request "OnSubmit" attribute.

To check on the client some terms of request sending, the "onSubmit " attribute is added to all components, which may cause the request.

Example:

<h:inputText id="i" value="#{beanText.kennung}">
            <a4j:support event="onfocus" onsubmit="doSomething();" reRender="panelToReRender"/>
</h:inputText>

So in this case "doSomething()" function is executed before the AJAX request.

Besides, if this function returns "false", AJAX request isn't fired.

Note:

Behavior of our "onsubmit" slightly differs from the standard one. Do not return "true" if you want to fire the request - because <xxx><a4j:support event="onclick" onsubmit="return true;"> is transformed into <xxx onclick="return true; A4J.Submit(.... );" > and the request isn't fired also in this case (but the standard event processing fired). You must only return "false" if your conditions weren't completed or perform some actions (if needed) without any returns in case you need to fire it.

5.6.3. What is differences of "onCompelete" attribute after release 1.0?

To avoid differences with other JavaScript attributes, a function placement in a JavaScript call is changed, instead of simple inserting of attribute content (..oncomplete :anotherFunction(this)..), it places (oncomplete: function(){anotherFunction(this);}..) in anonymous function, to allow put "chain" of statements in attribute.

Since, "this" keyword will point to a parameters map instead of a control element as it was before. You may use document.findElementById() to get references to this object after a request is processed as when a page is updated in AJAX you will have reference to a control, removed from a DOM tree.

Or, if you are sure that your element is not updated, you can add "onsubmit" in <a4j:support> (or onclick in <a4j:commandLink/Button> ) to place reference to known variable ( <a4j:commandLink onclick="var myControl=this;" oncomplete="anotherFunction(myControl)"/> ).

New:

The onComplete syntax now is:

	<someAjaxActionComponent ...oncomplete="myFunc(req,event,data)".../>

where the event is a variable where the JS event copy that fires the request is placed into. One may use it to get the element instead of this. and data is a variable that contains deserialized value from the data attribute.

5.6.4. Is it possible to use InvokeOnComponent with JSF 1.2?

Ajax4jsf currently does not use invokeOnComponent because of the 2 reasons:

Compatibility with JSF 1.1 and MyFaces applications is kept, due to a big amount of code used in corporate applications.
InvokeOnComponent works with already known clientId, and works fine for communication between widget and backed component, or updates content of already rendered component. But there are some troubles to use this method for more complex use-cases implemented in Ajax4jsf, as there is a choice for updatable components in application logic, where it's necessary to navigate in a components tree by the native id, with findComponent() methods.

Thus, for example, only entire dataTable can be updated in response (but all AJAX action components inside table work properly).

5.6.5. How to avoid generating exception for "keepAlive" component?

To avoid exception, don't forget that the component stores beans in serialized view, but your bean should implement java.io.Serializable.

5.6.6. Why does filter usage damage an application layout?

Ajax4jsf uses filters for correction of xhtml code received on an AJAX response, because when a response is recieved from the server, Ajax4jsf makes direct changes in DOM tree and browser doesn't make any corrections in generated xhtml. There are two ways for setting filters that could be used in an Ajax4jsf-based application.

The first one:

Example:

<context-param filter>
  <display-name>Ajax4jsf Filter</display-name>
  <filter-name>ajax4jsf</filter-name>
  <filter-class>org.ajax4jsf.Filter</filter-class>
</filter>

This filter is based on Tidy Filter usage and recommended for applications with complicated or non-standard markup, as all the necessary xhtml code corrections are made by the filter when a response comes from the server.

Anyway, some obvious errors could damage a layout, if it happens, make sure that the markup corresponds to the xhtml-strict specification.

The second one:

Example:

<filter>
  <display-name>org.ajax4jsf.FastFilter</display-name>
  <filter-name>ajax4jsf</filter-name>
  <filter-class>org.ajax4jsf.FastFilter</filter-class>
</filter>

This filter is based on the Nekko pacer. In this case an output xhtml code isn't strictly verified and it also could cause lot's of errors and corrupt a layout as a result. Though if you sure that your application markup is really strict for this filter, the filter considerably accelerates all AJAX requests processing.

Extra information.

forceParcer parameters setting for filters:

Example:

<filter>
...
<init-param>
<param-name>forceparser</param-name>
<param-value>false</param-value>
</init-param>
...
</filter>

The "false" setting for initialization parameter switches off application of filters for non-AJAX requests, if "true" is chosen, the filter checks all requests.

Changes for Ajax4jsf 1.1.0

forceparser parameter default value is false from this version.

5.6.7. Why form isn't submitted or setter isn't called after AJAX request?

This situation could happen because of conversion/validation errors on form submission. In order to verify this, it's necessary to place this updating via an AJAX error message inside a form:

Example:

<a4j:outputPanel ajaxRendered="true">
   <h:messages/>
</a4j:outpurPanel>

5.6.8. How to create "a4j delayed render zone"?

The <a4j:support> component has a "requestDelay" attribute where you can define the delay.

More information about this problem could be found on the Ajax4Jsf Users Forum.

5.6.9. How to stop "a4j:poll"?

More information about this problem could be found on the Ajax4Jsf Users Forum.

5.6.10. How to use IgnoreDupResponses and requestDelay?

The "IgnoreDupResponses" attribute appeared from 1.0.4 RC1 version and is used on the client for response ignoring after an AJAX request if a newer request has been already sent.

The additional information could be found here.

"RequestDelay" attribute also defines the client behavior. It sets the time delay, after which another request could be sent, all other requests are taken away from a queue except the last one.

5.6.11. How to refresh an image using <a4j:support> component?

More information about this problem could be found on the Ajax4Jsf Users Forum.

5.6.12. How to use "EventQueue" attribute?

The "EventQueue" attribute defines the query name where the requests are saved before their sending to the server. The queue is created for redundant requests deleting during frequent events, which call several requests forming one after another. The queue cuts redundant requests and send only the last one. The queue is created in any case and named on default, the attribute usage only re-defines this name.

5.6.13. Is <a4j:page> component required or not?

<4j:page> is a component used for solving of incompatibility problems in early Ajax4jsf and MyFaces versions. The component encodes the full html page structure.

More information about this problem could be found on the Ajax4Jsf Users Forum.

5.6.14. Can I have several <a4j:status> components on one page?

Yes, you can. More information about this problem could be found on the JBoss Ajax4jsf Online Demos.

5.6.15. Can I use <a4j:region> within <a4j:repeat>?

<a4j:region> can't work inside iteration components like <h:dataTable> and <a4j:repeat>.

The details could be found here.

5.6.16. How to reRender only particular row(s) of dataTable?

If you use dataTable then you may use ajaxKeys attribute to bind the rowKeys to be reRendered there. After you need to point reRender on the whole table and only specified rows will be reRedered. Also the example of usage of <a4j:repeat> component are available here.

5.6.17. How to reRender single dataTable column?

More information about this problem could be found on the Ajax4Jsf Users Forum.

5.6.18. Why does reRendering fail? Hide/Show components using rendered.

During "show/hide" functionality implementation the main error happens because of the "reRender" attribute of some AJAX Action Component is set on a component that depends on rendered properties, i.e. a component that is to be hidden/rendered is tried to be updated. The problem is that if rendered="false" in this moment, the component isn't in the DOM tree and can't be updated because of the general limitations described in the Ajax Processing chapter.

The correct variant of functionality implantation:

With the rendered attribute wrap the component that is to be hidden or rendered on AJAX in a wrapper component (e.g. a4j:outputPanel)
Set reRender of an AJAX Action component on this wrapper component instead of the component itself.

Example:

...
<a4j:outputPanel id="panel"> 
	<h:panelGroup rendered="#{bean.rendered}">
		<!--Some nested content to be hidden/shown depending on bean.rendered -->
	</h:panelGroup>
</a4j:outputPanel>
...
<a4j:commandButton action=".." value=".." reRender="panel"/>
...

In this case the wrapper component always presents in the DOM tree and its inner content could be updated dynamically on AJAX.

5.6.19. Why does JavaScript call don't work in <a4j:include>?

More information about this problem could be found on the Ajax4Jsf Users Forum.

5.6.20. What does ResourceNotRegistered Exception mean?

Ajax4jsf registers its resources (scripts, images) after an application is accessed and then accesses it via a generated URL. During an application development when a developer constantly updates it on the server, it could happen that Ajax4jsf re-registers its resources after every server restart and a browser tries to access them via cashed URL.

The problem is solved with browser cash update (e.g. CTRL+F5).

5.7. Other Relevant Resources

Introduction to Ajax4Jsf by Shunmuga Raja

Chapter 6. Ajax4jsf components

6.1. <a4j:ajaxListener>

The <a4j:ajaxListener> component is the same one as "ActionListener" or "ValueChangeListener", but for an AJAX container.

Table 6.1. a4j:ajaxListener attributes

Attribute Name	Description
type	Fully qualified Java class name of an AjaxListener to be created and registered.

    <a4j:region selfRendered="true" ajaxListener="#{bean.processAjax}" id="Region">

    </a4j:region>

Every time when AJAX request triggered from "region" method "processAjax" of "bean" will be called.

6.2. <a4j:keepAlive>

The <a4j:keepAlive> component allows to keep a state of each bean between requests.

Some additional information about usage of components can be found here.

Table 6.2. a4j:keepAlive attributes

Attribute Name	Description
beanName	name of bean for EL-expressions.
ajaxOnly	if true, bean value restored in ajax requests only.

6.3. <a4j:actionparam>

The <a4j:actionparam> component combines the functionality of both JSF components: <f:param> and <f:actionListener> .

Table 6.3. a4j:actionparam attributes

Attribute Name	Description
noEscape	If set to true, the value will not enclosed within single quotes and there will be no escaping of characters. This allows the use of the value as JavaScript code for calculating value on the client-side. This doesn't work with non-AJAX components.
value	An initial value or a value binding
converter	ID of a converter to be used or a reference to a converter.
assignTo	EL expression for updatable bean property. This property will be updated if the parent command component performs an actionEvent.
binding	The attribute takes a value-binding expression for a component property of a backing bean
name	A name of this parameter
id	Every component may have a unique id that is automatically created if omitted

6.4. <a4j:commandButton>

6.4.1. Description

The <a4j:commandButton> component is very similar to the <h:commandButton> component, the only difference is that an AJAX form submit is generated on a click and it allows dynamic rerendering after a response comes back. It's not necessary to plug any support into the component, as AJAX support is already built in.

Table 6.4. a4j:commandButton attributes

Attribute Name	Description
actionListener	MethodBinding pointing at method accepting an ActionEvent with return type void
title	Advisory title information about markup elements generated for this component
oncomplete	JavaScript code for call after request completed on client side
rendered	If "false", this component is not rendered
reRender	Id['s] (in format of call UIComponent.findComponent()) of components, rendered in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection
focus	id of element to set focus after request completed on client side
onchange	HTML: script expression; the element value was changed
dir	Direction indication for text that does not inherit directionality. Valid values are "LTR" (left-to-right) and "RTL" (right-to-left)
id	Every component may have a unique id that is automatically created if omitted
bypassUpdates	If "true", after process validations phase it skips updates of model beans on a force render response. It can be used for validating components input
styleClass	Corresponds to the HTML class attribute
accesskey	This attribute assigns an access key to an element. An access key is a single character from the document character set. Note: Authors should consider the input method of the expected reader when specifying an accesskey
limitToList	If "true", updates on client side ONLY elements from this 'reRender' property. If "false" (default) updates all rendered by ajax region components
onkeypress	HTML: a script expression; a key is pressed and released
ajaxSingle	if "true", submits ONLY one field/link, instead of all form controls
ondblclick	HTML: a script expression; a pointer button is double-clicked
image	Absolute or relative URL of the image to be displayed for this button. If specified, this "input" element will be of type "image". Otherwise, it will be of the type specified by the "type" property with a label specified by the "value" property.
style	CSS style(s) is/are to be applied when this component is rendered
size	This attribute tells the user agent the initial width of the control. The width is given in pixels except when type attribute has the value "text" or "password". In that case, its value refers to the (integer) number of characters
onblur	HTML: script expression; the element lost the focus
onmouseover	HTML: a script expression; a pointer is moved onto
value	The current value for this component
action	MethodBinding pointing at the application action to be invoked, if this UIComponent is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property
onkeyup	HTML: a script expression; a key is released
timeout	Timeout ( in ms ) for request.
tabindex	This attribute specifies the position of the current element in the tabbing order for the current document. This value must be a number between 0 and 32767. User agents should ignore leading zeros
lang	Code describing the language used in the generated markup for this component
type	submit\|reset\|image\|button This attribute specifies a type of control to create. The default value for this attribute is "submit"
actionExpression	The action method binding expression.
disabled	When set for a form control, this boolean attribute disables the control for user input
onclick	HTML: a script expression; a pointer button is clicked
status	ID (in format of call UIComponent.findComponent()) of Request status component
onmouseout	HTML: a script expression; a pointer is moved away
alt	Alternate textual description of the element rendered by this component.
onkeydown	HTML: a script expression; a key is pressed down
onmousedown	HTML: script expression; a pointer button is pressed down
requestDelay	Delay (in ms.) for send ajax request on JavaScript event. In conjunction with events queue can reduce number of requests on keyboard or mouse move events
eventsQueue	Name of requests queue to avoid send next request before complete other from same event. Can be used to reduce number of requests of frequently events (key press, mouse move etc.)
immediate	True means, that the default ActionListener should be executed immediately (i.e. during Apply Request Values phase of the request processing lifecycle), rather than waiting until the Invoke Application phase
data	Serialized (on default with JSON) data passed on the client by a developer on AJAX request. It's accessible via "data.foo" syntax
onfocus	HTML: script expression; the element got the focus
onmouseup	HTML: script expression; a pointer button is released
ignoreDupResponses	If true, unfinished request will be aborted on new event.
binding	The attribute takes a value-binding expression for a component property of a backing bean
onmousemove	HTML: a script expression; a pointer is moved within

Table 6.5. Component identification parameters

Name	Value
component-type	org.ajax4jsf.ajax.CommandButton
component-family	javax.faces.Command
component-class	org.ajax4jsf.ajax.html.HtmlCommandButton
renderer-type	org.ajax4jsf.components.AjaxCommandButtonRenderer

6.4.2. Creating on a page

<a4j:commandButton> is used in the same way as <h:commandButton> , but with definition of the area that is updated after the response comes back from the server.

<a4j:commandButton reRender="someData" action="#{bean.action1}" value="Link"/>

This definition of the component provides a link, a click on the link causes an AJAX form submit on the server, "action1" method performance, and rendering of the component with "someData" id after the response comes back from the server.

6.4.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.HtmlAjaxCommandButton;
...
HtmlAjaxCommandButton myButton = new HtmlAjaxCommandButton();
...

6.4.4. Key attributes and ways of usage

The component <a4j:commandButton> placed on a page generates the following HTML code:

<input type="submit" onclick="A4J.AJAX.Submit(...request parameters);return false;" value="sort"/>

Hence, the utility method "A4J.AJAX.Submit" is called on a click, the method performs AJAX request as the <a4j:support> component

Note:

AJAX support is built in and it's not necessary to add nested <a4j:support> to the component.

Common JSF navigation could be performed after an AJAX submit and partial rendering, but Navigation Case must be defined as <redirect/> in order to avoid problems with some browsers.

As any Ajax4jsf component sending AJAX requests and processing server responses <a4j:commandButton> has all attributes described above (see <a4j:support> chapter) that provide the required behavior of requests sending (delay, limitation of submit area and rendering, and etc.)

6.5. <a4j:commandLink>

6.5.1. Description

The <a4j:commandLink> component is very similar to the <h:commandLink> component, the only difference is that an AJAX form submit is generated on a click and it allows dynamic rerendering after a response comes back. It's not necessary to plug any support into the component, as AJAX support is already built in.

Table 6.6. a4j:commandLink attributes

Attribute Name	Description
focus	id of element to set focus after request completed on client side
dir	Direction indication for text that does not inherit directionality. Valid values are "LTR" (left-to-right) and "RTL" (right-to-left)
id	Every component may have a unique id that is automatically created if omitted
rev	A reverse link from the anchor specified by this hyperlink to the current document. The value of this attribute is a space-separated list of link types
bypassUpdates	If "true", after process validations phase it skips updates of model beans on a force render response. It can be used for validating components input
limitToList	If "true", updates on client side ONLY elements from this 'reRender' property. If "false" (default) updates all rendered by ajax region components
style	CSS style(s) is/are to be applied when this component is rendered
onmouseover	HTML: a script expression; a pointer is moved onto
onkeyup	HTML: a script expression; a key is released
tabindex	This attribute specifies the position of the current element in the tabbing order for the current document. This value must be a number between 0 and 32767. User agents should ignore leading zeros
timeout	Timeout ( in ms ) for request.
lang	Code describing the language used in the generated markup for this component
actionExpression	The action method binding expression.
onmouseout	HTML: a script expression; a pointer is moved away
rel	The relationship from the current document to the anchor specified by this hyperlink. The value of this attribute is a space-separated list of link types
onmouseup	HTML: script expression; a pointer button is released
binding	The attribute takes a value-binding expression for a component property of a backing bean
onmousemove	HTML: a script expression; a pointer is moved within
coords	This attribute specifies the position and shape on the screen. The number and order of values depends on the shape being defined. Possible combinations: * rect: left-x, top-y, right-x, bottom-y. * circle: center-x, center-y, radius. Note. When the radius value is percentage value, user agents should calculate the final radius value based on the associated object's width and height. The radius should be the smaller value of the two. * poly: x1, y1, x2, y2, ..., xN, yN. The first x and y coordinate pair and the last should be the same to close the polygon. When these coordinate values are not the same, user agents should infer an additional coordinate pair to close the polygon. Coordinates are relative to the top, left corner of the object. All values are lengths. All values are separated by commas
actionListener	MethodBinding pointing at method accepting an ActionEvent with return type void
title	Advisory title information about markup elements generated for this component
shape	default\|rect\|circle\|poly [CI] This attribute specifies the shape of a region. Possible values: * default: Specifies the entire region. * rect: Define a rectangular region. * circle: Define a circular region. * poly: Define a polygonal region.
oncomplete	JavaScript code for call after request completed on client side
target	This attribute specifies the name of a frame where a document is to be opened. By assigning a name to a frame via the name attribute, authors can refer to it as the "target" of links defined by other elements
charset	The character encoding of a resource designated by this hyperlink
rendered	If "false", this component is not rendered
reRender	Id['s] (in format of call UIComponent.findComponent()) of components, rendered in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection
styleClass	Corresponds to the HTML class attribute
accesskey	This attribute assigns an access key to an element. An access key is a single character from the document character set. Note: Authors should consider the input method of the expected reader when specifying an accesskey
onkeypress	HTML: a script expression; a key is pressed and released
ondblclick	HTML: a script expression; a pointer button is double-clicked
ajaxSingle	if "true", submits ONLY one field/link, instead of all form controls
onblur	JavaScript code. The onblur event occurs when an element loses focus either by the pointing device or by tabbing navigation. It may be used with the same elements as onfocus
action	MethodBinding pointing at the application action to be invoked, if this UIComponent is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property
value	The current value for this component
hreflang	Base language of a resource specified with the href attribute; hreflang may only be used with href
type	The content type of the resource designated by this hyperlink
onclick	HTML: a script expression; a pointer button is clicked
status	ID (in format of call UIComponent.findComponent()) of Request status component
onkeydown	HTML: a script expression; a key is pressed down
onmousedown	HTML: script expression; a pointer button is pressed down
requestDelay	Delay (in ms.) for send ajax request on JavaScript event. In conjunction with events queue can reduce number of requests on keyboard or mouse move events
eventsQueue	Name of requests queue to avoid send next request before complete other from same event. Can be used to reduce number of requests of frequently events (key press, mouse move etc.)
immediate	True means, that the default ActionListener should be executed immediately (i.e. during Apply Request Values phase of the request processing lifecycle), rather than waiting until the Invoke Application phase
data	Serialized (on default with JSON) data passed on the client by a developer on AJAX request. It's accessible via "data.foo" syntax
onfocus	JavaScript code. The onfocus event occurs when an element gets focus
ignoreDupResponses	If true, unfinished request will be aborted on new event.

Table 6.7. Component identification parameters

Name	Value
component-type	org.ajax4jsf.ajax.CommandLink
component-family	javax.faces.Command
component-class	org.ajax4jsf.ajax.html.HtmlCommandLink
renderer-type	org.ajax4jsf.components.AjaxCommandLinkRenderer

6.5.2. Creating on a page

<a4j:commandLink> is used in the same way as <h:commandLink> , but with definition of the area that is updated after the response comes back from the server.

<a4j:commandLink reRender="someData" action="#{bean.action1}" value="Link"/>

This definition of the component provides a link, and a click on the link causes an AJAX form submit on the server, "action1" method performance, and rendering of the component with "someData" id after the response comes back from the server.

6.5.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.HtmlAjaxCommandLink;
...
HtmlAjaxCommandLink myLink = new HtmlAjaxCommandLink();
...

6.5.4. Key attributes and ways of usage

The component <a4j:commandLink> placed on a page generates the following HTML code:

<a href="#" onclick="A4J.AJAX.Submit(?"request parameters");
	  return 
	  <a href="#" onclick="A4J.AJAX.Submit(?"request parameters");
	  return false;">
	  <span style="color: black;">Link Value</span>
	  </a>

Hence, the utility method "A4J.AJAX.Submit" is called on a click, the method performs AJAX request as the <a4j:support> component

Note:

AJAX support is built in and it's not necessary to add nested <a4j:support> to the component.

Common JSF navigation could be performed after AJAX submit and partial rendering, but Navigation Case must be defined as <redirect/> in order to avoid problems with some browsers.

As any Ajax4jsf component sending AJAX requests and processing server responses <a4j:commandLink> has all attributes described above (see <a4j:support> chapter) that provide the required behavior of requests sending (delay, limitation of submit area and rendering, etc.)

6.6. <a4j:form>

6.6.1. Description

The <a4j:form> component is very similar to the same component from the JSF HTML library, the only slight difference is in generation of links inside and possibility of AJAX by-default submission.

Table 6.8. a4j:form attributes

Attribute Name	Description
oncomplete	JavaScript code for call after request completed on client side
target	This attribute specifies the name of a frame where a document is to be opened. By assigning a name to a frame via the name attribute, authors can refer to it as the "target" of links defined by other elements
rendered	If "false", this component is not rendered
reRender	Id['s] (in format of call UIComponent.findComponent()) of components, rendered in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection
focus	id of element to set focus after request completed on client side
id	Every component may have a unique id that is automatically created if omitted
prependId	The flag indicating whether or not this form should prepend its id to its descendent id during the clientId generation process. If this flag is not set, the default value is true.
bypassUpdates	If "true", after process validations phase it skips updates of model beans on a force render response. It can be used for validating components input
limitToList	If "true", updates on client side ONLY elements from this 'reRender' property. If "false" (default) updates all rendered by ajax region components
ajaxSingle	if "true", submits ONLY one field/link, instead of all form controls
onreset	The onreset event occurs when a form is reset. It only applies to the FORM element
onsubmit	The onsubmit event occurs when a form is submitted. It only applies to the FORM element
accept	This attribute specifies a comma-separated list of content types that a server processing this form will handle correctly. User agents may use this information to filter out non-conforming files when prompting a user to select files to be sent to the server (cf. the INPUT element when type="file")
timeout	Timeout ( in ms ) for request.
enctype	This attribute specifies the content type used to submit the form to the server (when the value of method is "post"). The default value for this attribute is "application/x-www-form-urlencoded". The value "multipart/form-data" should be used in combination with the INPUT element, type="file"
status	ID (in format of call UIComponent.findComponent()) of Request status component
ajaxSubmit	If true, it becomes possible to set AJAX submission way for any components inside .
requestDelay	Delay (in ms.) for send ajax request on JavaScript event. In conjunction with events queue can reduce number of requests on keyboard or mouse move events
eventsQueue	Name of requests queue to avoid send next request before complete other from same event. Can be used to reduce number of requests of frequently events (key press, mouse move etc.)
data	Serialized (on default with JSON) data passed on the client by a developer on AJAX request. It's accessible via "data.foo" syntax
acceptCharset	This attribute specifies the list of character encodings for input data that is accepted by the server processing this form. The value is a space- and/or comma-delimited list of charset values. The client must interpret this list as an exclusive-or list, i.e., the server is able to accept any single character encoding per entity received. The default value for this attribute is the reserved string "UNKNOWN". User agents may interpret this value as the character encoding that was used to transmit the document containing this FORM element
binding	The attribute takes a value-binding expression for a component property of a backing bean
ignoreDupResponses	If true, unfinished request will be aborted on new event.

Table 6.9. Component identification parameters

Name	Value
component-type	org.ajax4jsf.ajax.Form
component-family	javax.faces.Form
component-class	org.ajax4jsf.ajax.html.AjaxForm
renderer-type	org.ajax4jsf.FormRenderer

6.6.2. Creating on a page

Component definition on a page is similar to definition of the original component from JSF HTML library.

<a4j:form>
	<!--...Some content to be submitted.-->
</a4j:form>

6.6.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.AjaxForm;
...
AjaxForm myForm = new AjaxForm();
...

6.6.4. Key attributes and ways of usage

The difference with the original component is that all hidden fields required for command links are always rendered and it doesn't depend on links rendering on the initial page. It solves the problem with invalid links that weren't rendered on a page immediately, but after some AJAX request.

Beginning with release 1.0.5 additional attributes that make this form variant universal have appeared. With a new attribute definition as ajax= "true" , it becomes possible to set AJAX submission way for any components inside, i.e. not a page URL is used as an "action" attribute, but the javascript:A4J.AJAX.Submit(...) call. In this case, rendering is defined as reRender=list of Ids for the form element itself.

Example

<a4j:form id="helloForm" ajaxSubmit="true" reRender="table">
	...
	<t:dataTable id="table"... >
		...
	</t:dataTable>
	...
	<t:dataScroller for="table"... >
		...
	</t:dataScroller>
	...
</a4j:form

This example shows that in order to make <t:dataScroller> submissions to be AJAX ones it's required only to place this <t:dataScroller> into <a4j:form> . In the other case it is necessary to redefine renders for its child links elements that are defined as <h:commandLink> and can't be made AJAX ones with using e.g. <a4j:support> .

6.7. <a4j:htmlCommandLink>

6.7.1. Description

The <a4j:htmlCommandLink> component is very similar to the same component from the JSF HTML library, the only slight difference is in links generation and problem solving that occurs when an original component is used.

Table 6.10. a4j:htmlCommandLink attributes

Attribute Name	Description
actionListener	MethodBinding pointing at method accepting an ActionEvent with return type void
title	Advisory title information about markup elements generated for this component
shape	default\|rect\|circle\|poly [CI] This attribute specifies the shape of a region. Possible values: * default: Specifies the entire region. * rect: Define a rectangular region. * circle: Define a circular region. * poly: Define a polygonal region.
target	This attribute specifies the name of a frame where a document is to be opened. By assigning a name to a frame via the name attribute, authors can refer to it as the "target" of links defined by other elements
rendered	If "false", this component is not rendered
charset	The character encoding of a resource designated by this hyperlink
id	Every component may have a unique id that is automatically created if omitted
dir	Direction indication for text that does not inherit directionality. Valid values are "LTR" (left-to-right) and "RTL" (right-to-left)
rev	A reverse link from the anchor specified by this hyperlink to the current document. The value of this attribute is a space-separated list of link types
styleClass	Corresponds to the HTML class attribute
accesskey	This attribute assigns an access key to an element. An access key is a single character from the document character set. Note: Authors should consider the input method of the expected reader when specifying an accesskey
onkeypress	HTML: a script expression; a key is pressed and released
ondblclick	HTML: a script expression; a pointer button is double-clicked
style	CSS style(s) is/are to be applied when this component is rendered
onmouseover	HTML: a script expression; a pointer is moved onto
onblur	JavaScript code. The onblur event occurs when an element loses focus either by the pointing device or by tabbing navigation. It may be used with the same elements as onfocus
onkeyup	HTML: a script expression; a key is released
value	The current value for this component
action	MethodBinding pointing at the application action to be invoked, if this UIComponent is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property
tabindex	This attribute specifies the position of the current element in the tabbing order for the current document. This value must be a number between 0 and 32767. User agents should ignore leading zeros
hreflang	Base language of a resource specified with the href attribute; hreflang may only be used with href
lang	Code describing the language used in the generated markup for this component
type	The content type of the resource designated by this hyperlink
actionExpression	The action method binding expression.
disabled	When set for a form control, this boolean attribute disables the control for user input.
onclick	HTML: a script expression; a pointer button is clicked
onmouseout	HTML: a script expression; a pointer is moved away
onkeydown	HTML: a script expression; a key is pressed down
onmousedown	HTML: script expression; a pointer button is pressed down
rel	The relationship from the current document to the anchor specified by this hyperlink. The value of this attribute is a space-separated list of link types
immediate	True means, that the default ActionListener should be executed immediately (i.e. during Apply Request Values phase of the request processing lifecycle), rather than waiting until the Invoke Application phase
onfocus	JavaScript code. The onfocus event occurs when an element gets focus
onmouseup	HTML: script expression; a pointer button is released
binding	The attribute takes a value-binding expression for a component property of a backing bean
onmousemove	HTML: a script expression; a pointer is moved within
coords	This attribute specifies the position and shape on the screen. The number and order of values depends on the shape being defined. Possible combinations: * rect: left-x, top-y, right-x, bottom-y. * circle: center-x, center-y, radius. Note. When the radius value is percentage value, user agents should calculate the final radius value based on the associated object's width and height. The radius should be the smaller value of the two. * poly: x1, y1, x2, y2, ..., xN, yN. The first x and y coordinate pair and the last should be the same to close the polygon. When these coordinate values are not the same, user agents should infer an additional coordinate pair to close the polygon. Coordinates are relative to the top, left corner of the object. All values are lengths. All values are separated by commas

Table 6.11. Component identification parameters

Name	Value
component-type	javax.faces.HtmlCommandLink
component-family	javax.faces.Command
component-class	javax.faces.component.html.HtmlCommandLink
renderer-type	org.ajax4jsf.HtmlCommandLinkRenderer

6.7.2. Creating on a page

Component definition on a page is the same as for the original component from the JSF HTML library.

Example:

<a4j:htmlCommandLink value="value" action="action"/>

6.7.3. Dynamical creation of a component from Java code

Example:

import javax.faces.component.html.HtmlCommandLink;
...
HtmlCommandLink myForm = new HtmlCommandLink();
...

6.7.4. Key attributes and ways of usage

The difference with the original component is that all hidden fields required for command links with the child <f:param> elements are always rendered and it doesn't depend on links rendering on the initial page. It solves the problem with invalid links that weren't rendered on a page immediately, but after some AJAX request.

Example:

<a4j:form>
	...
	<a4j:htmlComandLink action="action" value="link" rendered="#{bean.rendered}">
		<f:param ...>
	<a4j:htmlComandLink>
	...
</a4j:form>

In this example <a4j:htmlCommandLink> works as standard <h:commandLink> , but here hidden fields required for correct functionality are rendered before the first downloading of a page, though it doesn't happen if its attribute isn't set to "false".

6.8. <a4j:jsFunction>

6.8.1. Description

The <a4j:jsFunction> component allows to invoke the server side data and return it in a JSON format to use in a client JavaScript calls.

Table 6.12. a4j:jsFunction attributes

Attribute Name	Description
actionListener	MethodBinding pointing at method accepting an ActionEvent with return type void
action	MethodBinding pointing at the application action to be invoked, if this UIComponent is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property
timeout	Response waiting time on a particular request. If a response is not received during this time, the request is aborted
actionExpression	The action method binding expression.
oncomplete	JavaScript code for call after request completed on client side
rendered	If "false", this component is not rendered
status	ID (in format of call UIComponent.findComponent()) of Request status component
reRender	Id['s] (in format of call UIComponent.findComponent()) of components, rendered in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection
focus	id of element to set focus after request completed on client side
id	Every component may have a unique id that is automatically created if omitted
requestDelay	Delay (in ms.) for send ajax request on JavaScript event. In conjunction with events queue can reduce number of requests on keyboard or mouse move events
eventsQueue	Name of requests queue to avoid send next request before complete other from same event. Can be used to reduce number of requests of frequently events (key press, mouse move etc.)
bypassUpdates	If "true", after process validations phase it skips updates of model beans on a force render response. It can be used for validating components input
immediate	True means, that the default ActionListener should be executed immediately (i.e. during Apply Request Values phase of the request processing lifecycle), rather than waiting until the Invoke Application phase
limitToList	If "true", updates on client side ONLY elements from this 'reRender' property. If "false" (default) updates all rendered by ajax region components
data	Serialized (on default with JSON) data passed on the client by a developer on AJAX request. It's accessible via "data.foo" syntax
ajaxSingle	if "true", submits ONLY one field/link, instead of all form controls
ignoreDupResponses	If "true", unfinished request will be aborted on new event
binding	The attribute takes a value-binding expression for a component property of a backing bean
name	Name of generated JavaScript function definition

Table 6.13. Component identification parameters

Name	Value
component-type	org.ajax4jsf.ajax.Function
component-family	org.ajax4jsf.components.AjaxFunction
component-class	org.ajax4jsf.ajax.html.HtmlAjaxFunction
renderer-type	org.ajax4jsf.components.AjaxFunctionRenderer

6.8.2. Creating on a page

Simple component definition example:

Example:

...
<head>
	<script>
		<!--There is some script named "myScript" that uses parameters which will be taken from server-->
	</script>
</head>
<body>
...
<a4j:jsFunction data="#{bean.someProperty}" name="callScript" oncomplete="myScript(data.subProperty1, data.subProperty2)"/>
...

The script "myScript" will be called after bean.someProperty data will be returned from server(e.g. It'll be object with two subproperties).

6.8.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.HtmlAjaxFunction;
...
HtmlAjaxFunction myFunction = new HtmlAjaxFunction();
...

6.8.4. Key attributes and ways of usage

As the component uses Ajax request to get data from server - it has all common Ajax Action attributes. So, action and actionListener can be invoked, and reRendering some parts of the page fired after calling function.

When using the <a4j:jsFunction> it's possible to initiate the AJAX request from the JavaScript and perform partial update of a page and/or invoke the JavaScript function with data returned by AJAX response.

...
<body onload="callScript()">
    ...
    <h:form>
    ...
    <a4j:jsFunction name="callScript" data="#{bean.someProperty1 }
                    "reRender="someComponent" oncomplete="myScript(data.subProperty1, data.subProperty2)">
        <a4j:actionparam name="param_name" assignTo="#{bean.someProperty2}">
        </a4j:actionparam>
    </a4j:jsFunction>
    ...
    </h:form>
    ...
</body>
...

The <a4j:jsFunction> allows to use <a4j:actionparam> or pure <f:param> for passing any number of parameters of the JavaScript function into AJAX request. <a4j:jsFunction> is similar to <a4j:commandButton> , but it could be activated from the JavaScript code. It allows to invoke some server side functionality and use the returned data in the JavaScript function invoked from "oncomplete" attribute. So it's possible to use <a4j:jsFunction> instead of <a4j:commandButton> . You can put it anywhere, just don't forget to use <h:form> … </h:form> around it.

6.8.5. Relevant resources links

To see how <a4j:jsFunction> works on practice, look at a4j-jsFunction example from here.

6.9. <a4j:include>

6.9.1. Description

The <a4j:include> component is used for page areas update after an AJAX request according to the faces-config Navigation Rules and for implementation of wizard-like parts work in AJAX mode.

Table 6.14. a4j:include attributes

Attribute Name	Description
layout	HTML layout for generated markup. Possible values: "block" for generating an HTML <div> element, "inline" for generating an HTML <span> element, and "none" for generating no HTML element. There is a minor exception for the "none" case where a child element has the property "rendered" set to "false". In this case, we create an empty <span> element with same ID as the child element to use as a placeholder for later processing.
lang	Code describing the language used in the generated markup for this component
title	Advisory title information about markup elements generated for this component
ajaxRendered	Defines, whether the content of this component must be (or not) included in AJAX response created by parent AJAX Container, even if it is not forced by reRender list of ajax action. Ignored if component marked to output by Ajax action. default false
rendered	If "false", this component is not rendered
id	Every component may have a unique id that is automatically created if omitted
dir	Direction indication for text that does not inherit directionality. Valid values are "LTR" (left-to-right) and "RTL" (right-to-left)
styleClass	Corresponds to the HTML class attribute
keepTransient	Flag for mark all child components to non-transient. If true, all children components will be set to non-transient state and keep in saved components tree. For output in self-renderer region all content ( By default, all content in <f:verbatim> tags and non-jsf elements in facelets, marked as transient - since, self-rendered ajax regions don't plain output for ajax processing ).
style	CSS style(s) is/are to be applied when this component is rendered
binding	The attribute takes a value-binding expression for a component property of a backing bean
viewId	viewId for included page.

Table 6.15. Component identification parameters

Name	Value
component-type	org.ajax4jsf.ajax.Include
component-family	org.ajax4jsf.ajax.Output
component-class	org.ajax4jsf.ajax.html.Include
renderer-type	org.ajax4jsf.AjaxIncludeRenderer

6.9.2. Creating on a page

To use the component, it's necessary to place the following strings on a page:

Example:

<h:panelGroup id="wizard">
		<a4j:include  viewId="/pages/include/first.xhtml" />
</h:panelGroup>

For navigation inside a page defined in viewId any components responsible for AJAX requests to the server generation are used.

For example, the following component on the page "/pages/include/first.xhtml"

Example:

...
<a4j:commandButton action="next" reRender="wizard"/>
...

And in faces-config it's defined:

Example:

<navigation-rule>
  <from-view-id>/pages/include/first.xhtml</from-view-id>
  <navigation-case>
   <from-outcome>next</from-outcome>
   <to-view-id>/pages/include/second.xhtml</to-view-id>
  </navigation-case>
 </navigation-rule>

In this case after a click on a button defined inside "first.xhtml" view, navigation is performed after an AJAX request (the same as standard JSF one) only inside this view.

6.9.3. Dynamical creation of a component from Java code

<a4j:outputPanel ajaxRendered="true">
	<a4j:include  viewId="/pages/include/first.xhtml"/>
</a4j:outputPanel>

If <a4j:include> is defined this way, any AJAX request returning outcome inside generates navigation with this <a4j:include> .

Ajax Action for navigation implementation inside view must be placed inside <a4j:include> pages. Navigation defined by these pages is applied to the <a4j:include> element current for them.

As in the general case for Ajax Action component, if the <a4j:action> component inside <a4j:include> returns outcome defined as <redirect/>, AJAX submit is performed with navigation of the whole page and not only of the current view.

Some additional information can be found on the Ajax4Jsf Users Forum.

6.10. <a4j:loadBundle>

The <a4j:loadBundle> component is similar to the same component from the JSF Core library. The component loads a resource bundle localized for the Locale of the current view and exposes it (as a Map) in the request attributes of the current request.

Table 6.16. a4j:loadBundle attributes

Attribute Name	Description
var	Name of a request scope attribute under which the resource bundle will be exposed as a Map.
basename	Base name of the resource bundle to be loaded.
rendered	If "false", this component is not rendered
binding	The attribute takes a value-binding expression for a component property of a backing bean
id	Every component may have a unique id that is automatically created if omitted

6.11. <a4j:loadScript>

6.11.1. Description

Inserts script links to the head element. Render the value of the component as the value of the "src" attribute, after passing it to the getResourceURL() method of the ViewHandler for this application, and passing the result through the encodeResourceURL() method of the ExternalContext.

Table 6.17. a4j:loadScript attributes

Attribute Name	Description
src	name of JavaScript resource to load.
rendered	If "false", this component is not rendered
binding	The attribute takes a value-binding expression for a component property of a backing bean
id	Every component may have a unique id that is automatically created if omitted

Table 6.18. Component identification parameters

Name	Value
component-type	org.ajax4jsf.LoadScript
component-family	org.ajax4jsf.LoadScript
component-class	org.ajax4jsf.ajax.html.HtmlLoadScript
renderer-type	org.ajax4jsf.LoadScriptRenderer

6.11.2. Creating on a page

Simple Component definition on a page:

Example:

<a4j:loadScript src="scripts/someScript.js"/>

6.11.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.HtmlLoadScript;
...
HtmlLoadScript myScript = new HtmlLoadScript();
...

6.11.4. Key attributes and ways of usage

As it was mentioned before this componment returns its value passing it to the getResourceUR() method of the ViewHandler for this application, and passing the result through the encodeResourceURL() method of the ExternalContext.

It means that the Context will be inserts automatically to the link. And calls like resource:// will be properly handled.

Except this - you may be free to put your script links right from the child page while using facelets templates .

6.12. <a4j:loadStyle>

6.12.1. Description

Inserts stylesheet links to the head element. Render the value of the component as the value of the "src" attribute, after passing it to the getResourceURL() method of the ViewHandler for this application, and passing the result through the encodeResourceURL() method of the ExternalContext.

Table 6.19. a4j:loadStyle attributes

Attribute Name	Description
src	name of JavaScript resource to load.
rendered	If "false", this component is not rendered
binding	The attribute takes a value-binding expression for a component property of a backing bean
id	Every component may have a unique id that is automatically created if omitted

Table 6.20. Component identification parameters

Name	Value
component-type	org.ajax4jsf.LoadStyle
component-family	org.ajax4jsf.LoadStyle
component-class	org.ajax4jsf.ajax.html.HtmlLoadStyle
renderer-type	org.ajax4jsf.LoadStyleRenderer

6.12.2. Creating on a page

Simple Component definition on a page:

Example:

<a4j:loadStyle src="styles/style.css"/>

6.12.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.HtmlLoadStyle;
...
HtmlLoadScript myStyle = new HtmlLoadStyle();
...

6.12.4. Key attributes and ways of usage

As it was mentioned before this componment returns its value passing it to the getResourceUR() method of the ViewHandler for this application, and passing the result via the encodeResourceURL() method of the ExternalContext.

It means that the Context will be inserts automatically to the link. And calls like resource:// will be properly handled.

Except this - you may be free to put your stylesheet links right from the child page while using facelets templates .

6.13. <a4j:log>

6.13.1. Description

The <a4j:log > component generates JavaScript for opening of the window with client-side debug information on an AJAX request.

Table 6.21. a4j:log attributes

Attribute Name	Description
level	log level, possible values : FATAL,ERROR,WARN,INFO,DEBUG,ALL. Component set level 'ALL' by default.
width	width of pop-up.
popup	Render log as popup-window or as div element in page
height	height of pop-up
hotkey	Keyboard key for activate ( in combination with CTRL+SHIFT ) log window.
rendered	If "false", this component is not rendered
binding	The attribute takes a value-binding expression for a component property of a backing bean
name	name of pop-up window
id	Every component may have a unique id that is automatically created if omitted

Table 6.22. Component identification parameters

Name	Value
component-type	org.ajax4jsf.ajax.Log
component-family	org.ajax4jsf.ajax.Log
component-class	org.ajax4jsf.ajax.html.AjaxLog
renderer-type	org.ajax4jsf.LogRenderer

6.13.3. Creating on a page

To use the component, it's necessary to place the following string on a page:

<a4j:log/>

Then, in order to open a log window, press "CTRL+SHIFT+L" on a page with the component.

6.13.4. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.AjaxLog;
...
AjaxLog myLog = new AjaxLog();
...

6.13.5. Key attributes and ways of usage

Usage of the appropriate component attributes could change a representation level of debug information as well as the hot key for a window opening.

The hot key could be changed with the "hotkey" attribute, where it's necessary to define one letter that together with "CTRL+SHIFT" opens a window.

The "level" attribute with several possible values (FATAL, ERROR, WARN, INFO, ALL) could change a logging level.

The log could be generated not only in a new window, but also on the current page in a separate <div> , this is also controlled with the "popup" attribute on the component.

Example:

<a4j:log level="ALL" popup="false" width="400" height="200"/>

The component defined this way is decoded on a page as <div> inside a page, where all the information beginning with informational message is generated.

Note:

<a4j:log> is getting renewed automatically after execution of ajax requests. Don't renew <a4j:log> by using reRender!

6.14. <a4j:mediaOutput>

6.14.1. Description

The <a4j:mediaOutput> component implements one of the basic features specified in the framework. The component is a facility for generating images, video, sounds and other binary resources defined by a user on-the-fly.

Table 6.23. a4j:mediaOutput attributes

Attribute Name	Description
declare	declare but don't instantiate flag
dir	Direction indication for text that does not inherit directionality. Valid values are "LTR" (left-to-right) and "RTL" (right-to-left)
id	Every component may have a unique id that is automatically created if omitted
rev	A reverse link from the anchor specified by this hyperlink to the current document. The value of this attribute is a space-separated list of link types
mimeType	Geterated content mime-type for append to response header ( 'image/jpeg' etc )
style	CSS style(s) is/are to be applied when this component is rendered
onmouseover	HTML: a script expression; a pointer is moved onto
onkeyup	HTML: a script expression; a key is released
tabindex	This attribute specifies the position of the current element in the tabbing order for the current document. This value must be a number between 0 and 32767. User agents should ignore leading zeros
archive	space-separated list of URIs
converter	ID of a converter to be used or a reference to a converter.
lang	Code describing the language used in the generated markup for this component
createContent	Method call expression to send generated resource to OutputStream. It must have two parameter with a type of java.io.OutputStream and java.lang.Object ( deserialized value of data attribute )
onmouseout	HTML: a script expression; a pointer is moved away
element	Name of html element for resource link - may be <a> <img> <object> <applet> <script> or <link>
rel	The relationship from the current document to the anchor specified by this hyperlink. The value of this attribute is a space-separated list of link types
onmouseup	HTML: script expression; a pointer button is released
cacheable	If "true", the resource is cached (on the server and the client sides).
binding	The attribute takes a value-binding expression for a component property of a backing bean
expires	The attribute allows to manage caching and defines the period after which a resource is reloaded.
onmousemove	HTML: a script expression; a pointer is moved within
coords	This attribute specifies the position and shape on the screen. The number and order of values depends on the shape being defined. Possible combinations: * rect: left-x, top-y, right-x, bottom-y. * circle: center-x, center-y, radius. Note. When the radius value is percentage value, user agents should calculate the final radius value based on the associated object's width and height. The radius should be the smaller value of the two. * poly: x1, y1, x2, y2, ..., xN, yN. The first x and y coordinate pair and the last should be the same to close the polygon. When these coordinate values are not the same, user agents should infer an additional coordinate pair to close the polygon. Coordinates are relative to the top, left corner of the object. All values are lengths. All values are separated by commas
title	Advisory title information about markup elements generated for this component
shape	default\|rect\|circle\|poly [CI] This attribute specifies the shape of a region. Possible values: * default: Specifies the entire region. * rect: Define a rectangular region. * circle: Define a circular region. * poly: Define a polygonal region.
target	This attribute specifies the name of a frame where a document is to be opened. By assigning a name to a frame via the name attribute, authors can refer to it as the "target" of links defined by other elements
session	If "true", a session for an object generation is restored.
charset	The character encoding of a resource designated by this hyperlink
rendered	If "false", this component is not rendered
codetype	content type for code
classid	identifies an implementation
styleClass	Corresponds to the HTML class attribute
accesskey	This attribute assigns an access key to an element. An access key is a single character from the document character set. Note: Authors should consider the input method of the expected reader when specifying an accesskey
onkeypress	HTML: a script expression; a key is pressed and released
ondblclick	HTML: a script expression; a pointer button is double-clicked
align	bottom\|middle\|top\|left\|right Deprecated. This attribute specifies the position of an IMG, OBJECT, or APPLET with respect to its context. The following values for align concern the object's position with respect to surrounding text: * bottom: means that the bottom of the object should be vertically aligned with the current baseline. This is the default value. * middle: means that the center of the object should be vertically aligned with the current baseline. * top: means that the top of the object should be vertically aligned with the top of the current text line
vspace	Deprecated. This attribute specifies the amount of white space to be inserted above and below an IMG, APPLET, or OBJECT. The default value is not specified, but is generally a small, non-zero length
lastModified	The attribute allows to manage caching. A browser can send request with the header "If-Modified-Since" for necessity of object reloading. If time of modification is earlier, then the framework doesn't call generation and return code 304.
usemap	use client-side image map
standby	message to show while loading
border	Deprecated. This attribute specifies the width of an IMG or OBJECT border, in pixels. The default value for this attribute depends on the user agent
onblur	JavaScript code. The onblur event occurs when an element loses focus either by the pointing device or by tabbing navigation. It may be used with the same elements as onfocus
value	Data value calculated at render time and stored in URI (also as part of cache Key ), at generation time passed to send method. Can be used for update cache at change of generating conditions, and for creating beans as "Lightweight" pattern components (request scope). IMPORTANT: Since serialized data stored in URI, avoid using big objects.
hreflang	Base language of a resource specified with the href attribute; hreflang may only be used with href
codebase	base URI for classid, data, archive
type	The content type of the resource designated by this hyperlink
uriAttribute	Name of attribute for resource-link attribute ( 'href' for <a>, 'src' for <img> or <script>, etc
onclick	HTML: a script expression; a pointer button is clicked
ismap	use server-side image map
onkeydown	HTML: a script expression; a key is pressed down
onmousedown	HTML: script expression; a pointer button is pressed down
hspace	Deprecated. This attribute specifies the amount of white space to be inserted to the left and right of an IMG, APPLET, or OBJECT. The default value is not specified, but is generally a small, non-zero length
onfocus	JavaScript code. The onfocus event occurs when an element gets focus

Table 6.24. Component identification parameters

Name	Value
component-type	org.ajax4jsf.MediaOutput
component-family	org.ajax4jsf.Resource
component-class	org.ajax4jsf.ajax.html.MediaOutput
renderer-type	org.ajax4jsf.MediaOutputRenderer

6.14.2. Creating on a page

To use the component it's necessary to define it on a page and set Java methods for data keeping and data transmission to output stream.

Component definition on a page for graphical data output

Example:

...
<a4j:mediaOutput element="img" cacheable="false" session="true"
    createContent="#{paintBean.paint}" value="#{paintData}"
    mimeType="image/jpeg"/>
...

Here is the content of paintData that is a bean containing output data

Example:

package demo;

public class PaintData implements Serializable{
        private static final long serialVersionUID = 1L;
        Integer width=100;
        Integer weight=50;
...

The Paint method of the paintBean class is a method transmitting graphical data into output stream.

Example:

public void paint(OutputStream out, Object data) throws IOException{
	<!--...Some code that puts binary data to "out" Stream-->
        }

6.14.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.MediaOutput;
...
MediaOutput myMedia = new MediaOutput ();
...

6.14.4. Key attributes and ways of usage

As it was shown in the example above there are two main components:

createContent specifies a method accepting 2 parameters. The first (of java.io.OutputStream type) defines a stream, where any binary data is output. The second (of java.lang.Object type) contains deserialized object with data specified in the "value" attribute.
Value specifies a bean class keeping data for transmitting into a method that transmits it into a stream.

Note:

A bean class transmitted into value should implement Serializable interface.

Hence, when using the component it's possible to output user data of any type on a page with AJAX requests.

6.15. <a4j:outputPanel>

6.15.1. Description

The component is used for components grouping in the AJAX output area, which offers several additional output opportunities such as inserting of non-present in tree components, saving of transient elements after AJAX request and some others.

Table 6.25. a4j:outputPanel attributes

Attribute Name	Description
onkeyup	HTML: a script expression; a key is released
layout	HTML layout for generated markup. Possible values: "block" for generating an HTML <div> element, "inline" for generating an HTML <span> element, and "none" for generating no HTML element. There is a minor exception for the "none" case where a child element has the property "rendered" set to "false". In this case, we create an empty <span> element with same ID as the child element to use as a placeholder for later processing.
lang	Code describing the language used in the generated markup for this component
title	Advisory title information about markup elements generated for this component
ajaxRendered	Defines, whether the content of this component must be (or not) included in AJAX response created by parent AJAX Container, even if it is not forced by reRender list of ajax action. Ignored if component marked to output by Ajax action. default false
onclick	HTML: a script expression; a pointer button is clicked
rendered	If "false", this component is not rendered
onmouseout	HTML: a script expression; a pointer is moved away
onkeydown	HTML: a script expression; a key is pressed down
onmousedown	HTML: script expression; a pointer button is pressed down
id	Every component may have a unique id that is automatically created if omitted
dir	Direction indication for text that does not inherit directionality. Valid values are "LTR" (left-to-right) and "RTL" (right-to-left)
styleClass	Corresponds to the HTML class attribute
keepTransient	Flag for mark all child components to non-transient. If true, all children components will be set to non-transient state and keep in saved components tree. For output in self-renderer region all content ( By default, all content in <f:verbatim> tags and non-jsf elements in facelets, marked as transient - since, self-rendered ajax regions don't plain output for ajax processing ).
onkeypress	HTML: a script expression; a key is pressed and released
ondblclick	HTML: a script expression; a pointer button is double-clicked
onmouseup	HTML: script expression; a pointer button is released
style	CSS style(s) is/are to be applied when this component is rendered
binding	The attribute takes a value-binding expression for a component property of a backing bean
onmousemove	HTML: a script expression; a pointer is moved within
onmouseover	HTML: a script expression; a pointer is moved onto

Table 6.26. Component identification parameters

Name	Value
component-type	org.ajax4jsf.ajax.OutputPanel
component-family	javax.faces.Panel
component-type	org.ajax4jsf.ajax.OutputPanel
component-class	org.ajax4jsf.ajax.html.HtmlAjaxOutputPanel
renderer-type	org.ajax4jsf.components.AjaxOutputPanelRenderer

6.15.2. Creating on a page

Here is the simplest way for a component creation on a page.

Example:

<a4j:outputPanel>
<!--...Some Content Inside-->
</a4j:outputPanel>

6.15.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.HtmlAjaxOutputPanel;
...
HtmlAjaxOutputPanel  myPanel = new HtmlAjaxOutputPanel();

6.15.4. Key attributes and ways of usage

<a4j:outPanel> allows marking of a page area, which is updated on Ajax response. Anyway, <a4j:outputPanel> usage is optional, as in Ajax4jsf it's possible to indicate any existing component id on a component view in order to define updating areas. To speed up the performance, Ajax4jsf updates only a component tree. <a4j:outputPanel> usage is recommended for wrapping components that aren't rendered during the primary non-ajax response, as the components don't present in a component tree.

Example:

<a4j:support ... reRender="mypanel"/>
...
<a4j:outputPanel id="mypanel">
  <h:panelGrid rendered="#{not empty foo.bar}">
	...
  </h:panelGrid>
</a4j:outputPanel>

In addition to the areas directly indicated in reRender attribute of Ajax components, <a4j:outputPanel> allows to update a part of a page basing on its own flag. The flag is defined by the ajaxRendered attribute. The flag is commonly used when a part of a page must be updated or can be updated on any response.

Example:

<a4j:outputPanel ajaxRendered="true">
  <h:messages/>
</a4j:outputPanel>

On default <a4j:outputPanel> is output as a pair of opening and closing html <span> tag, but with the help of the layout attribute this output way could be changed. There are three variants for this component value:

inline (default)
block
none

If layout="block" is chosen, the component is rendered as a pair of opening and closing <div> tag, to which it’s possible to apply any available style attributes available for block tags.

Layout="none" helps to avoid an unnecessary tag round a context that could or couldn't be rendered according to the defined "rendered" attribute conditions. If an inner context isn’t rendered, <a4j:outputPanel> is rendered as a <span> tag with the id equal to an id of a child component and "display:none" style. If a child component is rendered, <a4j:outputPanel> doesn't present at all in a final code.

Example:

<a4j:support .... reRender="mypanel"/>
...
<a4j:outputPanel layout="none">
  <h:panelGrid id="mypanel" rendered="#{not empty foo.bar}">
	...
  </h:panelGrid>
</a4j:outputPanel>

As you see, the code is very similar to the one shown above, but "reRender " attribute refers directly to the updating panelGrid and not to the framing outputPanel, and it's more semantically correct.

<a4j:outPanel> should be used for non-JSF component part framing, which is to be updated on Ajax response, as Ajax4jsf specifies the list of updating areas as a list of an existing JSF component.

On default non-JSF context isn't saved in a component tree, but is rendered anew every time. To accelerate the processing speed and Ajax response input speed, Ajax4jsf saves non-JSF context in a component tree on default. This option could be canceled by keepTransient attribute that cancels transient flag forced setting for child components. This flag setting keeps the current value set by child components.

Note: In JSF 1.1 implementation and lower, where non-JSF context should be framed with the "f:verbatim" attribute, <a4j:outputPanel> doesn't improve this JSF implementation option in any way, so you still have to use this tag where it's necessary without Ajax4jsf usage.

Ajax4jsf allows setting Ajax responses rendering directly basing on component tree nodes without referring to the JSP (XHTML) page code. It could be defined by selfRendered attribute setting to "true" on <a4j:region> and could help considerably speed up a response output. However, if a transient flag is kept as it is, this rapid processing could cause missing of transient components that present on view and don’t come into a component tree. Hence, for any particular case you could choose a way for you application optimization: speed up processing or redundant memory for keeping tree part earlier defined a transient.

Some additional information about usage of component can be found here.

6.16. <a4j:page>

6.16.1. Description

<a4j:page> is a deprecated component used for solving of incompatibility problems in early Ajax4jsf and MyFaces versions. The component encodes the full html page structure.

Table 6.27. a4j:page attributes

Attribute Name	Description
namespace	Set html element default namespace
selfRendered	if "true", self-render subtree at InvokeApplication ( or Decode, if immediate property set to true ) phase
lang	Code describing the language used in the generated markup for this component
title	Advisory title information about markup elements generated for this component
onunload	JavaScript code to execute on a page unload.
rendered	If "false", this component is not rendered
contentType	Set custom mime content type to response
id	Every component may have a unique id that is automatically created if omitted
dir	Direction indication for text that does not inherit directionality. Valid values are "LTR" (left-to-right) and "RTL" (right-to-left)
styleClass	Corresponds to the HTML class attribute
immediate	Flag indicating that, if this component is activated by ajaxrequest, notifications should be delivered to interested listeners and actions immediately (that is, during Apply Request Values phase) rather than waiting until Invoke Application phase
onload	JavaScript code to execute on a page load.
pageTitle	String for output as a page title.
style	CSS style(s) is/are to be applied when this component is rendered
binding	The attribute takes a value-binding expression for a component property of a backing bean
ajaxListener	MethodBinding representing an action listener method that will be notified when this component is activated by the ajax Request and handle it. The expression must evaluate to a public method that takes an AjaxEvent parameter, with a return type of void
format	Page layout format ( html, xhtml, html-transitional, html-3.2 ) for encoding DOCTYPE, namespace and Content-Type definitions

Table 6.28. Component identification parameters

Name	Value
component-type	org.ajax4jsf.components.Page
component-family	org.ajax4jsf.components.AjaxRegion.
component-class	org.ajax4jsf.components.Page
renderer-type	org.ajax4jsf.components.PageRenderer

6.16.2. Creating on a page

This component should be defined as a child component for <f:view>

<f:view>
 <a4j:page>
  <f:facet name="head">
   <!--...Head Content here-->
  </f:facet>
   <!--...Page Content here-->
 </a4j:page>
</f:view>

This structure is rendered as:

Example:

<HTML>
 <HEAD> 
 <!--...Head Content here-->
 </HEAD> 
<body >
 <!--...Page Content Here-->
</body> 
</HTML>

6.16.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.components.Page;
...
Page myPage = new Page();
...

6.16.4. Key attributes and ways of usage

The component is mostly used to solve the following problem with MyFaces for erlier Ajax4gsf versions: in MyFaces <f:view> doesn't get control over the " RENDER_RESPONSE " phase, thus AJAX can't get control and make a response also. To avoid this problem it was necessary to use <a4j:page> on the page round the AJAX updatable area. In the last versions of both frameworks the problem is successfully fixed and no <a4j:page> usage is required.

The component is rendered as a full HTML page template (it was shown in the example). The " head " section is defined with the help of the corresponding facet with the name="head" and also there is an attribute with the same name for contentType definition.

All other component functionality is the same as of <a4j:region>. Its desctriprion could be found here.

6.17. <a4j:poll>

6.17.1. Description

The <a4j:poll> component allows periodical sending of AJAX requests to the server and is used for a page update according to a specified in milliseconds time interval.

Table 6.29. a4j:poll attributes

Attribute Name	Description
actionListener	MethodBinding pointing at method accepting an ActionEvent with return type void
oncomplete	JavaScript code for call after request completed on client side
rendered	If "false", this component is not rendered
reRender	Id['s] (in format of call UIComponent.findComponent()) of components, rendered in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection
focus	id of element to set focus after request completed on client side
id	Every component may have a unique id that is automatically created if omitted
bypassUpdates	If "true", after process validations phase it skips updates of model beans on a force render response. It can be used for validating components input
limitToList	If "true", updates on client side ONLY elements from this 'reRender' property. If "false" (default) updates all rendered by ajax region components
ajaxSingle	if "true", submits ONLY one field/link, instead of all form controls
onsubmit	JavaScript code for call before submission of ajax event
action	MethodBinding pointing at the application action to be invoked, if this UIComponent is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property
timeout	Timeout (in ms) for request
actionExpression	The action method binding expression.
status	ID (in format of call UIComponent.findComponent()) of Request status component
interval	Interval (in ms) for call poll requests. Default value 1000 (1 sec)
eventsQueue	Name of requests queue to avoid send next request before complete other from same event. Can be used to reduce number of requests of frequently events (key press, mouse move etc.)
immediate	True means, that the default ActionListener should be executed immediately (i.e. during Apply Request Values phase of the request processing lifecycle), rather than waiting until the Invoke Application phase
enabled	Enable/disable polling
data	Serialized (on default with JSON) data passed on the client by a developer on AJAX request. It's accessible via "data.foo" syntax
binding	The attribute takes a value-binding expression for a component property of a backing bean
ignoreDupResponses	If true, unfinished request will be aborted on new event.

Table 6.30. Component identification parameters

Name	Value
component-type	org.ajax4jsf.components.Poll
component-family	org.ajax4jsf.components.AjaxPoll
component-class	org.ajax4jsf.components.AjaxPoll
renderer-type	org.ajax4jsf.components.AjaxPollRenderer

6.17.2. Creating on a page

To use this component it's necessary only to set an update interval.

Example:

<a4j:poll interval="1000" reRender="someDataTable" action="#{bean.action1}"/>

The <a4j:poll> component defined this way every second submits AJAX form onto the server, performs the corresponding action and renders a components with the "someDataTable" id after a response comes back.

6.17.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.AjaxPoll;
...
AjaxPoll myPoll = new AjaxPoll();
...

6.17.4. Key attributes and ways of usage

The component decodes all necessary JavaScript for time count and on the expiry of some interval for calling of a Ajax4jsf utility method for Ajax request sending (A4J.AJAX.Submit (Some request parameters)).

The timer could be stopped or started in any time. The current state is controlled on the component with the "enabled" attribute:

<a4j:poll interval="1000" enabled="#{bean.boolProperty}"/>

As any Ajax4jsf Action component, <a4j:poll> has all described in the <a4j:support> chapter attributes to provide the necessary behavior of request sending (delay, limitation of a submit and render area, requests frequency, and etc.). For detailed information on these attributes see again the <a4j:support> component description.

The aditional information about component usage you can find here:Ajax4Jsf Users Forum.

6.18. <a4j:portlet>

Table 6.31. a4j:portlet attributes

Attribute Name	Description
rendered	If "false", this component is not rendered
binding	The attribute takes a value-binding expression for a component property of a backing bean
id	Every component may have a unique id that is automatically created if omitted

6.19. <a4j:push>

6.19.1. Description

The <a4j:push> periodically perform AJAX request to server, to simulate 'push' data.

Table 6.32. a4j:push attributes

Attribute Name	Description
actionListener	MethodBinding pointing at method accepting an ActionEvent with return type void
oncomplete	JavaScript code for call after request completed on client side
rendered	If "false", this component is not rendered
reRender	Id['s] (in format of call UIComponent.findComponent()) of components, rendered in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection
focus	id of element to set focus after request completed on client side
id	Every component may have a unique id that is automatically created if omitted
bypassUpdates	If "true", after process validations phase it skips updates of model beans on a force render response. It can be used for validating components input
limitToList	If "true", updates on client side ONLY elements from this 'reRender' property. If "false" (default) updates all rendered by ajax region components
ajaxSingle	if "true", submits ONLY one field/link, instead of all form controls
eventProducer	MethodBinding pointing at method accepting an PushEventListener with return type void. User bean must register this listener and send EventObject to this listener on ready.
action	MethodBinding pointing at the application action to be invoked, if this UIComponent is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property
timeout	Timeout (in ms) for request
actionExpression	The action method binding expression.
status	ID (in format of call UIComponent.findComponent()) of Request status component
interval	Interval (in ms) for call push requests. Default value 1000 (1 sec)
eventsQueue	Name of requests queue to avoid send next request before complete other from same event. Can be used to reduce number of requests of frequently events (key press, mouse move etc.)
immediate	True means, that the default ActionListener should be executed immediately (i.e. during Apply Request Values phase of the request processing lifecycle), rather than waiting until the Invoke Application phase
enabled	Enable/disable pushing
data	Serialized (on default with JSON) data passed on the client by a developer on AJAX request. It's accessible via "data.foo" syntax
binding	The attribute takes a value-binding expression for a component property of a backing bean
ignoreDupResponses	If true, unfinished request will be aborted on new event.

Table 6.33. Component identification parameters

Name	Value
component-type	org.ajax4jsf.components.Push
component-family	org.ajax4jsf.components.AjaxPush
component-class	org.ajax4jsf.components.AjaxPush
renderer-type	org.ajax4jsf.components.AjaxPushRenderer

6.19.2. Creating on a page

<a4j:push reRender="msg" eventProducer="#{messageBean.addListener}" interval="3000"/>

6.19.3. Dynamical creation of a component from Java code

import org.ajax4jsf.ajax.html.AjaxPush;
...
AjaxPush myPush = new AjaxPush();
...

6.19.4. Key attributes and ways of usage

The main difference between <a4j:push> and <a4j:poll> components is that <a4j:push> makes request to minimal code only (not to JSF tree) in order to check the presence of messages in the queue. If the message exists the complete request will be performed. The component doesn't poll registered beans but registers EventListener which receives messages about events.

There are some attributes which allows to customize of the component behaviour:

'interval' - Interval (in ms) for call push requests. Default value 1000 (1 sec).

Code for registration of listener:

public void addListener(EventListener listener) {
synchronized (listener) {
	if (this.listener != listener) {
	this.listener = (PushEventListener) listener;
}

Component can get message using current code:

System.out.println("event occurs");
synchronized (listener) {
	listener.onEvent(new EventObject(this));
}

Thus, component 'push' uses asynchronous model instead of polls.

6.20. <a4j:region>

6.20.1. Description

The <a4j:region> component defines an area that is decoded on the server after AJAX submission.

Table 6.34. a4j:region attributes

Attribute Name	Description
selfRendered	if "true", self-render subtree at InvokeApplication ( or Decode, if immediate property set to true ) phase
renderRegionOnly	Flag to disable rendering in AJAX responses content outside of active region. If this attribute set to "true" , no one of the components outside of region will be included to AJAX response. If set to "false", search for components to include in response will be performed on all tree. Default "true"
immediate	Flag indicating that, if this component is activated by ajaxrequest, notifications should be delivered to interested listeners and actions immediately (that is, during Apply Request Values phase) rather than waiting until Invoke Application phase
rendered	If "false", this component is not rendered
binding	The attribute takes a value-binding expression for a component property of a backing bean
ajaxListener	MethodBinding representing an action listener method that will be notified when this component is activated by the ajax Request and handle it. The expression must evaluate to a public method that takes an AjaxEvent parameter, with a return type of void
id	Every component may have a unique id that is automatically created if omitted

Table 6.35. Component identification parameters

Name	Value
component-type	org.ajax4jsf.ajax.AjaxRegion
component-family	org.ajax4jsf.components.AjaxRegion.
component-class	org.ajax4jsf.ajax.html.HtmlAjaxRegion
renderer-type	org.ajax4jsf.components.AjaxRegionRenderer

6.20.2. Creating on a page

Here is an example of the region decoding on a page.

<a4j:region>
	<!--..Some content that will be decoded on server after Ajax request.-->
</a4j:region>

6.20.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.HtmlAjaxRegion;
...
HtmlAjaxRegion newRegion = new HtmlAjaxRegion();
...

6.20.4. Key attributes and ways of usage

The region is a component used for manipulation with components sent to the server. It sets particular processing parameters for an area on the server, i.e. the region deals with data input on the server and has no direct impact on output. To read more on the components responsible for out, see "reference"

The region marks an area page that is decoded on the server. In most cases it is not necessary to use the region, as ViewRoot is a default region. This component helps to reduce data quantity processed by the server, but the region doesn't influence on the standard submission rules. It means that:

The area that is to be submitted onto the server should be embedded in <h:form/a4j:form> component.
The whole form is submitted on Ajax response and not a region that request is performed from.

Example:

<h:form id="form1">
	<a4j:region>
		<a4j:commandLink reRender="someID" value="Link" id="link1"/>
		<!--..Some content that will be decoded on server after Ajax request.-->
	</a4j:region>
<h:form>

Hence, the <a4j:commandLink> request generation causes full "form1" form submission onto the server, the only difference is that a component tree part decoded on the serve is the part included into the region.

The regions could be nested in any order, the server picks out and decodes only the region, which contains a particular component that sends a request.

Example:

<a4j:region>
	<a4j:commandLink reRender="someID" value="Link" id="link1"/>
	<a4j:region>
		<a4j:commandLink reRender="someID" value="Link" id="link2"/>
		<!--..Some content that will be decoded on server after Ajax request.-->
	</a4j:region >
	<!--..Some content that will be decoded on server after Ajax request.-->
</a4j:region >

Therefore, the external region is decoded for the "link1" and the internal one is decoded for the "link2".

Ajax4jsf allows setting Ajax responses rendering directly basing on component tree nodes without referring to the JSP (XHTML) page code. It could be defined by selfRendered attribute setting to "true" on <a4j:region> and could help considerably speed up a response output. However, this rapid processing could cause missing of transient components that present on view and don't come into a component tree as well as omitting of <a4j:outputPanel> usage described below.

Example:

<a4j:region selfRendered ="true">
	<a4j:commandLink reRender="someID" value="Link" id="link1"/>
	<!--..Some content with HTML used ("br" ,"h1" and other tags used)-->
</a4j:region >

In this case, the processing is quicker and going on without referring to a page code, but the HTML code that isn't saved in a component tree could be lost. Thus, this optimization should be very carefully performed and a usage of the additional components ajax4jsf ( <a4j:outputPanel> ) is required.

The processing could be also accelerated if a region decoded for the processing passes straight away into Encode. But to update some data out of the region or on another region, use the "renderRegionOnly" attribute set to "false" ("true on default") to change this behaviour.

Example:

<a4j:region renderRegionOnly="true">
	<a4j:commandLink reRender="someID2" value="Link1" id="link1"/>
	<h:panelGroup id="someId1">
	</h:panelGroup>
</a4j:region>
<a4j:region renderRegionOnly="false">
	<a4j:commandLink reRender="someID1" value="Link2" id="link2"/>
	<h:panelGroup  id="someId1">
	</h:panelGroup>
</a4j:region>

This example shows that one of the regions is decoded when a link is used inside. Nevertheless, if after processing the "link1" is clicked, the first region passes into Encode as a root region and encode performance time is reduced. This optimization doesn't allow data update out of the region and should be implemented very carefully. The data out of the region described with "renderRegionOnly"="false" is updated successfully.

6.21. <a4j:repeat>

6.21.1. Description

The <a4j:repeat> component implements a basic iteration component allowing to update a set of its children with AJAX.

Table 6.36. a4j:repeat attributes

Attribute Name	Description
var	A request-scope attribute via which the data object for the current row will be used when iterating
value	The current value for this component.
rows	A number of rows to display, or zero for all remaining rows in the table
first	A zero-relative row number of the first row to display
componentState	It defines EL-binding for a component state for saving or redefinition.
stateVar	The attribute provides access to a component state on the client side.
rowKeyVar	The attribute provides access to a row key in a Request scope.
rendered	If "false", this component is not rendered
id	Every component may have a unique id that is automatically created if omitted
ajaxKeys	This attribute defines strings that are updated after an AJAX request.
binding	The attribute takes a value-binding expression for a component property of a backing bean

Table 6.37. Component identification parameters

Name	Value
component-type	org.ajax4jsf.ajax.Repeat
component-family	javax.faces.Data
component-class	org.ajax4jsf.ajax.html.HtmlAjaxRepeat
renderer-type	org.ajax4jsf.components.RepeatRenderer

6.21.2. Creating on a page

The component definition on a page is the same as for the "facelets" component:

<a4j:repeat id="detail" value="#{bean.props}" var="detail">
	<h:outputText value="#{detail.someProperty}"/>
</a4j:repeat>

The output is generated according to a collection contained in "bean.props" with the "detail" key passed to child components.

6.21.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.HtmlAjaxRepeat;
...
HtmlAjaxRepeat repeater = new HtmlAjaxRepeat ();
...

6.21.4. Key attributes and ways of usage

The main difference of this component from iterative components of other libraries is a special "ajaxKeys" attribute. This attribute defines strings that are updated after an AJAX request. As a result it becomes easier to update several child components separately without updating the whole page.

<a4j:poll intervall="1000" action="#{repeater.action}" reRender="list">
...
<table>
 <tbody>
   <a4j:repeat value="#{bean.props}" var="detail" binding="#{repeater.myRepeat}"
	 id="list" ajaxKeys="#{repeater.ajaxedRowsSet}">
	 </tr>
	   <td>
	    <h:outputText value="detail.someProperty">
	    </td>
	  </tr>
   </a4j:repeat>
   <tbody>
<table>

Thus, a list with a table structure from "bean.props" is output.

In the above-mentioned example the component <a4j:poll> sends AJAX requests every second, calling the "action" method of the "repeater" bean.

Note:

The <a4j:repeater> component is defined as fully updated, but really updated there are only the strings which rowKeys are included into the set "ajaxRowSet" defined in the "ajaxKeys" attribute

The set could be defined during the action method processing using data on a model from the property "repeater.myRepeat"

One more benefit of this component is absence of strictly defined markup as JSF HTML DataTable and Tomahawk DataTable has, hence the components could be used more flexibly anywhere where it's necessary to output the results of selection from some collection.

The next example shows collection output as a plain HTML list

<ul>
      <a4j:repeat ...>
	    <li>...<li/>
	     ...
	    <li>...<li/>
      </a4j:repeat>
</ul>

All other general attributes are defined according to the similar attributes of iterative components ( <h:dataTable> or <ui:repeat> ) and are used in the same way.

6.22. <a4j:status>

6.22.1. Description

The <a4j:status> component generates elements for displaying of the current AJAX requests status. There are two status modes: AJAX request is in process or finished.

Table 6.38. a4j:status attributes

Attribute Name	Description
startStyleClass	CSS style class for the element displayed on the start of a request.
stopStyle	CSS style for element displayed on request completion.
stopStyleClass	CSS style class for element displayed on request
layout	Define visual layout of panel, can be "block" or "inline".
title	Advisory title information about markup elements generated for this component
onstart	JavaScript code, called on the start of a request.
rendered	If "false", this component is not rendered
id	Every component may have a unique id that is automatically created if omitted
dir	Direction indication for text that does not inherit directionality. Valid values are "LTR" (left-to-right) and "RTL" (right-to-left)
styleClass	Corresponds to the HTML class attribute
startStyle	CSS style class for the element displayed on the start of a request.
onkeypress	HTML: a script expression; a key is pressed and released
ondblclick	HTML: a script expression; a pointer button is double-clicked
style	CSS style(s) is/are to be applied when this component is rendered
onmouseover	HTML: a script expression; a pointer is moved onto
for	ID of the AjaxContainer component whose status is indicated (in the format of a javax.faces.UIComopnent.findComponent() call).
onkeyup	HTML: a script expression; a key is released
lang	Code describing the language used in the generated markup for this component
onclick	HTML: a script expression; a pointer button is clicked
onmouseout	HTML: a script expression; a pointer is moved away
startText	Text for display on starting request.
onkeydown	HTML: a script expression; a key is pressed down
onmousedown	HTML: script expression; a pointer button is pressed down
forceId	If true, render the ID of the component in HTML code without JSF modifications.
stopText	Text for display on request complete.
onstop	JavaScript code, called on the stop of a request.
onmouseup	HTML: script expression; a pointer button is released
binding	The attribute takes a value-binding expression for a component property of a backing bean
onmousemove	HTML: a script expression; a pointer is moved within

Table 6.39. Component identification parameters

Name	Value
component-type	org.ajax4jsf.ajax.Status
component-family	javax.faces.Panel
component-class	org.ajax4jsf.ajax.html.HtmlAjaxStatus
renderer-type	org.ajax4jsf.components.AjaxStatusRenderer

6.22.2. Creating on a page

There are two ways to define elements indicating a request status :

With "StartText"/"StopText" atributes:
```
<a4j:status startText="Progress" stopText="Done" for="stat1">
```
In this case, text elements for the corresponding status are generated.

With "Start"/"Stop" facets definition:

<a4j:status for="stat2">
	<f:facet name="start">
		<h:graphicImage value="ajax_process.gif" />
	</f:facet>
	<f:facet name="stop">
		<h:graphicImage value="ajax_stoped.gif" />
	</f:facet>
</a4j:status>

In this case, the elements are generated for each status and correspond the facets content.

6.22.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.HtmlAjaxStatus;
...
HtmlAjaxStatus  myStatus = new HtmlAjaxStatus();
...

6.22.4. Key attributes and ways of usage

There are two ways for components or containers definition, which AJAX requests status is tracked by a component.

Definition with the "for" attribute on the <a4j:status> component. Here "for" attribute should point at an AJAX container ( <a4j:region> ) "id", which requests are tracked by a component.

Definition with the "status" attribute obtained by any Ajax4jsf library action component. The attribute should point at the <a4j:status> component "id". Then this <a4j:status> component shows the status for the request fired from this action component.

The component creates two <span> elements with content defined for each status, one of the elements (start) is initially hidden. At the beginning of an AJAX request, elements state is inversed, hence the second element is shown and the first is hidden. At the end of a response processing, elements display states return to its initial values.

Example:

<a4j:status startText="Started" stopText="stopped"  layout="block"/>

is decoded on a page as:

<span id="j_id20:status.start" style="display: none">
      Started
</span>
<span id="j_id20:status.stop">
        Stopped
</span>

And after the generation of an AJAX response is changed to:

<span id="j_id20:status.start">
        Started
</span>
<span id="j_id20:status.stop" style="display: none">
        Stopped
</span>

There is a possibility to group a <a4j:status> elements content into <div> elements, instead of <span> . To use it, just redefine the "layout" attribute from "incline"(default) to "block".

6.23. <a4j:support>

6.23.1. Description

The <a4j:support> component adds an AJAX support to any existing JSF component. It allows a component to generate asynchronous requests on the necessary event demand and with partial update of page content after a response incoming from the server.

Table 6.40. a4j:support attributes

Attribute Name	Description
actionListener	MethodBinding pointing at method accepting an ActionEvent with return type void
oncomplete	JavaScript code for call after request completed on client side
rendered	If "false", this component is not rendered
reRender	Id['s] (in format of call UIComponent.findComponent()) of components, rendered in case of AjaxRequest caused by this component. Can be single id, comma-separated list of Id's, or EL Expression with array or Collection
focus	id of element to set focus after request completed on client side
id	Every component may have a unique id that is automatically created if omitted
disableDefault	Disable default action for target event ( append "return false;" to javascript )
bypassUpdates	If "true", after process validations phase it skips updates of model beans on a force render response. It can be used for validating components input
limitToList	If "true", updates on client side ONLY elements from this 'reRender' property. If "false" (default) updates all rendered by ajax region components
ajaxSingle	if "true", submits ONLY one field/link, instead of all form controls
onsubmit	JavaScript code for call before submission of ajax event
action	MethodBinding pointing at the application action to be invoked, if this UIComponent is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property
timeout	Timeout (in ms) for request
actionExpression	The action method binding expression.
status	ID (in format of call UIComponent.findComponent()) of Request status component
requestDelay	Delay (in ms.) for send ajax request on JavaScript event. In conjunction with events queue can reduce number of requests on keyboard or mouse move events
eventsQueue	Name of requests queue to avoid send next request before complete other from same event. Can be used to reduce number of requests of frequently events (key press, mouse move etc.)
immediate	True means, that the default ActionListener should be executed immediately (i.e. during Apply Request Values phase of the request processing lifecycle), rather than waiting until the Invoke Application phase
data	Serialized (on default with JSON) data passed on the client by a developer on AJAX request. It's accessible via "data.foo" syntax
event	Name of JavaScript event property ( onclick, onchange, etc.) of parent component, for which we will build AJAX submission code
binding	The attribute takes a value-binding expression for a component property of a backing bean
ignoreDupResponses	If true, unfinished request will be aborted on new event

Table 6.41. Component identification parameters

Name	Value
component-type	org.ajax4jsf.ajax.Support
component-family	org.ajax4jsf.components.AjaxSupport
component-class	org.ajax4jsf.ajax.html.HtmlAjaxSupport
renderer-type	org.ajax4jsf.components.AjaxSupportRenderer

6.23.2. Creating on a page

To use a component, place <a4j:support> as nested to the component requesting AJAX functionality and specify an event of a parent component that generates AJAX request and the components to be rerendered after a response from the server.

Example:

<h:inputText value="#{bean.text}">
	<a4j:support event="onkeyup" reRender="repeater"/>
</h:inputText>
<h:outputText id="repeater" value="#{bean.text}"/>

On every keyup event generated by an input field, a form is submitted on the server with the help of Ajax and on a response coming from the server, element with "repeater" id, founded in a DOM tree is redrawn according to a new data from the response.

6.23.3. Dynamical creation of a component from Java code

Example:

import org.ajax4jsf.ajax.html.HtmlAjaxSupport;
...
HtmlAjaxSupport mySupport = new HtmlAjaxSupport();>

6.23.4. Key attributes and ways of usage

A4j support addition is very similar to correspondent event redefinition of a component, i.e.

Example:

<h:inputText value="#{bean.text}">
    <a4j:support event="onkeyup" reRender="repeater"/>
</h:inputText>

Is decoded on the page as:

Example:

<input  onkeyup="A4J.AJAX.Submit( Some request parameters )"/>

As you see from the code, the "onkeyup" event calls a utility ajax4jsf method that submit a form creating a special marks for a filter informing that it is an Ajax request. Thus, any supports quantity could be added to every component, the supports define component behavior on these events.

Note

The components: <a4j:commandLink> , <a4j:commandButton> , <a4j:poll> and others from Ajax4jsf library are already supplied with <a4j:support> functionality and there is no necessity to add the support to them.

With the help of "onsubmit" and "oncomplete" attributes the component allows using JavaScript before (for request sending conditions checking) and after an AJAX response processing termination (for performance of user-defined activities on the client)

Example:

<h:selectOneMenu value="#{bean.text}">
	<f:selectItem itemValue="First Item " itemLabel="First Item"/>
	<f:selectItem itemValue=" Second Item " itemLabel="Second Item"/>
	<f:selectItem itemValue=" Third Item " itemLabel="Third Item"/>
		<a4j:support event="onblur" reRender="panel" onsubmit="if(!confirm('Are you sure to change the option ?')) 
					{form.reset(); return false;}" oncomplete="alert('Value succesfully stored')"/>
</h:selectOneMenu>

In example there is the condition checking (confirm) is used before request sending and message printing after the request processing is over.

The components allows different AJAX request managing ways for its various optimization in particular conditions such as:

Limitation of the submit area and updating area for the request.
"ajaxSingle" is an attribute that allows submission on the server only component sending a request, as if the component presented on a separate form.
"limitToList" is an attribute that allows to limit areas, which are updated after the responses. Only these components defined in the reRender attribute are updated.

Example 1:

<h:form>
	<h:inputText value="#{person.name}">
		<a4j:support event="onkeyup" reRender="test" ajaxSingle="true"/>
	</h:inputText>
	<h:inputText value="#{person.middleName}"/>
</form>

In this example the request contains only the input component causes the request generation, not all the components contained on a form, because of "ajaxSingle=true" usage.

Example 2:

<h:form>
	<a4j:outputPanel ajaxRendered="true">
		<h:messages/>
	</a4j:outputPanel>
	<h:inputText value="#{person.name}">
		<a4j:support event="onkeyup" reRender="test" limitToList="true"/>
	</h:inputText>
	<h:outputText value="#{person.name}" id="test"/>
</form>

In this example the component "h:messages" is always updated (as it capturing all AJAX requests, located in ajaxRendered <a4j:outputPanel> ), except the case when a response is sent from the input component from the example. On sending this component marks that updating area is limited to the defined in it components, it means that on its usage with "limitToList"="true" the only component updated is the one with "d"="test".

Limitation of requests frequency and updates quantity after the responses.
"requestDelay" is an attribute that defines a time interval in seconds minimally permissible between responses.
"eventQueue" is an attribute for naming of the queue where the next response is kept in till its processing, but if the next event comes in till this time is over, the waiting event is taken away, replacing with a new one.
"ignoreDupResponces" is an attribute that allows to disable any updates on the client after an AJAX request if another AJAX request is already sent.
"timeout" is an attribute that allows to set a time interval in millisecond to define a maximum time period of response wait time. In case of the interval interaction, a new request is sent and the previous one is canceled. Postprocessing of a response isn't performed.
Example:
```
<h:form>
	<h:inputText value="#{person.name}">
	   <a4j:support event="onkeyup" reRender="test" 
	   requestDelay="1000" ignoreDupResponces="true" eventsQueue="myQueue"/>
	</h:inputText>
	<h:outputText value="#{person.name}" id="test"/>
</form>
```
This example clearly shows mentioned above attributes. If quick typing in a text field happens, every next requests sending is delayed for a second and requests quantity is reduced. The requests are kept in the queue "myQueue" till its the sending. Moreover, if the next request is already sent, the rerendering after the previous request is banned, and it helps to avoid unnecessary processing on the client.

6.24. Other Relevant Resources

Introduction to Ajax4Jsf - Exploring the Ajax4Jsf Library by Shunmuga Raja

Chapter 7. Built-in skinnability in Ajax4jsf

Ajax4jsf gives an opportunity to incorporate skinnability into UI design. With this framework you can easily use named skin parameters in properties files to control the appearance of the skins that are applied consistently to a whole set of components. You can look at examples of predefined skins at:

http://livedemo.exadel.com/richfaces-demo/

You may simply control the look-and-feel of your application by using the skinnability service of the Ajax4jsf framework. With the means of this service you can define the same style for rendering standard JSF components and custom JSF components built with the help of Ajax4jsf.

To find out more on skinnability possibilities, follow these steps:

Create a custom render kit and register it in the faces-config.xml like this:

<render-kit>
        <render-kit-id>NEW_SKIN</render-kit-id>
        <render-kit-class> 
            org.ajax4jsf.framework.renderer.ChameleonRenderKitImpl
        </render-kit-class>
</render-kit>

Then you need to create and register custom renderers for the component based on the look-and-feel predefined variables:

<renderer>
        <component-family>javax.faces.Command</component-family> 
        <renderer-type>javax.faces.Link</renderer-type> 
        <renderer-class>
           newskin.HtmlCommandLinkRenderer
        </renderer-class> 
</renderer>

Finally, you need to place a properties file with skin parameters into the class path root. There are two requirements for the properties file:
- The file must be named <skinName>.skin.properties, in this case, it would be called newskin.skin.properties.
- The first line in this file should be render.kit= <render-kit-id>, in this case, it would be called render.kit=NEW_SKIN.

Extra information on custom renderers creation can be found at:

http://java.sun.com/javaee/javaserverfaces/reference/docs/index.html

Chapter 8. IDE Integration

Exadel Studio 4 is an IDE that provides a full support for Exadel RichFaces, Ajax4jsf, Facelets, Struts, MyFaces, and other Web technologies. In addition to this, it seamlessly combines visual and source-oriented development approaches. One way in which Ajax4jsf and RichFaces are supported is implemented via special predefined capabilities that can be added to any JSF project and then be accessed with the help of the Visual Page Editor, Open On, Content Assist, and Components Palette features.

Chapter 9. Links to Web Resources

Table 9.1. Ajax4jsf Resources

Resources	Links
Ajax4jsf on jboss.org	JBoss Ajax4jsf
RichFaces	JBoss RichFaces
JBoss Forums	JBoss Forums
Ajax4Jsf Wiki	Ajax4Jsf Wiki
RichFaces Wiki	RichFaces Wiki
Ajax4jsf/RichFaces Blog	Ajax4jsf/RichFaces Blog