<?xml version='1.0' encoding='UTF-8'?>
<chapter>
	<chapterinfo>
		<keywordset>
			<keyword>a4j:outputPanel</keyword>
		</keywordset>
	</chapterinfo>
	<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 the Component with a Page Tag</title>
	      <para>
	            To create the simplest variant on a page use the following syntax:
	      </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: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>Details of usage</title>
            <para>
                  The <emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis> component is used when one or more components should be always updated. 
                  The component job is similar to that the <emphasis><property>&quot;reRender&quot;</property></emphasis> attribute does, but instead of specifying a comma separated list of components it wraps the components to be updated. 
                  This could be useful in cases when some components aren&apos;t rendered during the primary non-ajax response.
            </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>
                  By default the <emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis> is rendered as opening and closing HTML <emphasis role="bold"><property>&lt;span&gt;</property></emphasis> tags and functions as container. 
                  With the help of the <emphasis><property>&quot;layout&quot;</property></emphasis> attribute this output way could be set to any of three variants: 
            </para>
            <itemizedlist>
                  <listitem>
                        <para>&quot;inline&quot; (default)</para>
                  </listitem>
                  <listitem>
                        <para>&quot;block&quot;</para>
                  </listitem>
                  <listitem>
                        <para>&quot;none&quot;</para>
                  </listitem>
            </itemizedlist>
            
            <para>
                  If <code>layout=&quot;block&quot;</code> is set, the component is rendered as a pair of opening and closing <emphasis role="bold"><property>&lt;div&gt;</property></emphasis> tags. 
                  In this case it is possible to apply available for <emphasis role="bold"><property>&lt;div&gt;</property></emphasis> elements style attributes.
                  <code>layout =&quot;none&quot;</code> helps to avoid an unnecessary tag around a context that is rendered or not according to the <emphasis><property>&quot;rendered&quot;</property></emphasis> attribute value. 
                  In case an inner context isn&apos;t rendered the <emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis> is rendered in a <emphasis role="bold"><property>&lt;span&gt;</property></emphasis> tags with ID equal to ID of a child component and <code>display:none</code> 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>
                  The <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>
		      The <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 <emphasis>
				<property>&quot;selfRendered&quot;</property>
			</emphasis> attribute setting to &quot;true&quot; 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&apos;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>
	            Vizit <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/outputPanel.jsf?c=outputPanel">OutputPanel page</ulink> at RichFaces Livedemo for examples of component usage and their sources.
	      </para>
	      
	      <para>
	            Useful articles:
	      </para>
                              <itemizedlist>
                                    <listitem>
                                          <para>
                                                search the <ulink url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&amp;f=26">RichFaces Users Forum</ulink> for some additional information on component usage;
                                          </para>
                                    </listitem>
                                   
                              </itemizedlist>
	      
	      
	      
	</section>
</chapter>
