3:35 p.m.
Author: atsebro
Date: 2009-06-24 09:35:20 -0400 (Wed, 24 Jun 2009)
New Revision: 14714
Modified:
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/outputPanel.xml
Log:
RF-7412: a4j:outputPanel component description review
Modified:
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/outputPanel.xml
===================================================================
---
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/outputPanel.xml 2009-06-24
11:58:11 UTC (rev 14713)
+++
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/outputPanel.xml 2009-06-24
13:35:20 UTC (rev 14714)
@@ -40,125 +40,107 @@
</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>
+ <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;
+
+ <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><a4j:outputPanel></property>
- </emphasis> allows marking of a page area, which is updated on Ajax response.
Anyway,
- <emphasis role="bold">
- <property><a4j:outputPanel></property>
- </emphasis> usage is optional, as in RichFaces it'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><a4j:outputPanel></property>
- </emphasis> usage is recommended for wrapping components that aren't
rendered
- during the primary non-ajax response, as the components don't present in a
- component tree. </para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[<a4j:support ...
reRender="mypanel"/>
+ </section>
+
+ <section>
+ <title>Details of usage</title>
+ <para>
+ The <emphasis
role="bold"><property><a4j:outputPanel></property></emphasis>
component is used when one or more components should be always updated.
+ The component job is similar to that the
<emphasis><property>"reRender"</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'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>
+ <h:panelGrid rendered="#{not empty foo.bar}">
+ ...
+ </h:panelGrid>
</a4j:outputPanel>]]></programlisting>
- <para> In addition to the areas directly indicated in <emphasis>
- <property>"reRender"</property>
- </emphasis> attribute of Ajax components, <emphasis
role="bold">
- <property><a4j:outputPanel></property>
- </emphasis> allows to update a part of a page basing on its own flag. The flag
is
- defined by the <emphasis>
- <property>"ajaxRendered"</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><a4j:outputPanel></property>
- </emphasis> is output as a pair of opening and closing html <emphasis
role="bold">
- <property><span></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>"inline" (default)</para>
- </listitem>
- <listitem>
- <para>"block"</para>
- </listitem>
- <listitem>
- <para>"none"</para>
- </listitem>
- </itemizedlist>
- <para> If <code>layout="block"</code> is chosen,
the component is rendered
- as a pair of opening and closing <emphasis role="bold">
- <property><div></property>
- </emphasis> tag, to which it's possible to apply any available style
attributes
- available for block tags. </para>
- <para>
- <code>layout ="none"</code> helps to avoid an
unnecessary tag round a
- context that could or couldn't be rendered according to the defined
<emphasis>
- <property>"rendered"</property>
- </emphasis> attribute conditions. If an inner context isn't rendered,
<emphasis
- role="bold">
- <property><a4j:outputPanel></property>
- </emphasis> is rendered as a <emphasis role="bold">
- <property><span></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><a4j:outputPanel></property>
- </emphasis> doesn't present at all in a final code. </para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[<a4j:support ....
reRender="mypanel"/>
-...
+
+ <para>
+ By default the <emphasis
role="bold"><property><a4j:outputPanel></property></emphasis>
is rendered as opening and closing HTML <emphasis
role="bold"><property><span></property></emphasis>
tags and functions as container.
+ With the help of the
<emphasis><property>"layout"</property></emphasis>
attribute this output way could be set to any of three variants:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>"inline" (default)</para>
+ </listitem>
+ <listitem>
+ <para>"block"</para>
+ </listitem>
+ <listitem>
+ <para>"none"</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ If <code>layout="block"</code> is set,
the component is rendered as a pair of opening and closing <emphasis
role="bold"><property><div></property></emphasis>
tags.
+ In this case it is possible to apply available for <emphasis
role="bold"><property><div></property></emphasis>
elements style attributes.
+ <code>layout ="none"</code> helps to
avoid an unnecessary tag around a context that is rendered or not according to the
<emphasis><property>"rendered"</property></emphasis>
attribute value.
+ In case an inner context isn't rendered the <emphasis
role="bold"><property><a4j:outputPanel></property></emphasis>
is rendered in a <emphasis
role="bold"><property><span></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><a4j:outputPanel></property></emphasis>
doesn'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>
+ <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>"reRender "</property>
- </emphasis> attribute refers directly to the updating panelGrid and not to the
framing
- outputPanel, and it's more semantically correct. </para>
+
+ <para>
+ As you see, the code is very similar to the one shown above, but
<emphasis><property>"reRender
"</property></emphasis> attribute refers directly to the updating
panelGrid and not to the framing outputPanel,
+ and it's more semantically correct.
+ </para>
+
+ <para>
+ The <emphasis
role="bold"><property><a4j:outputPanel></property></emphasis>
allows to update a part of a page basing on its own flag.
+ The flag is defined by the
<emphasis><property>"ajaxRendered"</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>
- <emphasis role="bold">
- <property><a4j:outPanel></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>
+ The <emphasis
role="bold"><property><a4j:outPanel></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'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
@@ -191,21 +173,23 @@
</section>
<section>
<title>Relevant resources links</title>
- <para>On
- <ulink
- url="http://livedemo.exadel.com/richfaces-demo/richfaces/outputPanel...
- > RichFaces Live Demo page </ulink> you can see the example of <emphasis
role="bold">
- <property><a4j:outputPanel></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&op=viewtopic&...
- > Ajax4JSF Users Forum </ulink>
- </para>
- <para> See how the <emphasis role="bold">
- <property><a4j:outputPanel></property>
- </emphasis> component can be used in the <ulink
- url="http://www.jboss.org/auth/wiki//RichFacesCookbook/FormOldNew&qu...
Input form with detection of Old/New
- Values</ulink> example in the RichFaces cookbook.
- </para>
+ <para>
+ Vizit <ulink
url="http://livedemo.exadel.com/richfaces-demo/richfaces/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&op=viewforum&...
Users Forum</ulink> for some additional information on component usage;
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+
+
</section>
</chapter>