<?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>On
			<ulink
				url="http://livedemo.exadel.com/richfaces-demo/richfaces/outputPanel.jsf?c=outputPanel"
				> RichFaces Live Demo page </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 on the <ulink
				url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&amp;p=4052203#4052203"
				> Ajax4JSF Users Forum </ulink>
		</para>
		<para> See how the <emphasis role="bold">
			<property>&lt;a4j:outputPanel&gt;</property>
		</emphasis> component can be used in the <ulink
			url="http://www.jboss.org/auth/wiki//RichFacesCookbook/FormOldNew">Ajax Input form with detection of Old/New
			Values</ulink> example in the RichFaces cookbook.
		</para>
	</section>
</chapter>
