a4j:include functionality is equal to the facelets ui:include functionality, plus, it enables the partial page navigation in an Ajax mode. The standard JSF navigation rules are used to define the navigation between the view.

viewId attribute specifies the view id of a page that will be included. It should be a full context-relative path of the resource in order to use as from-view and to-view in the JSF navigation cases.

Include example

The demo shows the example of three-steps wizard created using a4j:include. The navigation rules defined in the faces-config.xml are used to navigate between the steps of the wizard.

Using a4j:include for Wizard-like behaviour First Name: Last Name: Company:

HideView Source

<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">

    <style type="text/css">
        .col1 { vertical-align:top; }
        .col2 { vertical-align:top; width:450px; }
        .wizard { width:400px; }
        .wform td { vertical-align:top; }
        .wfcol1 { text-align: right; white-space:nowrap;}
        .wfcol2 { }
        .wfcol3 { }
        .s1row td { height:30px; }
        .rich-message { color:red;  }
        
        .navPanel {
            position:absolute;
            bottom:0;
            height:23px;
            margin:0;
            padding:2px;
        }

    </style>
    <br/>
    <h:panelGrid width="100%" columns="2" columnClasses="col1,col2">
        <a4j:keepAlive beanName="profile" />
        <rich:panel styleClass="wizard">
            <f:facet name="header">
            <h:outputText value="Using a4j:include for Wizard-like behaviour" />
            </f:facet>
            <h:form>
                <a4j:include viewId="/richfaces/include/examples/wstep1.xhtml" />
            </h:form>
        </rich:panel>
    
    </h:panelGrid>
    <br/>

</ui:composition>

<<Hide Source

HideView wstep1.xhtml Source

<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:outputText value="Company:" />
        <h:inputText id="comp" value="#{profile.company}"  label="Company"  required="true" />
        <rich:message for="comp"/>
    </h:panelGrid>
    <div class="navPanel" style="width:100%;">
        <a4j:commandButton style="float:right" action="next" value="Next &gt;&gt;"/>
    </div>
    </div>
</ui:composition>

<<Hide Source

HideView wstep2.xhtml Source

<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 columns="3" columnClasses="wfcol1,wfcol2,wfcol3">
        <h:outputText value="Notes:" />
        <h:inputTextarea cols="20" rows="4" id="notes" value="#{profile.notes}" label="Notes" required="true" />
        <rich:message  for="notes" />
    </h:panelGrid>
    <div class="navPanel" style="width:100%;">
    <a4j:commandButton value="&lt;&lt;Previous" style="float:left"  immediate="true" action="previous"/>
    <a4j:commandButton value="Next &gt;&gt;"  style="float:right"  action="next"/>
    </div>

    
    </div>
</ui:composition>

<<Hide Source

HideView finalStep.xhtml Source

<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
            columns="2" columnClasses="wfcol1">
            <h:outputText value="First Name:" />
            <h:outputText value="#{profile.firstName}" />
            <h:outputText value="Last Name:" />
            <h:outputText value="#{profile.lastName}" />
            <h:outputText value="Company:" />
            <h:outputText value="#{profile.company}" />
            <h:outputText value="Notes:" />
            <h:outputText value="#{profile.notes}" />
        </h:panelGrid>
        <div class="navPanel">
            <a4j:commandButton  value="&lt;&lt;Previous" style="float:left" immediate="true"
                action="previous" />
        </div>
    </div>

</ui:composition>

<<Hide Source

HideView faces-config.xml Navigation Rules

<?xml version="1.0"?>
<!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
                              "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">
<faces-config>
<!--  The rest parts of the faces-config.xml are not shown here -->
<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> 
 </faces-config>

<<Hide Source

The Ajax command component (button, link, jsFunction, etc) should be located inside the a4j:include in order to have a partial navigation. When the navigation is performed, a part of the component tree content is replaced with the content of a view given by a navigation rule.

The content of the a4j:include is not isolated from the whole view. You can point to the other parts of the view with reRender if you want to update them while you navigate inside the a4j:include.