JBoss.orgCommunity Documentation

Chapter 6. Containers

6.1. <a4j:form>
6.2. <a4j:include>
6.3. <a4j:outputPanel>
6.4. <a4j:page>
6.5. <a4j:region>

This chapter details those components in the a4j tag library which define an area used as a container or wrapper for other components.

6.1. <a4j:form>

The <a4j:form> builds on the functionality of the JavaServer Faces (JSF) component <h:form>, adding Ajax capabilities to the form.

Command link rendering fixed

The JSF component <h:form>, on which the <a4j:form> component is based, had an issue whereby the <h:commandLink> component could not be re-rendered without re-rendering the entire form. <a4j:form> and <a4j:commandLink> fix this issue.

The <a4j:form> component can add indirect Ajax support to non-Ajax components on the form by setting ajaxSubmit="true". It then uses the standard Ajax component attributes and updates components specified with the render attribute.

ajaxSubmit

<a4j:form> should not use ajaxSubmit="true" if it contains other Ajax-capable components.

Additionally, due to security reasons the file upload form element cannot be indirectly made Ajax-capable with <a4j:form>.

6.2. <a4j:include>

The <a4j:include> component allows one view to be included as part of another page. This is useful for applications where multiple views might appear on the one page, with navigation between the views. Views can use partial page navigation in Ajax mode, or standard JSF navigation for navigation between views.

The viewId attribute is required to reference the resource that will be included as a view on the page. It uses a full context-relative path to point to the resource, similar to the paths used for the <from-view-id> and <to-view-id> tags in the faces-config.xml JSF navigation rules.

Example 6.1. A wizard using <a4j:include>

The page uses <a4j:include> to include the first step of the wizard: 




<h:panelGrid width="100%" columns="2">

    <a4j:keepAlive beanName="profile" />

    <rich:panel>

        <f:facet name="header">

        <h:outputText value="A wizard using a4j:include" />

        </f:facet>

        <h:form>

            <a4j:include viewId="/richfaces/include/examples/wstep1.xhtml" />

        </h:form>

    </rich:panel>

</h:panelGrid>

The first step is fully contained in a separate file, wstep1.xhtml. Subsequent steps are set up similarly with additional Previous buttons. 




<ui:composition xmlns="http://www.w3.org/1999/xhtml"

      xmlns:ui="http://java.sun.com/jsf/facelets"

      xmlns:h="http://java.sun.com/jsf/html"

      xmlns:f="http://java.sun.com/jsf/core"

      xmlns:a4j="http://richfaces.org/a4j"

      xmlns:rich="http://richfaces.org/rich">

    

    <div style="position:relative;height:140px">

        <h:panelGrid rowClasses="s1row" columns="3" columnClasses="wfcol1,wfcol2,wfcol3">

            <h:outputText value="First Name:" />

            <h:inputText id="fn" value="#{profile.firstName}" label="First Name" required="true" />

            <rich:message  for="fn" />

            

            <h:outputText value="Last Name:" />

            <h:inputText  id="ln" value="#{profile.lastName}"  label="Last Name"  required="true" />

            <rich:message  for="ln" />

        </h:panelGrid>

        <div class="navPanel" style="width:100%;">

            <a4j:commandButton style="float:right" action="next" value="Next &gt;&gt;"/>

        </div>

    </div>

</ui:composition>

The navigation is defined in the faces-config.xml configuration file: 




<navigation-rule> 

   <from-view-id>/richfaces/include/examples/wstep1.xhtml</from-view-id> 

   <navigation-case> 

      <from-outcome>next</from-outcome> 

      <to-view-id>/richfaces/include/examples/wstep2.xhtml</to-view-id> 

   </navigation-case> 

</navigation-rule>  

<navigation-rule> 

   <from-view-id>/richfaces/include/examples/wstep2.xhtml</from-view-id> 

   <navigation-case> 

      <from-outcome>previous</from-outcome> 

      <to-view-id>/richfaces/include/examples/wstep1.xhtml</to-view-id> 

   </navigation-case> 

   <navigation-case> 

      <from-outcome>next</from-outcome> 

      <to-view-id>/richfaces/include/examples/finalStep.xhtml</to-view-id> 

   </navigation-case> 

</navigation-rule>  

<navigation-rule> 

   <from-view-id>/richfaces/include/examples/finalStep.xhtml</from-view-id> 

   <navigation-case> 

      <from-outcome>previous</from-outcome> 

      <to-view-id>/richfaces/include/examples/wstep2.xhtml</to-view-id> 

   </navigation-case> 

</navigation-rule> 

6.3. <a4j:outputPanel>

The <a4j:outputPanel> component is used to group together components in to update them as a whole, rather than having to specify the components individually.

The layout attribute can be used to determine how the component is rendered in HTML:

Setting ajaxRendered="true" will cause the <a4j:outputPanel> to be updated with each Ajax response for the page, even when not listed explicitly by the requesting component. This can in turn be overridden by specific attributes on any requesting components.

6.4. <a4j:page>

The <a4j:page> component encodes a full HTML-page structure using only one tag. It renders complete <!DOCTYPE>, <html>, <head>, <title>, and <body> tags using the specified attributes and facets. Additionally, the <a4j:page> component solves an incompatibility issue between early versions of MyFaces and the Ajax4jsf framework.

The pageTitle attribute is rendered as a <title> element. The component uses the head facet to define the contents of the HTML <head> element. The format facet defines the page layout format for encoding the <!DOCTYPE> element. There rest of the contents of the <a4j:page> component are rendered as part of the <body> element.

Example 6.2. <a4j:page> rendering

An <a4j:page> component can be defined as follows: 


<a4j:page format="xhtml" pageTitle="myPage">

      <f:facet name="head">

            <!--Head Content here-->

      </f:facet>

      <!--Page Content Here-->

</a4j:page>

This definition will render on an XHTML page as follows: 


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html>

    <head> 

        <title>myPage</title>

        <!--Head Content here-->

    </head> 

    <body>

        <!--Page Content Here-->

    </body> 

</html>

When using the Ajax4jsf framework with MyFaces version 1.2.2 and lower, the <f:view> JSP tag does not receive control for encoding contents during the RENDER_RESPONSE phase. As a result, Ajax fails to receive control and send responses. The <a4j:page> component solves this problem by wrapping the Ajax areas to be updated. Later versions of MyFaces do not have this problem, and as such do not require the use of the <a4j:page> component.

6.5. <a4j:region>

The <a4j:region> component specifies a part of the document object model (DOM) tree to be processed on the server. The processing includes data handling during decoding, conversion, validation, and model updating. When not using <a4j:region>, the entire view functions as a region.

The whole form is still submitted to the server, but only the specified region is processed. Regions can be nested, in which case only the immediate region of the component initiating the request will be processed.