[richfaces-svn-commits] JBoss Rich Faces SVN: r14714 - branches/community/3.3.X/docs/userguide/en/src/main/docbook/included.
richfaces-svn-commits at lists.jboss.org
richfaces-svn-commits at lists.jboss.org
Wed Jun 24 09:35:21 EDT 2009
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.jsf?c=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&p=4052203#4052203"
- > 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">Ajax 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.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&op=viewforum&f=26">RichFaces Users Forum</ulink> for some additional information on component usage;
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+
+
</section>
</chapter>
More information about the richfaces-svn-commits
mailing list