JBoss.orgCommunity Documentation
This chapter details those components in the a4j tag library which define an area used as a container or wrapper for other components.
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 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 >>"/>
</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>
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:
layout="inline" is the default behavior, which will render the component as a pair of <span> tags containing the child components.
layout="block" will render the component as a pair of <div> tags containing the child components, which will use any defined <div> element styles.
layout="none" will render the component as a pair of <span> tags with an identifier equal to that of a child component. If the child component is rendered then the <span> are not included, leaving no markup representing the <a4j:outputPanel> 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.
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.