<?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>
<!--...Some Content Inside-->
</a4j:outputPanel>
]]></programlisting>
  </section>
  <section>
    <title>Dynamical creation of a component from Java code</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:outPanel&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 Ajax4jsf 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, Ajax4jsf 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 reRender 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 ajaxRendered 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 layout=&quot;block&quot; 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’s possible to apply any available style attributes available for block tags. </para>
    <para>Layout=&quot;none&quot; 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 &quot;display:none&quot; 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 Ajax4jsf 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, 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.</para>
    <para>Note: In JSF 1.1 implementation and lower, where non-JSF context should be framed with the &quot;f:verbatim&quot; attribute,  <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 Ajax4jsf usage. </para>
    <para>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 <emphasis >
        <property>&quot;true&quot;</property>
      </emphasis> 
 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>
	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>.
	<!--
	To see how component works on practice, look at a4j-outputPanel example from 
	<ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/outputPanel.jsf?c=outputPanel">RichFaces Live Demo</ulink>. -->
	</para>	  
  </section>  
</chapter>