<?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 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: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>
				<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 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>
			<code>layout =&quot;none&quot;</code>
			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&apos;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
			<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>
			<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>
			<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 on the
			found
			<ulink
				url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&amp;p=4052203#4052203">
				Ajax4JSF Users Forum
			</ulink>
			.

		</para>
	</section>
</chapter>