<?xml version='1.0' encoding='UTF-8'?>
<chapter>
  
    <table>
	    <title>Component identification parameters </title>
      <tgroup cols="2">
	  <thead>
            <row>
                <entry>Name</entry>
                <entry>Value</entry>
            </row>
        </thead>
        <tbody>
          <row>
            <entry>component-type</entry>
            <entry>org.ajax4jsf.OutputPanel</entry>
          </row>
          <row>
            <entry>component-family</entry>
            <entry>javax.faces.Panel</entry>
          </row>
          <row>
            <entry>component-type</entry>
            <entry>org.ajax4jsf.ajax.OutputPanel</entry>
          </row>
          <row>
            <entry>component-class</entry>
            <entry>org.ajax4jsf.component.html.HtmlAjaxOutputPanel</entry>
          </row>
          <row>
            <entry>renderer-type</entry>
            <entry>org.ajax4jsf.components.AjaxOutputPanelRenderer</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  
  <section>
    <title>Creating on a page</title>
    <para>Here is the simplest way for a component creation on a page.</para>

  <para>
      <emphasis role="bold">Example:</emphasis>
 </para>
    <programlisting role="XML"><![CDATA[        <a4j:outputPanel>
                    <h:form>
                        <h:outputText value="Some text"/>
                            <h:inputText id="text1" label="text1" value="#{rsBean.text1}">
                            </h:inputText>
                    </h:form>
        </a4j:outputPanel>
]]></programlisting>
  </section>
  <section>
    <title>Creating the Component Dynamically Using Java</title>

  <para>
      <emphasis role="bold">Example:</emphasis>
 </para>
    <programlisting role="JAVA"><![CDATA[import org.ajax4jsf.component.html.HtmlAjaxOutputPanel;
...
HtmlAjaxOutputPanel  myPanel = new HtmlAjaxOutputPanel();
]]></programlisting>
  </section>
  <section>
    <title>Key attributes and ways of usage</title>
    <para><emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis> allows marking of a page area, which is updated on Ajax response. Anyway, <emphasis role="bold">
        <property>&lt;a4j:outputPanel&gt;</property>
      </emphasis> usage is optional, as in RichFaces it&apos;s possible to indicate any existing component id on a component view in order to define updating areas. 

To speed up the performance, RichFaces updates only a component tree. <emphasis role="bold">
        <property>&lt;a4j:outputPanel&gt;</property>
      </emphasis> usage is recommended for wrapping components that aren&apos;t rendered during the primary non-ajax response, as the components don&apos;t present in a component tree. 
</para>
    <para><emphasis role="bold">Example:</emphasis></para>
    <programlisting role="XML"><![CDATA[<a4j:support ... reRender="mypanel"/>
...
<a4j:outputPanel id="mypanel">
  <h:panelGrid rendered="#{not empty foo.bar}">
	...
  </h:panelGrid>
</a4j:outputPanel>
]]></programlisting>
    <para>In addition to the areas directly indicated in<emphasis><property> &quot;reRender&quot; </property></emphasis>attribute of Ajax components, <emphasis role="bold">
        <property>&lt;a4j:outputPanel&gt;</property>
      </emphasis> allows to update a part of a page basing on its own flag. The flag is defined by the<emphasis><property> &quot;ajaxRendered&quot; </property></emphasis>attribute. The flag is commonly used when a part of a page must be updated or can be updated on any response.</para>
    <para><emphasis role="bold">Example:</emphasis></para>
	<programlisting role="XML"><![CDATA[<a4j:outputPanel ajaxRendered="true">
  <h:messages/>
</a4j:outputPanel>
]]></programlisting>
    <para>On default <emphasis role="bold">
        <property>&lt;a4j:outputPanel&gt;</property>
      </emphasis> is output as a pair of opening and closing html <emphasis role="bold"><property>&lt;span&gt;</property></emphasis> tag, but with the help of the layout attribute this output way could be changed. There are three variants for this component value:</para>
    <itemizedlist>
      <listitem>
        inline (default)
      </listitem>
      <listitem>
        block
      </listitem>
      <listitem>
        none
      </listitem>
    </itemizedlist>
    <para>If <emphasis><property> &quot;layout&quot; </property></emphasis>=<property>&quot;block&quot;</property> is chosen, the component is rendered as a pair of opening and closing <emphasis role="bold"><property>&lt;div&gt;</property></emphasis> tag, to which it&apos;s possible to apply any available style attributes available for block tags. </para>
    <para><emphasis><property> &quot;layout&quot; </property></emphasis>=<property>&quot;none&quot;</property> helps to avoid an unnecessary tag round a context that could or couldn&apos;t be rendered according to the defined <emphasis><property>&quot;rendered&quot;</property></emphasis> attribute conditions. If an inner context isn’t rendered, <emphasis role="bold">
        <property>&lt;a4j:outputPanel&gt;</property>
    </emphasis> is rendered as a <emphasis role="bold"><property>&lt;span&gt;</property></emphasis> tag with the id equal to an id of a child component and <property>display:none</property> style. If a child component is rendered, <emphasis role="bold">
        <property>&lt;a4j:outputPanel&gt;</property>
      </emphasis> doesn&apos;t present at all in a final code.</para>
    <para><emphasis role="bold">Example:</emphasis></para>
	<programlisting role="XML"><![CDATA[<a4j:support .... reRender="mypanel"/>
...
<a4j:outputPanel layout="none">
  <h:panelGrid id="mypanel" rendered="#{not empty foo.bar}">
	...
  </h:panelGrid>
</a4j:outputPanel>
]]></programlisting>
    <para>As you see, the code is very similar to the one shown above, but <emphasis ><property>&quot;reRender &quot;</property></emphasis> attribute refers directly to the updating panelGrid and not to the framing outputPanel, and it&apos;s more semantically correct.</para>
    <para><emphasis role="bold"><property>&lt;a4j:outPanel&gt;</property></emphasis> should be used for non-JSF component part framing, which is to be updated on Ajax response, as RichFaces specifies the list of updating areas as a list of an existing JSF component. </para>
    <para>On default non-JSF context isn&apos;t saved in a component tree, but is rendered anew every time. To accelerate the processing speed and Ajax response input speed, RichFaces saves non-JSF context in a component tree on default. This option could be canceled by<emphasis><property> &quot;keepTransient&quot; </property></emphasis>attribute that cancels transient flag forced setting for child components. This flag setting keeps the current value set by child components.</para>
    <note>
      <title>Note:</title>
    <para>In JSF 1.1 implementation and lower, where non-JSF context should be framed with the <emphasis role="bold"><property>&lt;f:verbatim&gt;</property></emphasis> component,  <emphasis role="bold">
        <property>&lt;a4j:outputPanel&gt;</property>
    </emphasis> doesn&apos;t improve this JSF implementation option in any way, so you still have to use this tag where it&apos;s necessary without RichFaces usage. </para>
    </note>
    <para>RichFaces 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 
        <property>&quot;true&quot;</property>
       
 on <emphasis role="bold">
        <property>&lt;a4j:region&gt;</property>
      </emphasis> 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. </para>
  </section>
  <section>
    <title>Relevant resources links</title>
    <para><ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/outputPanel.jsf?c=outputPanel"
      >Here</ulink> you can see the example of <emphasis role="bold"
        ><property>&lt;a4j:outputPanel&gt;</property></emphasis> usage and sources for the given example.</para>
    <para>
	Some additional information about usage of component can be found
	<ulink url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&amp;p=4052203#4052203">here</ulink>.
	
	</para>	  
  </section>  
</chapter>