Author: SeanRogers
Date: 2011-03-24 23:29:04 -0400 (Thu, 24 Mar 2011)
New Revision: 22304
Added:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Panels.xml
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jstatus-Updating_a_referenced_a4jstatus_component.xml_sample
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values-0.xml_sample
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values-1.xml_sample
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-a4jlog-a4jlog_example.png
Removed:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Panels_and_containers.xml
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jstatus-Updating_a_common_a4jstatus_component.xml_sample
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values.xml_sample
Modified:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/Component_Reference.xml
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Introduction.xml
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Processing_management.xml
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jlog-a4jlog_example.xml_sample
Log:
Updates and revisions from engineering review RFPL-1380
Modified:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/Component_Reference.xml
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/Component_Reference.xml 2011-03-24
18:55:40 UTC (rev 22303)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/Component_Reference.xml 2011-03-25
03:29:04 UTC (rev 22304)
@@ -21,7 +21,7 @@
<part id="part-Component_Reference-User_interface_components">
<title>User interface components</title>
<xi:include href="chap-Component_Reference-Rich_inputs.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="chap-Component_Reference-Panels_and_containers.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="chap-Component_Reference-Panels.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="chap-Component_Reference-Tables_and_grids.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="chap-Component_Reference-Trees.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="chap-Component_Reference-Menus_and_toolbars.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
Modified:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Introduction.xml
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Introduction.xml 2011-03-24
18:55:40 UTC (rev 22303)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Introduction.xml 2011-03-25
03:29:04 UTC (rev 22304)
@@ -9,6 +9,9 @@
<para>
For full in-depth references for all component classes and properties, refer to the
<citetitle>API Reference</citetitle>, <citetitle>JS
Documentation</citetitle>, and <citetitle>VDL Documentation</citetitle>
available from the RichFaces website.
</para>
+ <para>
+ For further examples for each component, refer to the <citetitle>RichFaces
Showcase</citetitle> at <ulink
url="http://richfaces-showcase.appspot.com/">http://richface...;.
+ </para>
<section id="sect-Component_Reference-Introduction-Libraries">
<title>Libraries</title>
<para>
Copied:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Panels.xml
(from rev 22292,
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Panels_and_containers.xml)
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Panels.xml
(rev 0)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Panels.xml 2011-03-25
03:29:04 UTC (rev 22304)
@@ -0,0 +1,1327 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter id="chap-Component_Reference-Panels">
+ <title>Panels</title>
+ <para>
+ This chapter details those components which act as panels and containers to hold groups
of other components.
+ </para>
+
+ <!--<rich:panel>-->
+ <section id="sect-Component_Reference-Panels-richpanel">
+ <title><sgmltag><rich:panel></sgmltag></title>
+ <para>
+ The <sgmltag><rich:panel></sgmltag> component is a bordered
panel with an optional header.
+ </para>
+ <figure id="figu-Component_Reference-richpanel-richpanel">
+ <title><sgmltag><rich:panel></sgmltag></title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/figu-Component_Reference-richpanel-richpanel.png"
format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A <sgmltag><rich:Panel></sgmltag> component displaying
details on a camera model.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <section id="sect-Component_Reference-richpanel-Basic_usage">
+ <title>Basic usage</title>
+ <para>
+ No attributes need to be listed for basic usage. a
<sgmltag><rich:panel></sgmltag> without any attributes defined
renders a bordered region with no header.
+ </para>
+ </section>
+ <section id="sect-Component_Reference-richpanel-Adding_a_header">
+ <title>Adding a header</title>
+ <para>
+ To add a header to the panel, use the <varname>header</varname> attribute
to specify the text to appear in the header. Alternatively the header can be constructed
using a header facet. <xref
linkend="exam-Component_Reference-richpanel-Adding_a_header" /> demonstrates
the two different approaches.
+ </para>
+ <example id="exam-Component_Reference-richpanel-Adding_a_header">
+ <title>Adding a header</title>
+ <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richpanel-Adding_a_header-0.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richpanel-Adding_a_header-1.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ Both the examples render an identical panel.
+ </para>
+ <blockquote>
+ <figure id="figu-Component_Reference-richpanel-Adding_a_header">
+ <title>Adding a header</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/figu-Component_Reference-richpanel-Adding_a_header.png"
format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A panel with a header that reads <phrase>"This is the panel
header"</phrase> and content that reads <phrase>"This is the panel
content"</phrase>.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </blockquote>
+ </example>
+ </section>
+
+ <section id="sect-Component_Reference-richpanel-Reference_data">
+ <title>Reference data</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>component-type</parameter>:
<classname>org.richfaces.panel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlPanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-family</parameter>:
<classname>org.richfaces.panel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>renderer-type</parameter>:
<classname>org.richfaces.panelRenderer</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.panelTag</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section
id="sect-Component_Reference-richpanel-Style_classes_and_skin_parameters">
+ <title>Style classes and skin parameters</title>
+ <xi:include href="skinning/tabl-richpanel.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </section>
+ </section>
+
+ <!--<rich:accordion>-->
+ <section id="sect-Component_Reference-Panels-richaccordion">
+ <title><sgmltag><rich:accordion></sgmltag></title>
+ <para>
+ The <sgmltag><rich:accordion></sgmltag> is a series of
panels stacked on top of each other, each collapsed such that only the header of the panel
is showing. When the header of a panel is clicked, it is expanded to show the content of
the panel. Clicking on a different header will collapse the previous panel and epand the
selected one. Each panel contained in a
<sgmltag><rich:accordion></sgmltag> component is a
<sgmltag><rich:accordionItem></sgmltag> component.
+ </para>
+ <figure id="figu-Component_Reference-richaccordion-richaccordion">
+ <title>A <sgmltag><rich:accordion></sgmltag> component
containing three <sgmltag><rich:accordionItem></sgmltag>
components</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/figu-Component_Reference-richaccordion-richaccordion.png"
format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A <sgmltag><rich:accordion></sgmltag> component
containing three <sgmltag><rich:accordionItem></sgmltag>
components. Only the first panel is expanded.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ <section id="sect-Component_Reference-richaccordion-Basic_usage">
+ <title>Basic usage</title>
+ <para>
+ The <sgmltag><rich:accordion></sgmltag> component requires
no attributes for basic usage. The component can contain any number of
<sgmltag><rich:accordionItem></sgmltag> components as children.
The headers of the <sgmltag><rich:accordionItem></sgmltag>
components control the expanding and collapsing when clicked. Only a single
<sgmltag><rich:accordionItem></sgmltag> can be displayed at a
time. Refer to <xref
linkend="sect-Component_Reference-Panels-richaccordionItem" /> for details on
the <sgmltag><rich:accordionItem></sgmltag> component.
+ </para>
+ </section>
+
+ <section id="sect-Component_Reference-richaccordion-Switching_panels">
+ <title>Switching panels</title>
+ <para>
+ The switching mode for performing submissions is determined by the
<code>switchType</code> attribute, which can have one of the following three
values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>server</literal></term>
+ <listitem>
+ <para>
+ The default setting. Activation of a
<sgmltag><rich:accordionItem></sgmltag> component causes the
parent <sgmltag><rich:accordion></sgmltag> component to perform
a common submission, completely re-rendering the page. Only one panel at a time is
uploaded to the client side.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ajax</literal></term>
+ <listitem>
+ <para>
+ Activation of a <sgmltag><rich:accordionItem></sgmltag>
component causes the parent <sgmltag><rich:accordion></sgmltag>
component to perform an Ajax form submission, and the content of the panel is rendered.
Only one panel at a time is uploaded to the client side.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>client</literal></term>
+ <listitem>
+ <para>
+ Activation of a <sgmltag><rich:accordionItem></sgmltag>
component causes the parent <sgmltag><rich:accordion></sgmltag>
component to update on the client side. JavaScript changes the styles such that one panel
component becomes hidden while the other is shown.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <!-- TODO
+ <section
id="sect-Component_Reference-richaccordion-Controlling_panel_size">
+ <title>Controlling panel size</title>
+ <para>
+ Unlike the <sgmltag><rich:panel></sgmltag> component, the
size of the <sgmltag><rich:accordion></sgmltag> can be specified
using <varname>width</varname> and <varname>height</varname>
attributes. If unspecified, these values default to 100%.
+ </para>
+ </section>
+ -->
+
+ <section
id="sect-Component_Reference-richaccordion-richaccordion_client-side_events">
+ <title><sgmltag><rich:accordion></sgmltag> client-side
events</title>
+ <para>
+ In addition to the standard Ajax events and HTML events, the
<sgmltag><rich:accordion></sgmltag> component uses the
client-side events common to all switchable panels:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <varname>itemchange</varname> event points to the function to
perform when the switchable item is changed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <varname>beforeitemchange</varname> event points to the function to
perform when before the switchable item is changed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section
id="sect-Component_Reference-richaccordion-richaccordion_server-side_events">
+ <title><sgmltag><rich:accordion></sgmltag> server-side
events</title>
+ <para>
+ The <sgmltag><rich:accordion></sgmltag> component uses the
server-side events common to all switchable panels:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <varname>ItemChangeEvent</varname> event occurs on the server side
when an item is changed through Ajax using the <literal>server</literal> mode.
It can be processed using the <varname>ItemChangeListener</varname>
attribute.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="sect-Component_Reference-richaccordion-JavaScript_API">
+ <title>JavaScript API</title>
+ <para>
+ The <sgmltag><rich:accordion></sgmltag> component can
be controlled through the JavaScript API. The JavaScript API provides the following
functions, which are common to all switchable panels:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><function>getItems()</function></term>
+ <listitem>
+ <para>
+ Return an array of the items contained in the accordion control.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>getItemsNames()</function></term>
+ <listitem>
+ <para>
+ Return an array of the names of the items contained in the accordion
control.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+
<term><function>switchToItem(itemName)</function></term>
+ <listitem>
+ <para>
+ Switch to and display the item identified by the
<parameter>itemName</parameter> string passed as a parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="sect-Component_Reference-richaccordion-Reference_data">
+ <title>Reference data</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>component-type</parameter>:
<classname>org.richfaces.accordion</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlAccordion</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-family</parameter>:
<classname>org.richfaces.accordion</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>renderer-type</parameter>:
<classname>org.richfaces.accordionRenderer</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.accordionTag</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section
id="sect-Component_Reference-richaccordion-Style_classes_and_skin_parameters">
+ <title>Style classes and skin parameters</title>
+ <xi:include href="skinning/tabl-richaccordion.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </section>
+
+ <!--<rich:accordionItem>-->
+ <section id="sect-Component_Reference-Panels-richaccordionItem">
+ <title><sgmltag><rich:accordionItem></sgmltag></title>
+ <para>
+ The <sgmltag><rich:accordionItem></sgmltag> component is a
panel for use with the <sgmltag><rich:accordion></sgmltag>
component.
+ </para>
+
+ <section id="sect-Component_Reference-richaccordionItem-Basic_usage">
+ <title>Basic usage</title>
+ <para>
+ Basic usage of the <sgmltag><rich:accordionItem></sgmltag>
component requires the <varname>label</varname> attribute, which provides the
text on the panel header. The panel header is all that is visible when the accordion item
is collapsed.
+ </para>
+ <para>
+ Alternatively the <literal>header</literal> facet could be used in place
of the <varname>label</varname> attribute. This would allow for additional
styles and custom content to be applied to the tab.
+ </para>
+ </section>
+
+ <section
id="sect-Component_Reference-richaccordionItem-richaccordionItem_client-side_events">
+ <title><sgmltag><rich:accordionItem></sgmltag>
client-side events</title>
+ <para>
+ In addition to the standard HTML events, the
<sgmltag><rich:accordionItem></sgmltag> component uses the
client-side events common to all switchable panel items:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <varname>enter</varname> event points to the function to perform
when the mouse enters the panel.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <varname>leave</varname> event points to the function to perform
when the mouse leaves the panel.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section
id="sect-Component_Reference-richaccordionItem-Reference_data">
+ <title>Reference data</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>component-type</parameter>:
<classname>org.richfaces.accordionItem</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlAccordionItem</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-family</parameter>:
<classname>org.richfaces.accordionItem</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>renderer-type</parameter>:
<classname>org.richfaces.accordionItemRenderer</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.accordionItemTag</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ </section>
+
+ <!--<rich:collapsiblePanel>-->
+ <section id="sect-Component_Reference-Panels-richcollapsiblePanel">
+ <title><sgmltag><rich:collapsiblePanel></sgmltag></title>
+ <para>
+ The <sgmltag><rich:collapsiblePanel></sgmltag> component is
a collapsible panel that shows or hides content when the header bar is activated. It is a
simplified version of <sgmltag><rich:togglePanel></sgmltag>
component.
+ </para>
+ <figure
id="figu-Component_Reference-richcollapsiblePanel-richcollapsiblePanel">
+ <title><sgmltag><rich:collapsiblePanel></sgmltag></title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/figu-Component_Reference-richcollapsiblePanel-richcollapsiblePanel.png"
format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A <sgmltag><rich:collapsiblePanel></sgmltag> component
displaying details on a camera model.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ <section
id="sect-Component_Reference-richcollapsiblePanel-Basic_usage">
+ <title>Basic usage</title>
+ <para>
+ Basic usage requires the <varname>header</varname> attribute to be
specified, which provides the title for the header element. Additionally the panel
requires content to display when it is expanded. Content is added as child elements like a
standard panel.
+ </para>
+ </section>
+
+ <section
id="sect-Component_Reference-richcollapsiblePanel-Expanding_and_collapsing_the_panel">
+ <title>Expanding and collapsing the panel</title>
+ <!-- TODO not in M3 -->
+ <!--
+ <para>
+ If the <sgmltag><rich:collapsiblePanel></sgmltag> component
uses <code><varname>expanded</varname>="true"</code>,
the panel is open and expanded, otherwise it is closed and collapsed.
+ </para>
+ <para>
+ The <varname>toggleElement</varname> attribute is used to specify which
user interface element triggers the expansion when clicked. It can have one of the
following values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>header</literal></term>
+ <listitem>
+ <para>
+ This is the default setting. Clicking anywhere on the header of the panel will
cause it to expand or collapse.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>panel</literal></term>
+ <listitem>
+ <para>
+ Clicking anywhere on the entire panel will cause it to expand or collapse.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>control</literal></term>
+ <listitem>
+ <para>
+ The panel can only be expanded or collapsed by clicking on the control in the
right-hand side of the header.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ -->
+ <para>
+ The switching mode for performing submissions is determined by the
<varname>switchType</varname> attribute, which can have one of the following
three values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>server</literal></term>
+ <listitem>
+ <para>
+ This is the default setting. The
<sgmltag><rich:collapsiblePanel></sgmltag> component performs a
common submission, completely re-rendering the page. Only one panel at a time is uploaded
to the client side.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ajax</literal></term>
+ <listitem>
+ <para>
+ The <sgmltag><rich:collapsiblePanel></sgmltag> component
performs an Ajax form submission, and only the content of the panel is rendered. Only one
panel at a time is uploaded to the client side.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>client</literal></term>
+ <listitem>
+ <para>
+ The <sgmltag><rich:collapsiblePanel></sgmltag> component
updates on the client side, re-rendering itself and any additional components listed with
the <varname>render</varname> attribute.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section
id="sect-Component_Reference-richcollapsiblePanel-Appearance">
+ <title>Appearance</title>
+ <para>
+ The appearance of the
<sgmltag><rich:collapsiblePanel></sgmltag> component can be
customized using facets. The <literal>headerExpandedClass</literal> and
<literal>headerCollapsedClass</literal> facets are used to style the
appearance of the panel when it is expanded and collapsed respectively. The
<literal>expandControl</literal> facet styles the control in the panel header
used for expanding, and the <literal>collapseControl</literal> facet styles
the control for collapsing.
+ </para>
+ </section>
+
+ <section
id="sect-Component_Reference-richcollapsiblePanel-richcollapsiblePanel_server-side_events">
+ <title><sgmltag><rich:collapsiblePanel></sgmltag>
server-side events</title>
+ <para>
+ The <sgmltag><rich:collapsiblePanel></sgmltag> component
uses the following unique server-side events:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <varname>ChangeExpandEvent</varname> event occurs on the server
side when the <sgmltag><rich:collapsiblePanel></sgmltag>
component is expanded or collapsed through Ajax using the
<literal>server</literal> mode. It can be processed using the
<varname>ChangeExpandListener</varname> attribute.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section
id="sect-Component_Reference-richcollapsiblePanel-JavaScript_API">
+ <title>JavaScript API</title>
+ <para>
+ The <sgmltag><rich:collapsiblePanel></sgmltag>
component can be controlled through the JavaScript API. The JavaScript API provides the
following functions:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><function>switchPanel()</function></term>
+ <listitem>
+ <para>
+ Switch the state of the collapsible panel (expanded or collapsed).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section
id="sect-Component_Reference-richcollapsiblePanel-Reference_data">
+ <title>Reference data</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>component-type</parameter>:
<classname>org.richfaces.collapsiblePanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlcollapsiblePanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-family</parameter>:
<classname>org.richfaces.collapsiblePanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>renderer-type</parameter>:
<classname>org.richfaces.collapsiblePanelRenderer</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.collapsiblePanelTag</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section
id="sect-Component_Reference-richcollapsiblePanel-Style_classes_and_skin_parameters">
+ <title>Style classes and skin parameters</title>
+ <xi:include href="skinning/tabl-richcollapsiblePanel.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </section>
+
+ </section>
+
+ <!--<rich:popupPanel>-->
+ <section id="sect-Component_Reference-Panels-richpopupPanel">
+ <title><sgmltag><rich:popupPanel></sgmltag></title>
+ <para>
+ The <sgmltag><rich:popupPanel></sgmltag> component provides
a pop-up panel or window that appears in front of the rest of the application. The
<sgmltag><rich:popupPanel></sgmltag> component functions either
as a modal window which blocks interaction with the rest of the application while active,
or as a non-modal window. It can be positioned on the screen, dragged to a new position by
the user, and re-sized.
+ </para>
+
+ <section id="sect-Component_Reference-richpopupPanel-Basic_usage">
+ <title>Basic usage</title>
+ <para>
+ The <sgmltag><rich:popupPanel></sgmltag> does not require
any compulsory attributes, though certain use cases require different attributes.
+ </para>
+ </section>
+
+ <section
id="sect-Component_Reference-richpopupPanel-Showing_and_hiding_the_pop-up">
+ <title>Showing and hiding the pop-up</title>
+ <para>
+ If <code>show="true"</code> then the pop-up panel will display
when the page is first loaded.
+ </para>
+ <para>
+ The <sgmltag><rich:popupPanel></sgmltag> component can be
shown and hidden manually using the <code>show()</code> and
<code>hide()</code> methods from the JavaScript API. These can be implemented
using two different approaches:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Using the <sgmltag><rich:componentControl></sgmltag>
component. For details on the component, refer to <xref
linkend="sect-Component_Reference-Actions-richcomponentControl" />.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Using the <code>rich:component</code> function. For details on the
function, refer to <xref
linkend="sect-Component_Reference-Functions-richcomponent" />.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ For explicit referencing when using the functions, the component can be given an
<varname>id</varname> identifier. The component can, however, be referenced
using other means, such as through a selector.
+ </para>
+ <para>
+ <xref
linkend="exam-Component_Reference-richpopupPanel-richpopupPanel_example" />
demonstrates basic use of both the
<sgmltag><rich:componentControl></sgmltag> component and the
<code>rich:component</code> function to show and hide the
<sgmltag><rich:popupPanel></sgmltag> component.
+ </para>
+ <example
id="exam-Component_Reference-richpopupPanel-richpopupPanel_example">
+ <title><sgmltag><rich:popupPanel></sgmltag>
example</title>
+ <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richpopupPanel-richpopupPanel_example.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ <important>
+ <title>Placement</title>
+ <para>
+ The <sgmltag><rich:popupPanel></sgmltag> component should
usually be placed outside the original form, and include its own form if performing
submissions. An exception to this is when using the
<varname>domElementAttachment</varname> attribute, as described in <xref
linkend="sect-Component_Reference-richpopupPanel-Size_and_positioning" />.
+ </para>
+ </important>
+ </section>
+
+ <section
id="sect-Component_Reference-richpopupPanel-Modal_and_non-modal_panels">
+ <title>Modal and non-modal panels</title>
+ <para>
+ By default, the <sgmltag><rich:popupPanel></sgmltag>
appears as a modal window that blocks interaction with the other objects on the page. To
implement a non-modal window instead, set
<code><varname>modal</varname>="false"</code>. This will
allow interaction with other objects outside the pop-up panel.
+ </para>
+ </section>
+
+ <section
id="sect-Component_Reference-richpopupPanel-Size_and_positioning">
+ <title>Size and positioning</title>
+ <para>
+ The pop-up panel can be both re-sized and re-positioned by the user. The minimum
possible size for the panel can be set with the <varname>minWith</varname> and
<varname>minHeight</varname> attributes. These abilities can be deactivated by
setting <code>resizable</code> or <code>movable</code> to
<literal>false</literal> as necessary.
+ <!--
+ The state of the modal panel, including size and position on screen, can be
maintained and restored after submitting and reloading by setting
<code>keepVisualState="true"</code>.
+ -->
+ </para>
+ <para>
+ The pop-up panel can be automatically sized when it is shown if the
<varname>autosized</varname> attribute is set to
<literal>true</literal>.
+ </para>
+ <para>
+ The <sgmltag><rich:popupPanel></sgmltag> component is
usually rendered in front of any other objects on the page. This is achieved by attaching
the component to the <sgmltag><body></sgmltag> element of the
page, and setting a very high <emphasis>"z-index"</emphasis> (the
stack order of the object). This approach is taken because relatively-positioned elements
could still overlap the pop-up panel if they exist at higher levels of the
<acronym>DOM</acronym> hierarchy, even if their z-index is less than the
<sgmltag><rich:popupPanel></sgmltag> component. However, to
avoid form limitation of the pop-up panel on pages where no such elements exist, the
<sgmltag><rich:popupPanel></sgmltag> component can be reattached
to its original <acronym>DOM</acronym> element by setting
<varname>domElementAttachment</varname> to either
<literal>parent</literal> or <literal>form</literal>.
+ </para>
+ <para>
+ Embedded objects inserted into the <acronym>HTML</acronym> with the
<sgmltag><embed></sgmltag> tag will typically be rendered in
front of a <sgmltag><rich:popupPanel></sgmltag> component. The
<sgmltag><rich:popupPanel></sgmltag> component can be forcibly
rendered in front of these objects by setting
<code><varname>overlapEmbedObjects</varname>="true"</code>.
+ </para>
+ <note>
+ <title>Using <varname>overlapEmbedObjects</varname></title>
+ <para>
+ Due to the additional script processing required when using the
<varname>overlapEmbedObjects</varname> attribute, applications can suffer from
decreased performance. As such, <varname>overlapEmbedObjects</varname> should
only be set to <literal>true</literal> when
<sgmltag><embed></sgmltag> tags are being used. Do not set it to
<literal>true</literal> for applications that do not require it.
+ </para>
+ </note>
+ </section>
+
+ <section
id="sect-Component_Reference-richpopupPanel-Contents_of_the_pop-up">
+ <title>Contents of the pop-up</title>
+ <para>
+ The <sgmltag><rich:popupPanel></sgmltag> component can
contain any other rich component just like a normal panel.
+ </para>
+ <para>
+ Contents of the <sgmltag><rich:popupPanel></sgmltag>
component which are positioned relatively may be trimmed if they extend beyond the borders
of the pop-up panel. For certain in-line controls this behavior may be preferable, but for
other dynamic controls it could be undesirable. If the
<varname>trimOverlayedElements</varname> attribute is set to
<literal>false</literal> then child components will not be trimmed if they
extend beyond the borders of the pop-up panel.
+ </para>
+ </section>
+
+ <section
id="sect-Component_Reference-richpopupPanel-Header_and_controls">
+ <title>Header and controls</title>
+ <para>
+ A panel header and associated controls can be added to the
<sgmltag><rich:popupPanel></sgmltag> component through the use
of facets. The <literal>header</literal> facet displays a title for the panel,
and the <literal>controls</literal> facet can be customized to allow window
controls such as a button for closing the pop-up. <xref
linkend="exam-Component_Reference-richpopupPanel-Header_and_controls" />
demonstrates the use of the facets.
+ </para>
+ <example
id="exam-Component_Reference-richpopupPanel-Header_and_controls">
+ <title>Header and controls</title>
+ <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richpopupPanel-Header_and_controls.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <blockquote>
+ <figure
id="figu-Component_Reference-richpopupPanel-Header_and_controls">
+ <title>Header and controls</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/figu-Component_Reference-richpopupPanel-Header_and_controls.png"
format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ The <sgmltag><rich:popupPanel></sgmltag> component,
rendered with a title header and a button control for closing the pop-up.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </blockquote>
+ </example>
+ </section>
+
+ <section id="sect-Component_Reference-richpopupPanel-JavaScript_API">
+ <title>JavaScript API</title>
+ <para>
+ The <sgmltag><rich:popupPanel></sgmltag> component can
be controlled through the JavaScript API. The JavaScript API provides the following
functions:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><function>getTop()</function></term>
+ <listitem>
+ <para>
+ Return the top co-ordinate for the position of the pop-up panel.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>getLeft()</function></term>
+ <listitem>
+ <para>
+ Return the left co-ordinate for the position of the pop-up panel.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>moveTo(top,left)</function></term>
+ <listitem>
+ <para>
+ Move the pop-up panel to the co-ordinates specified with the
<parameter>top</parameter> and <parameter>left</parameter>
parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+
<term><function>resize(width,height)</function></term>
+ <listitem>
+ <para>
+ Resize the pop-up panel to the size specified with the
<parameter>width</parameter> and <parameter>height</parameter>
parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>show()</function></term>
+ <listitem>
+ <para>
+ Show the pop-up panel.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>hide()</function></term>
+ <listitem>
+ <para>
+ Hide the pop-up panel.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="sect-Component_Reference-richpopupPanel-Reference_data">
+ <title>Reference data</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>component-type</parameter>:
<classname>org.richfaces.popupPanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlpopupPanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-family</parameter>:
<classname>org.richfaces.popupPanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>renderer-type</parameter>:
<classname>org.richfaces.popupPanelRenderer</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.popupPanelTag</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section
id="sect-Component_Reference-richpopupPanel-Style_classes_and_skin_parameters">
+ <title>Style classes and skin parameters</title>
+ <xi:include href="skinning/tabl-richpopupPanel.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </section>
+ </section>
+
+ <!--<rich:tabPanel>-->
+ <section id="sect-Component_Reference-Panels-richtabPanel">
+ <title><sgmltag><rich:tabPanel></sgmltag></title>
+ <para>
+ The <sgmltag><rich:tabPanel></sgmltag> component provides a
set of tabbed panels for displaying one panel of content at a time. The tabs can be highly
customized and themed. Each tab within a
<sgmltag><rich:tabPanel></sgmltag> container is a
<sgmltag><rich:tab></sgmltag> component. Refer to <xref
linkend="sect-Component_Reference-Panels-richtab" /> for further details on
the <sgmltag><rich:tab></sgmltag> component.
+ </para>
+ <figure
id="figu-Component_Reference-richtabPanel-richtabPanel_component">
+ <title>A <sgmltag><rich:tabPanel></sgmltag> component
containing three <sgmltag><rich:tab></sgmltag>
components</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/figu-Component_Reference-richtabPanel-richtabPanel_component.png"
format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A <sgmltag><rich:tabPanel></sgmltag> component containing
three <sgmltag><rich:tab></sgmltag> components.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <note>
+ <title>Form elements required</title>
+ <para>
+ All <sgmltag><rich:tabPanel></sgmltag> components should be
wrapped in a form element so that the contents of the tab are processed correctly during a
tab change in either <literal>ajax</literal> or
<literal>server</literal> mode.
+ </para>
+ <para>
+ Alternatively, the contents of a
<sgmltag><rich:tab></sgmltag> component within the
<sgmltag><rich:tabPanel></sgmltag> component could be wrapped in
a form element, such that they will be processed using the inner submitting component
only. In this case, the <sgmltag><rich:tabPanel></sgmltag>
component will automatically add form tags around the tab's contents, and the contents
will not be processed during switching.
+ </para>
+ </note>
+
+ <section id="sect-Component_Reference-richtabPanel-Switching_tabs">
+ <title>Switching panels</title>
+ <para>
+ The <code>activeItem</code> attribute holds the active tab name. This
name is a reference to the <varname>name</varname> identifier of the active
child <sgmltag><rich:tab></sgmltag> component.
+ </para>
+ <para>
+ The switching mode for performing submissions is determined by the
<code>switchType</code> attribute, which can have one of the following three
values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>server</literal></term>
+ <listitem>
+ <para>
+ The default setting. Activation of a
<sgmltag><rich:tab></sgmltag> component causes the parent
<sgmltag><rich:tabPanel></sgmltag> component to perform a common
submission, completely re-rendering the page. Only one tab at a time is uploaded to the
client side.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ajax</literal></term>
+ <listitem>
+ <para>
+ Activation of a <sgmltag><rich:tab></sgmltag> component
causes the parent <sgmltag><rich:tabPanel></sgmltag> component
to perform an Ajax form submission, and the content of the tab is rendered. Only one tab
at a time is uploaded to the client side.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>client</literal></term>
+ <listitem>
+ <para>
+ Activation of a <sgmltag><rich:tab></sgmltag> component
causes the parent <sgmltag><rich:tabPanel></sgmltag> component
to update on the client side. JavaScript changes the styles such that one tab becomes
hidden while the other is shown.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <!-- FIXME details on name attribute -->
+
+ <!-- TODO not in M3 -->
+ <!--
+ <section
id="sect-Component_Reference-richtabPanel-Tab_position_and_alignment">
+ <title>Tab position and alignment</title>
+ <para>
+ The tab headers, used for switching between the tabs, can be positioned along any
edge of the panel by using the <varname>headerPosition</varname> attribute.
The possible values for the <varname>headerPosition</varname> attribute are as
follows:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>top</literal></term>
+ <listitem>
+ <para>
+ The tab headers are positioned along the top of the panel. This is the default
position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>left</literal></term>
+ <listitem>
+ <para>
+ The tab headers are positioned along the left edge of the panel.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>right</literal></term>
+ <listitem>
+ <para>
+ The tab headers are positioned along the right edge of the panel.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>bottom</literal></term>
+ <listitem>
+ <para>
+ The tab headers are positioned along the bottom of the panel.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The tab headers themselves can be aligned using the
<code>headerAlignment</code> attribute. The possible values for the
<varname>headerAlignment</varname> attribute are as follows:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>top</literal></term>
+ <listitem>
+ <para>
+ The tab headers are aligned to the top of the tab header position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>left</literal></term>
+ <listitem>
+ <para>
+ The tab headers are aligned to the left of the tab header position. This is the
default alignment.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>right</literal></term>
+ <listitem>
+ <para>
+ The tab headers are aligned to the right of the tab header position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>bottom</literal></term>
+ <listitem>
+ <para>
+ The tab headers are aligned to the bottom of the tab header position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>center</literal></term>
+ <listitem>
+ <para>
+ The tab headers are aligned in the center of the tab header position.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ -->
+
+ <section
id="sect-Component_Reference-richtabPanel-richtabPanel_client-side_events">
+ <title><sgmltag><rich:tabPanel></sgmltag> client-side
events</title>
+ <para>
+ In addition to the standard Ajax events and HTML events, the
<sgmltag><rich:tabPanel></sgmltag> component uses the
client-side events common to all switchable panels:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <varname>itemchange</varname> event points to the function to
perform when the switchable item is changed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <varname>beforeitemchange</varname> event points to the function to
perform when before the switchable item is changed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section
id="sect-Component_Reference-richtabPanel-richtabPanel_server-side_events">
+ <title><sgmltag><rich:tabPanel></sgmltag> server-side
events</title>
+ <para>
+ The <sgmltag><rich:tabPanel></sgmltag> component uses the
server-side events common to all switchable panels:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <varname>ItemChangeEvent</varname> event occurs on the server side
when an item is changed through Ajax using the <literal>server</literal> mode.
It can be processed using the <varname>ItemChangeListener</varname>
attribute.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="sect-Component_Reference-richtabPanel-JavaScript_API">
+ <title>JavaScript API</title>
+ <para>
+ The <sgmltag><rich:tabPanel></sgmltag> component can be
controlled through the JavaScript API. The JavaScript API provides the following
functions, which are common to all switchable panels:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><function>getItems()</function></term>
+ <listitem>
+ <para>
+ Return an array of the tabs contained in the tab panel.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>getItemsNames()</function></term>
+ <listitem>
+ <para>
+ Return an array of the names of the tabs contained in the tab panel.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+
<term><function>switchToItem(itemName)</function></term>
+ <listitem>
+ <para>
+ Switch to and display the item identified by the
<parameter>itemName</parameter> string passed as a parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="sect-Component_Reference-richtabPanel-Reference_data">
+ <title>Reference data</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>component-type</parameter>:
<classname>org.richfaces.tabPanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlTabPanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-family</parameter>:
<classname>org.richfaces.tabPanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>renderer-type</parameter>:
<classname>org.richfaces.tabPanelRenderer</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.tabPanelTag</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section
id="sect-Component_Reference-richtabPanel-Style_classes_and_skin_parameters">
+ <title>Style classes and skin parameters</title>
+ <xi:include href="skinning/tabl-richtabPanel.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </section>
+
+ <!--<rich:tab>-->
+ <section id="sect-Component_Reference-Panels-richtab">
+ <title><sgmltag><rich:tab></sgmltag></title>
+ <para>
+ The <sgmltag><rich:tab></sgmltag> component represents an
individual tab inside a <sgmltag><rich:tabPanel></sgmltag>
component, including the tab's content. Clicking on the tab header will bring its
corresponding content to the front of other tabs.
+ </para>
+
+ <section id="sect-Component_Reference-richtab-Basic_usage">
+ <title>Basic usage</title>
+ <para>
+ Basic usage of the <sgmltag><rich:tab></sgmltag> component
requires the <varname>name</varname> attribute to uniquely identify the tab
within the parent <sgmltag><rich:tabPanel></sgmltag> component.
As the tabs are switched, the <varname>name</varname> identifier of the
currently selected tab is stored in the <varname>activeItem</varname>
attribute of the parent <sgmltag><rich:tabPanel></sgmltag>
component.
+ </para>
+ </section>
+
+ <section id="sect-Component_Reference-richtab-Header_labeling">
+ <title>Header labeling</title>
+ <para>
+ In addition to the <varname>name</varname> identifier, the
<varname>header</varname> attribute must be defined. The
<varname>header</varname> attribute provides the text on the tab header. The
content of the tab is then detailed inside the
<sgmltag><rich:tab></sgmltag> tags.
+ </para>
+ <para>
+ Alternatively, the <literal>header</literal> facet could be used in
place of the <varname>header</varname> attribute. This would allow for
additional styles and custom content to be applied to the tab. The component also supports
three facets to customize the appearance depending on the current state of the tab:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>headerActiveClass</literal> facet</term>
+ <listitem>
+ <para>
+ This facet is used when the tab is the currently active tab.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>headerInactiveClass</literal> facet</term>
+ <listitem>
+ <para>
+ This facet is used when the tab is not currently active.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>headerDisabledClass</literal> facet</term>
+ <listitem>
+ <para>
+ This facet is used when the tab is disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The <literal>header</literal> facet is used in place of any state-based
facet that has not been defined.
+ </para>
+ </section>
+
+ <section id="sect-Component_Reference-richtab-Switching_tabs">
+ <title>Switching tabs</title>
+ <para>
+ The switching mode for performing submissions can be inherited from the
<varname>switchType</varname> attribute of the parent
<sgmltag><rich:tabPanel></sgmltag> component, or set
individually for each <sgmltag><rich:tab></sgmltag> component.
Refer to <xref linkend="sect-Component_Reference-Panels-richtabPanel" />
for details on the <varname>switchType</varname> attribute.
+ </para>
+ <para>
+ An individual tab can be disabled by setting
<code><varname>disabled</varname>="true"</code>.
Disabled tabs cannot be activated or switched to.
+ </para>
+ </section>
+
+ <section
id="sect-Component_Reference-richtab-richtab_client-side_events">
+ <title><sgmltag><rich:tab></sgmltag> client-side
events</title>
+ <para>
+ In addition to the standard HTML events, the
<sgmltag><rich:tab></sgmltag> component uses the client-side
events common to all switchable panel items:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <varname>enter</varname> event points to the function to perform
when the mouse enters the tab.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <varname>leave</varname> attribute points to the function to
perform when the mouse leaves the tab.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="sect-Component_Reference-richtab-Reference_data">
+ <title>Reference data</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>component-type</parameter>:
<classname>org.richfaces.tab</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlTab</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-family</parameter>:
<classname>org.richfaces.tab</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>renderer-type</parameter>:
<classname>org.richfaces.tabRenderer</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.tabTag</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ </section>
+
+ <!--<rich:togglePanel>-->
+ <section id="sect-Component_Reference-Panels-richtogglePanel">
+ <title><sgmltag><rich:togglePanel></sgmltag></title>
+ <para>
+ The <sgmltag><rich:togglePanel></sgmltag> component is a
wrapper for multiple <sgmltag><rich:togglePanelItem></sgmltag>
components. Each child component is displayed after being activated with the
<sgmltag><rich:toggleControl></sgmltag> behavior.
+ </para>
+ <para>
+ Refer to <xref
linkend="sect-Component_Reference-Panels-richtoggleControl" /> and <xref
linkend="sect-Component_Reference-Panels-richtogglePanel" /> for details on
how to use the components together.
+ </para>
+ <para>
+ The <sgmltag><rich:togglePanel></sgmltag> component is used
as a base for the other switchable components, the
<sgmltag><rich:accordion></sgmltag> component and the
<sgmltag><rich:tabPanel></sgmltag> component. It provides an
abstract switchable component without any associated markup. As such, the
<sgmltag><rich:togglePanel></sgmltag> component could be
customized to provide a switchable component when neither an accordion component or a tab
panel component is appropriate.
+ </para>
+
+ <section id="sect-Component_Reference-richtogglePanel-Basic_usage">
+ <title>Basic usage</title>
+ <para>
+ The initial state of the component can be configured using the
<varname>activeItem</varname> attribute, which points to a child component to
display. Alternatively, if no <varname>activeItem</varname> attribute is
defined, the initial state will be blank until the user activates a child component using
the <sgmltag><rich:toggleControl></sgmltag> component.
+ </para>
+ <para>
+ The child components are shown in the order in which they are defined in the view.
+ </para>
+ </section>
+
+ <section
id="sect-Component_Reference-richtogglePanel-Toggling_between_panels">
+ <title>Toggling between components</title>
+ <para>
+ The switching mode for performing submissions is determined by the
<code>switchType</code> attribute, which can have one of the following three
values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>server</literal></term>
+ <listitem>
+ <para>
+ The default setting. Activation of a child component causes the parent
<sgmltag><rich:togglePanel></sgmltag> component to perform a
common submission, completely re-rendering the page. Only one child at a time is uploaded
to the client side.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ajax</literal></term>
+ <listitem>
+ <para>
+ Activation of a child component causes the parent
<sgmltag><rich:togglePanel></sgmltag> component to perform an
Ajax form submission, and the content of the child is rendered. Only one child at a time
is uploaded to the client side.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>client</literal></term>
+ <listitem>
+ <para>
+ Activation of a child component causes the parent
<sgmltag><rich:togglePanel></sgmltag> component to update on the
client side. JavaScript changes the styles such that one child component becomes hidden
while the other is shown.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="sect-Component_Reference-richtogglePanel-JavaScript_API">
+ <title>JavaScript API</title>
+ <para>
+ The <sgmltag><rich:togglePanel></sgmltag> component can
be controlled through the JavaScript API. The JavaScript API provides the following
functions, which are common to all switchable panels:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><function>getItems()</function></term>
+ <listitem>
+ <para>
+ Return an array of the items contained in the toggle panel.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>getItemsNames()</function></term>
+ <listitem>
+ <para>
+ Return an array of the names of the items contained in the toggle
panel.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+
<term><function>switchToItem(itemName)</function></term>
+ <listitem>
+ <para>
+ Switch to and display the item identified by the
<parameter>itemName</parameter> string passed as a parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="sect-Component_Reference-richtogglePanel-Reference_data">
+ <title>Reference data</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>component-type</parameter>:
<classname>org.richfaces.TogglePanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlTogglePanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-family</parameter>:
<classname>org.richfaces.TogglePanel</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>renderer-type</parameter>:
<classname>org.richfaces.TogglePanelRenderer</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.TogglePanelTag</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <!--<rich:toggleControl>-->
+ <section id="sect-Component_Reference-Panels-richtoggleControl">
+ <title><sgmltag><rich:toggleControl></sgmltag></title>
+ <para>
+ The <sgmltag><rich:toggleControl></sgmltag> behavior can be
attached to any interface component. It works with a
<sgmltag><rich:togglePanel></sgmltag> component to switch
between different <sgmltag><rich:togglePanelItem></sgmltag>
components.
+ </para>
+ <para>
+ Refer to <xref linkend="sect-Component_Reference-Panels-richtogglePanel"
/> and <xref linkend="sect-Component_Reference-Panels-richtogglePanelItem"
/> for details on how to use the components together.
+ </para>
+
+ <section id="sect-Component_Reference-richtoggleControl-Basic_usage">
+ <title>Basic usage</title>
+ <para>
+ The <sgmltag><rich:toggleControl></sgmltag> can be used to
switch through <sgmltag><rich:togglePanelItem></sgmltag>
components in a <sgmltag><rich:togglePanel></sgmltag> container.
If the <sgmltag><rich:toggleControl></sgmltag> component is
positioned inside a <sgmltag><rich:togglePanel></sgmltag>
component, no attributes need to be defined, as the control is assumed to switch through
the <sgmltag><rich:togglePanelItem></sgmltag> components of its
parent.
+ </para>
+ <para>
+ A <sgmltag><rich:toggleControl></sgmltag> component can be
located outside the <sgmltag><rich:togglePanel></sgmltag>
component it needs to switch. Where this is the case, the
<sgmltag><rich:togglePanel></sgmltag> is identified using the
<varname>activePanel</varname> attribute. the Cycling through components
requires the <varname>for</varname> attribute, which points to the
<varname>id</varname> identifier of the
<sgmltag><rich:togglePanel></sgmltag> that it controls.
+ </para>
+ </section>
+
+ <section
id="sect-Component_Reference-richtoggleControl-Specifying_the_next_state">
+ <title>Specifying the next state</title>
+ <para>
+ The <sgmltag><rich:toggleControl></sgmltag> component will
cycle through <sgmltag><rich:togglePanelItem></sgmltag>
components in the order they are defined within the view. However, the next item to switch
to can be explicitly defined by including a
<sgmltag><rich:toggleControl></sgmltag> component within a
<sgmltag><rich:togglePanelItem></sgmltag> and using the
<varname>targetItem</varname> attribute. The
<varname>targetItem</varname> attribute points to the
<sgmltag><rich:togglePanelItem></sgmltag> to switch to when the
state is next changed. <xref
linkend="exam-Component_Reference-richtoggleControl-richtoggleControl_example"
/> demonstrates how to specify the next switchable state in this way.
+ </para>
+ <example
id="exam-Component_Reference-richtoggleControl-richtoggleControl_example">
+ <title><sgmltag><rich:toggleControl></sgmltag>
example</title>
+ <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richtoggleControl-richtoggleControl_example.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ </section>
+
+ <section
id="sect-Component_Reference-richtoggleControl-Reference_data">
+ <title>Reference data</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>component-type</parameter>:
<classname>org.richfaces.ToggleControl</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlToggleControl</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-family</parameter>:
<classname>org.richfaces.ToggleControl</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>renderer-type</parameter>:
<classname>org.richfaces.ToggleControlRenderer</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.ToggleControlTag</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ <!--<rich:togglePanelItem>-->
+ <section id="sect-Component_Reference-Panels-richtogglePanelItem">
+ <title><sgmltag><rich:togglePanelItem></sgmltag></title>
+ <para>
+ The <sgmltag><rich:togglePanelItem></sgmltag> component is
a switchable panel for use with the
<sgmltag><rich:togglePanel></sgmltag> component. Switching
between <sgmltag><rich:togglePanelItem></sgmltag> components is
handled by the <sgmltag><rich:toggleControl></sgmltag>
behavior.
+ </para>
+
+ <section
id="sect-Component_Reference-richtogglePanelItem-Reference_data">
+ <title>Reference data</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <parameter>component-type</parameter>:
<classname>org.richfaces.TogglePanelItem</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlTogglePanelItem</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>component-family</parameter>:
<classname>org.richfaces.TogglePanelItem</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>renderer-type</parameter>:
<classname>org.richfaces.TogglePanelItemRenderer</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.TogglePanelItemTag</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ </section>
+
+</chapter>
+
Deleted:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Panels_and_containers.xml
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Panels_and_containers.xml 2011-03-24
18:55:40 UTC (rev 22303)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Panels_and_containers.xml 2011-03-25
03:29:04 UTC (rev 22304)
@@ -1,1327 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<chapter id="chap-Component_Reference-Panels_and_containers">
- <title>Panels and containers</title>
- <para>
- This chapter details those components which act as panels and containers to hold groups
of other components.
- </para>
-
- <!--<rich:panel>-->
- <section id="sect-Component_Reference-Panels_and_containers-richpanel">
- <title><sgmltag><rich:panel></sgmltag></title>
- <para>
- The <sgmltag><rich:panel></sgmltag> component is a bordered
panel with an optional header.
- </para>
- <figure id="figu-Component_Reference-richpanel-richpanel">
- <title><sgmltag><rich:panel></sgmltag></title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/figu-Component_Reference-richpanel-richpanel.png"
format="PNG" />
- </imageobject>
- <textobject>
- <para>
- A <sgmltag><rich:Panel></sgmltag> component displaying
details on a camera model.
- </para>
- </textobject>
- </mediaobject>
- </figure>
- <section id="sect-Component_Reference-richpanel-Basic_usage">
- <title>Basic usage</title>
- <para>
- No attributes need to be listed for basic usage. a
<sgmltag><rich:panel></sgmltag> without any attributes defined
renders a bordered region with no header.
- </para>
- </section>
- <section id="sect-Component_Reference-richpanel-Adding_a_header">
- <title>Adding a header</title>
- <para>
- To add a header to the panel, use the <varname>header</varname> attribute
to specify the text to appear in the header. Alternatively the header can be constructed
using a header facet. <xref
linkend="exam-Component_Reference-richpanel-Adding_a_header" /> demonstrates
the two different approaches.
- </para>
- <example id="exam-Component_Reference-richpanel-Adding_a_header">
- <title>Adding a header</title>
- <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richpanel-Adding_a_header-0.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richpanel-Adding_a_header-1.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <para>
- Both the examples render an identical panel.
- </para>
- <blockquote>
- <figure id="figu-Component_Reference-richpanel-Adding_a_header">
- <title>Adding a header</title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/figu-Component_Reference-richpanel-Adding_a_header.png"
format="PNG" />
- </imageobject>
- <textobject>
- <para>
- A panel with a header that reads <phrase>"This is the panel
header"</phrase> and content that reads <phrase>"This is the panel
content"</phrase>.
- </para>
- </textobject>
- </mediaobject>
- </figure>
- </blockquote>
- </example>
- </section>
-
- <section id="sect-Component_Reference-richpanel-Reference_data">
- <title>Reference data</title>
- <itemizedlist>
- <listitem>
- <para>
- <parameter>component-type</parameter>:
<classname>org.richfaces.panel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlPanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-family</parameter>:
<classname>org.richfaces.panel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>renderer-type</parameter>:
<classname>org.richfaces.panelRenderer</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.panelTag</classname>
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section
id="sect-Component_Reference-richpanel-Style_classes_and_skin_parameters">
- <title>Style classes and skin parameters</title>
- <xi:include href="skinning/tabl-richpanel.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- </section>
- </section>
-
- <!--<rich:accordion>-->
- <section
id="sect-Component_Reference-Panels_and_containers-richaccordion">
- <title><sgmltag><rich:accordion></sgmltag></title>
- <para>
- The <sgmltag><rich:accordion></sgmltag> is a series of
panels stacked on top of each other, each collapsed such that only the header of the panel
is showing. When the header of a panel is clicked, it is expanded to show the content of
the panel. Clicking on a different header will collapse the previous panel and epand the
selected one. Each panel contained in a
<sgmltag><rich:accordion></sgmltag> component is a
<sgmltag><rich:accordionItem></sgmltag> component.
- </para>
- <figure id="figu-Component_Reference-richaccordion-richaccordion">
- <title>A <sgmltag><rich:accordion></sgmltag> component
containing three <sgmltag><rich:accordionItem></sgmltag>
components</title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/figu-Component_Reference-richaccordion-richaccordion.png"
format="PNG" />
- </imageobject>
- <textobject>
- <para>
- A <sgmltag><rich:accordion></sgmltag> component
containing three <sgmltag><rich:accordionItem></sgmltag>
components. Only the first panel is expanded.
- </para>
- </textobject>
- </mediaobject>
- </figure>
-
- <section id="sect-Component_Reference-richaccordion-Basic_usage">
- <title>Basic usage</title>
- <para>
- The <sgmltag><rich:accordion></sgmltag> component requires
no attributes for basic usage. The component can contain any number of
<sgmltag><rich:accordionItem></sgmltag> components as children.
The headers of the <sgmltag><rich:accordionItem></sgmltag>
components control the expanding and collapsing when clicked. Only a single
<sgmltag><rich:accordionItem></sgmltag> can be displayed at a
time. Refer to <xref
linkend="sect-Component_Reference-Panels_and_containers-richaccordionItem" />
for details on the <sgmltag><rich:accordionItem></sgmltag>
component.
- </para>
- </section>
-
- <section id="sect-Component_Reference-richaccordion-Switching_panels">
- <title>Switching panels</title>
- <para>
- The switching mode for performing submissions is determined by the
<code>switchType</code> attribute, which can have one of the following three
values:
- </para>
- <variablelist>
- <varlistentry>
- <term><literal>server</literal></term>
- <listitem>
- <para>
- The default setting. Activation of a
<sgmltag><rich:accordionItem></sgmltag> component causes the
parent <sgmltag><rich:accordion></sgmltag> component to perform
a common submission, completely re-rendering the page. Only one panel at a time is
uploaded to the client side.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ajax</literal></term>
- <listitem>
- <para>
- Activation of a <sgmltag><rich:accordionItem></sgmltag>
component causes the parent <sgmltag><rich:accordion></sgmltag>
component to perform an Ajax form submission, and the content of the panel is rendered.
Only one panel at a time is uploaded to the client side.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>client</literal></term>
- <listitem>
- <para>
- Activation of a <sgmltag><rich:accordionItem></sgmltag>
component causes the parent <sgmltag><rich:accordion></sgmltag>
component to update on the client side. JavaScript changes the styles such that one panel
component becomes hidden while the other is shown.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <!-- TODO
- <section
id="sect-Component_Reference-richaccordion-Controlling_panel_size">
- <title>Controlling panel size</title>
- <para>
- Unlike the <sgmltag><rich:panel></sgmltag> component, the
size of the <sgmltag><rich:accordion></sgmltag> can be specified
using <varname>width</varname> and <varname>height</varname>
attributes. If unspecified, these values default to 100%.
- </para>
- </section>
- -->
-
- <section
id="sect-Component_Reference-richaccordion-richaccordion_client-side_events">
- <title><sgmltag><rich:accordion></sgmltag> client-side
events</title>
- <para>
- In addition to the standard Ajax events and HTML events, the
<sgmltag><rich:accordion></sgmltag> component uses the
client-side events common to all switchable panels:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The <varname>itemchange</varname> event points to the function to
perform when the switchable item is changed.
- </para>
- </listitem>
- <listitem>
- <para>
- The <varname>beforeitemchange</varname> event points to the function to
perform when before the switchable item is changed.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section
id="sect-Component_Reference-richaccordion-richaccordion_server-side_events">
- <title><sgmltag><rich:accordion></sgmltag> server-side
events</title>
- <para>
- The <sgmltag><rich:accordion></sgmltag> component uses the
server-side events common to all switchable panels:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The <varname>ItemChangeEvent</varname> event occurs on the server side
when an item is changed through Ajax using the <literal>server</literal> mode.
It can be processed using the <varname>ItemChangeListener</varname>
attribute.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="sect-Component_Reference-richaccordion-JavaScript_API">
- <title>JavaScript API</title>
- <para>
- The <sgmltag><rich:accordion></sgmltag> component can
be controlled through the JavaScript API. The JavaScript API provides the following
functions, which are common to all switchable panels:
- </para>
- <variablelist>
- <varlistentry>
- <term><function>getItems()</function></term>
- <listitem>
- <para>
- Return an array of the items contained in the accordion control.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>getItemsNames()</function></term>
- <listitem>
- <para>
- Return an array of the names of the items contained in the accordion
control.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
-
<term><function>switchToItem(itemName)</function></term>
- <listitem>
- <para>
- Switch to and display the item identified by the
<parameter>itemName</parameter> string passed as a parameter.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="sect-Component_Reference-richaccordion-Reference_data">
- <title>Reference data</title>
- <itemizedlist>
- <listitem>
- <para>
- <parameter>component-type</parameter>:
<classname>org.richfaces.accordion</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlAccordion</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-family</parameter>:
<classname>org.richfaces.accordion</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>renderer-type</parameter>:
<classname>org.richfaces.accordionRenderer</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.accordionTag</classname>
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section
id="sect-Component_Reference-richaccordion-Style_classes_and_skin_parameters">
- <title>Style classes and skin parameters</title>
- <xi:include href="skinning/tabl-richaccordion.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- </section>
-
- <!--<rich:accordionItem>-->
- <section
id="sect-Component_Reference-Panels_and_containers-richaccordionItem">
- <title><sgmltag><rich:accordionItem></sgmltag></title>
- <para>
- The <sgmltag><rich:accordionItem></sgmltag> component is a
panel for use with the <sgmltag><rich:accordion></sgmltag>
component.
- </para>
-
- <section id="sect-Component_Reference-richaccordionItem-Basic_usage">
- <title>Basic usage</title>
- <para>
- Basic usage of the <sgmltag><rich:accordionItem></sgmltag>
component requires the <varname>label</varname> attribute, which provides the
text on the panel header. The panel header is all that is visible when the accordion item
is collapsed.
- </para>
- <para>
- Alternatively the <literal>header</literal> facet could be used in place
of the <varname>label</varname> attribute. This would allow for additional
styles and custom content to be applied to the tab.
- </para>
- </section>
-
- <section
id="sect-Component_Reference-richaccordionItem-richaccordionItem_client-side_events">
- <title><sgmltag><rich:accordionItem></sgmltag>
client-side events</title>
- <para>
- In addition to the standard HTML events, the
<sgmltag><rich:accordionItem></sgmltag> component uses the
client-side events common to all switchable panel items:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The <varname>enter</varname> event points to the function to perform
when the mouse enters the panel.
- </para>
- </listitem>
- <listitem>
- <para>
- The <varname>leave</varname> event points to the function to perform
when the mouse leaves the panel.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section
id="sect-Component_Reference-richaccordionItem-Reference_data">
- <title>Reference data</title>
- <itemizedlist>
- <listitem>
- <para>
- <parameter>component-type</parameter>:
<classname>org.richfaces.accordionItem</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlAccordionItem</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-family</parameter>:
<classname>org.richfaces.accordionItem</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>renderer-type</parameter>:
<classname>org.richfaces.accordionItemRenderer</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.accordionItemTag</classname>
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
- </section>
-
- <!--<rich:collapsiblePanel>-->
- <section
id="sect-Component_Reference-Panels_and_containers-richcollapsiblePanel">
- <title><sgmltag><rich:collapsiblePanel></sgmltag></title>
- <para>
- The <sgmltag><rich:collapsiblePanel></sgmltag> component is
a collapsible panel that shows or hides content when the header bar is activated. It is a
simplified version of <sgmltag><rich:togglePanel></sgmltag>
component.
- </para>
- <figure
id="figu-Component_Reference-richcollapsiblePanel-richcollapsiblePanel">
- <title><sgmltag><rich:collapsiblePanel></sgmltag></title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/figu-Component_Reference-richcollapsiblePanel-richcollapsiblePanel.png"
format="PNG" />
- </imageobject>
- <textobject>
- <para>
- A <sgmltag><rich:collapsiblePanel></sgmltag> component
displaying details on a camera model.
- </para>
- </textobject>
- </mediaobject>
- </figure>
-
- <section
id="sect-Component_Reference-richcollapsiblePanel-Basic_usage">
- <title>Basic usage</title>
- <para>
- Basic usage requires the <varname>header</varname> attribute to be
specified, which provides the title for the header element. Additionally the panel
requires content to display when it is expanded. Content is added as child elements like a
standard panel.
- </para>
- </section>
-
- <section
id="sect-Component_Reference-richcollapsiblePanel-Expanding_and_collapsing_the_panel">
- <title>Expanding and collapsing the panel</title>
- <!-- TODO not in M3 -->
- <!--
- <para>
- If the <sgmltag><rich:collapsiblePanel></sgmltag> component
uses <code><varname>expanded</varname>="true"</code>,
the panel is open and expanded, otherwise it is closed and collapsed.
- </para>
- <para>
- The <varname>toggleElement</varname> attribute is used to specify which
user interface element triggers the expansion when clicked. It can have one of the
following values:
- </para>
- <variablelist>
- <varlistentry>
- <term><literal>header</literal></term>
- <listitem>
- <para>
- This is the default setting. Clicking anywhere on the header of the panel will
cause it to expand or collapse.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>panel</literal></term>
- <listitem>
- <para>
- Clicking anywhere on the entire panel will cause it to expand or collapse.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>control</literal></term>
- <listitem>
- <para>
- The panel can only be expanded or collapsed by clicking on the control in the
right-hand side of the header.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- -->
- <para>
- The switching mode for performing submissions is determined by the
<varname>switchType</varname> attribute, which can have one of the following
three values:
- </para>
- <variablelist>
- <varlistentry>
- <term><literal>server</literal></term>
- <listitem>
- <para>
- This is the default setting. The
<sgmltag><rich:collapsiblePanel></sgmltag> component performs a
common submission, completely re-rendering the page. Only one panel at a time is uploaded
to the client side.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ajax</literal></term>
- <listitem>
- <para>
- The <sgmltag><rich:collapsiblePanel></sgmltag> component
performs an Ajax form submission, and only the content of the panel is rendered. Only one
panel at a time is uploaded to the client side.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>client</literal></term>
- <listitem>
- <para>
- The <sgmltag><rich:collapsiblePanel></sgmltag> component
updates on the client side, re-rendering itself and any additional components listed with
the <varname>render</varname> attribute.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section
id="sect-Component_Reference-richcollapsiblePanel-Appearance">
- <title>Appearance</title>
- <para>
- The appearance of the
<sgmltag><rich:collapsiblePanel></sgmltag> component can be
customized using facets. The <literal>headerExpandedClass</literal> and
<literal>headerCollapsedClass</literal> facets are used to style the
appearance of the panel when it is expanded and collapsed respectively. The
<literal>expandControl</literal> facet styles the control in the panel header
used for expanding, and the <literal>collapseControl</literal> facet styles
the control for collapsing.
- </para>
- </section>
-
- <section
id="sect-Component_Reference-richcollapsiblePanel-richcollapsiblePanel_server-side_events">
- <title><sgmltag><rich:collapsiblePanel></sgmltag>
server-side events</title>
- <para>
- The <sgmltag><rich:collapsiblePanel></sgmltag> component
uses the following unique server-side events:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The <varname>ChangeExpandEvent</varname> event occurs on the server
side when the <sgmltag><rich:collapsiblePanel></sgmltag>
component is expanded or collapsed through Ajax using the
<literal>server</literal> mode. It can be processed using the
<varname>ChangeExpandListener</varname> attribute.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section
id="sect-Component_Reference-richcollapsiblePanel-JavaScript_API">
- <title>JavaScript API</title>
- <para>
- The <sgmltag><rich:collapsiblePanel></sgmltag>
component can be controlled through the JavaScript API. The JavaScript API provides the
following functions:
- </para>
- <variablelist>
- <varlistentry>
- <term><function>switchPanel()</function></term>
- <listitem>
- <para>
- Switch the state of the collapsible panel (expanded or collapsed).
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section
id="sect-Component_Reference-richcollapsiblePanel-Reference_data">
- <title>Reference data</title>
- <itemizedlist>
- <listitem>
- <para>
- <parameter>component-type</parameter>:
<classname>org.richfaces.collapsiblePanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlcollapsiblePanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-family</parameter>:
<classname>org.richfaces.collapsiblePanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>renderer-type</parameter>:
<classname>org.richfaces.collapsiblePanelRenderer</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.collapsiblePanelTag</classname>
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section
id="sect-Component_Reference-richcollapsiblePanel-Style_classes_and_skin_parameters">
- <title>Style classes and skin parameters</title>
- <xi:include href="skinning/tabl-richcollapsiblePanel.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- </section>
-
- </section>
-
- <!--<rich:popupPanel>-->
- <section
id="sect-Component_Reference-Panels_and_containers-richpopupPanel">
- <title><sgmltag><rich:popupPanel></sgmltag></title>
- <para>
- The <sgmltag><rich:popupPanel></sgmltag> component provides
a pop-up panel or window that appears in front of the rest of the application. The
<sgmltag><rich:popupPanel></sgmltag> component functions either
as a modal window which blocks interaction with the rest of the application while active,
or as a non-modal window. It can be positioned on the screen, dragged to a new position by
the user, and re-sized.
- </para>
-
- <section id="sect-Component_Reference-richpopupPanel-Basic_usage">
- <title>Basic usage</title>
- <para>
- The <sgmltag><rich:popupPanel></sgmltag> does not require
any compulsory attributes, though certain use cases require different attributes.
- </para>
- </section>
-
- <section
id="sect-Component_Reference-richpopupPanel-Showing_and_hiding_the_pop-up">
- <title>Showing and hiding the pop-up</title>
- <para>
- If <code>show="true"</code> then the pop-up panel will display
when the page is first loaded.
- </para>
- <para>
- The <sgmltag><rich:popupPanel></sgmltag> component can be
shown and hidden manually using the <code>show()</code> and
<code>hide()</code> methods from the JavaScript API. These can be implemented
using two different approaches:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Using the <sgmltag><rich:componentControl></sgmltag>
component. For details on the component, refer to <xref
linkend="sect-Component_Reference-Actions-richcomponentControl" />.
- </para>
- </listitem>
- <listitem>
- <para>
- Using the <code>rich:component</code> function. For details on the
function, refer to <xref
linkend="sect-Component_Reference-Functions-richcomponent" />.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- For explicit referencing when using the functions, the component can be given an
<varname>id</varname> identifier. The component can, however, be referenced
using other means, such as through a selector.
- </para>
- <para>
- <xref
linkend="exam-Component_Reference-richpopupPanel-richpopupPanel_example" />
demonstrates basic use of both the
<sgmltag><rich:componentControl></sgmltag> component and the
<code>rich:component</code> function to show and hide the
<sgmltag><rich:popupPanel></sgmltag> component.
- </para>
- <example
id="exam-Component_Reference-richpopupPanel-richpopupPanel_example">
- <title><sgmltag><rich:popupPanel></sgmltag>
example</title>
- <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richpopupPanel-richpopupPanel_example.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
- <important>
- <title>Placement</title>
- <para>
- The <sgmltag><rich:popupPanel></sgmltag> component should
usually be placed outside the original form, and include its own form if performing
submissions. An exception to this is when using the
<varname>domElementAttachment</varname> attribute, as described in <xref
linkend="sect-Component_Reference-richpopupPanel-Size_and_positioning" />.
- </para>
- </important>
- </section>
-
- <section
id="sect-Component_Reference-richpopupPanel-Modal_and_non-modal_panels">
- <title>Modal and non-modal panels</title>
- <para>
- By default, the <sgmltag><rich:popupPanel></sgmltag>
appears as a modal window that blocks interaction with the other objects on the page. To
implement a non-modal window instead, set
<code><varname>modal</varname>="false"</code>. This will
allow interaction with other objects outside the pop-up panel.
- </para>
- </section>
-
- <section
id="sect-Component_Reference-richpopupPanel-Size_and_positioning">
- <title>Size and positioning</title>
- <para>
- The pop-up panel can be both re-sized and re-positioned by the user. The minimum
possible size for the panel can be set with the <varname>minWith</varname> and
<varname>minHeight</varname> attributes. These abilities can be deactivated by
setting <code>resizable</code> or <code>movable</code> to
<literal>false</literal> as necessary.
- <!--
- The state of the modal panel, including size and position on screen, can be
maintained and restored after submitting and reloading by setting
<code>keepVisualState="true"</code>.
- -->
- </para>
- <para>
- The pop-up panel can be automatically sized when it is shown if the
<varname>autosized</varname> attribute is set to
<literal>true</literal>.
- </para>
- <para>
- The <sgmltag><rich:popupPanel></sgmltag> component is
usually rendered in front of any other objects on the page. This is achieved by attaching
the component to the <sgmltag><body></sgmltag> element of the
page, and setting a very high <emphasis>"z-index"</emphasis> (the
stack order of the object). This approach is taken because relatively-positioned elements
could still overlap the pop-up panel if they exist at higher levels of the
<acronym>DOM</acronym> hierarchy, even if their z-index is less than the
<sgmltag><rich:popupPanel></sgmltag> component. However, to
avoid form limitation of the pop-up panel on pages where no such elements exist, the
<sgmltag><rich:popupPanel></sgmltag> component can be reattached
to its original <acronym>DOM</acronym> element by setting
<varname>domElementAttachment</varname> to either
<literal>parent</literal> or <literal>form</literal>.
- </para>
- <para>
- Embedded objects inserted into the <acronym>HTML</acronym> with the
<sgmltag><embed></sgmltag> tag will typically be rendered in
front of a <sgmltag><rich:popupPanel></sgmltag> component. The
<sgmltag><rich:popupPanel></sgmltag> component can be forcibly
rendered in front of these objects by setting
<code><varname>overlapEmbedObjects</varname>="true"</code>.
- </para>
- <note>
- <title>Using <varname>overlapEmbedObjects</varname></title>
- <para>
- Due to the additional script processing required when using the
<varname>overlapEmbedObjects</varname> attribute, applications can suffer from
decreased performance. As such, <varname>overlapEmbedObjects</varname> should
only be set to <literal>true</literal> when
<sgmltag><embed></sgmltag> tags are being used. Do not set it to
<literal>true</literal> for applications that do not require it.
- </para>
- </note>
- </section>
-
- <section
id="sect-Component_Reference-richpopupPanel-Contents_of_the_pop-up">
- <title>Contents of the pop-up</title>
- <para>
- The <sgmltag><rich:popupPanel></sgmltag> component can
contain any other rich component just like a normal panel.
- </para>
- <para>
- Contents of the <sgmltag><rich:popupPanel></sgmltag>
component which are positioned relatively may be trimmed if they extend beyond the borders
of the pop-up panel. For certain in-line controls this behavior may be preferable, but for
other dynamic controls it could be undesirable. If the
<varname>trimOverlayedElements</varname> attribute is set to
<literal>false</literal> then child components will not be trimmed if they
extend beyond the borders of the pop-up panel.
- </para>
- </section>
-
- <section
id="sect-Component_Reference-richpopupPanel-Header_and_controls">
- <title>Header and controls</title>
- <para>
- A panel header and associated controls can be added to the
<sgmltag><rich:popupPanel></sgmltag> component through the use
of facets. The <literal>header</literal> facet displays a title for the panel,
and the <literal>controls</literal> facet can be customized to allow window
controls such as a button for closing the pop-up. <xref
linkend="exam-Component_Reference-richpopupPanel-Header_and_controls" />
demonstrates the use of the facets.
- </para>
- <example
id="exam-Component_Reference-richpopupPanel-Header_and_controls">
- <title>Header and controls</title>
- <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richpopupPanel-Header_and_controls.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <blockquote>
- <figure
id="figu-Component_Reference-richpopupPanel-Header_and_controls">
- <title>Header and controls</title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/figu-Component_Reference-richpopupPanel-Header_and_controls.png"
format="PNG" />
- </imageobject>
- <textobject>
- <para>
- The <sgmltag><rich:popupPanel></sgmltag> component,
rendered with a title header and a button control for closing the pop-up.
- </para>
- </textobject>
- </mediaobject>
- </figure>
- </blockquote>
- </example>
- </section>
-
- <section id="sect-Component_Reference-richpopupPanel-JavaScript_API">
- <title>JavaScript API</title>
- <para>
- The <sgmltag><rich:popupPanel></sgmltag> component can
be controlled through the JavaScript API. The JavaScript API provides the following
functions:
- </para>
- <variablelist>
- <varlistentry>
- <term><function>getTop()</function></term>
- <listitem>
- <para>
- Return the top co-ordinate for the position of the pop-up panel.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>getLeft()</function></term>
- <listitem>
- <para>
- Return the left co-ordinate for the position of the pop-up panel.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>moveTo(top,left)</function></term>
- <listitem>
- <para>
- Move the pop-up panel to the co-ordinates specified with the
<parameter>top</parameter> and <parameter>left</parameter>
parameters.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
-
<term><function>resize(width,height)</function></term>
- <listitem>
- <para>
- Resize the pop-up panel to the size specified with the
<parameter>width</parameter> and <parameter>height</parameter>
parameters.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>show()</function></term>
- <listitem>
- <para>
- Show the pop-up panel.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>hide()</function></term>
- <listitem>
- <para>
- Hide the pop-up panel.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="sect-Component_Reference-richpopupPanel-Reference_data">
- <title>Reference data</title>
- <itemizedlist>
- <listitem>
- <para>
- <parameter>component-type</parameter>:
<classname>org.richfaces.popupPanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlpopupPanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-family</parameter>:
<classname>org.richfaces.popupPanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>renderer-type</parameter>:
<classname>org.richfaces.popupPanelRenderer</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.popupPanelTag</classname>
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section
id="sect-Component_Reference-richpopupPanel-Style_classes_and_skin_parameters">
- <title>Style classes and skin parameters</title>
- <xi:include href="skinning/tabl-richpopupPanel.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- </section>
- </section>
-
- <!--<rich:tabPanel>-->
- <section
id="sect-Component_Reference-Panels_and_containers-richtabPanel">
- <title><sgmltag><rich:tabPanel></sgmltag></title>
- <para>
- The <sgmltag><rich:tabPanel></sgmltag> component provides a
set of tabbed panels for displaying one panel of content at a time. The tabs can be highly
customized and themed. Each tab within a
<sgmltag><rich:tabPanel></sgmltag> container is a
<sgmltag><rich:tab></sgmltag> component. Refer to <xref
linkend="sect-Component_Reference-Panels_and_containers-richtab" /> for
further details on the <sgmltag><rich:tab></sgmltag> component.
- </para>
- <figure
id="figu-Component_Reference-richtabPanel-richtabPanel_component">
- <title>A <sgmltag><rich:tabPanel></sgmltag> component
containing three <sgmltag><rich:tab></sgmltag>
components</title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/figu-Component_Reference-richtabPanel-richtabPanel_component.png"
format="PNG" />
- </imageobject>
- <textobject>
- <para>
- A <sgmltag><rich:tabPanel></sgmltag> component containing
three <sgmltag><rich:tab></sgmltag> components.
- </para>
- </textobject>
- </mediaobject>
- </figure>
- <note>
- <title>Form elements required</title>
- <para>
- All <sgmltag><rich:tabPanel></sgmltag> components should be
wrapped in a form element so that the contents of the tab are processed correctly during a
tab change in either <literal>ajax</literal> or
<literal>server</literal> mode.
- </para>
- <para>
- Alternatively, the contents of a
<sgmltag><rich:tab></sgmltag> component within the
<sgmltag><rich:tabPanel></sgmltag> component could be wrapped in
a form element, such that they will be processed using the inner submitting component
only. In this case, the <sgmltag><rich:tabPanel></sgmltag>
component will automatically add form tags around the tab's contents, and the contents
will not be processed during switching.
- </para>
- </note>
-
- <section id="sect-Component_Reference-richtabPanel-Switching_tabs">
- <title>Switching panels</title>
- <para>
- The <code>activeItem</code> attribute holds the active tab name. This
name is a reference to the <varname>name</varname> identifier of the active
child <sgmltag><rich:tab></sgmltag> component.
- </para>
- <para>
- The switching mode for performing submissions is determined by the
<code>switchType</code> attribute, which can have one of the following three
values:
- </para>
- <variablelist>
- <varlistentry>
- <term><literal>server</literal></term>
- <listitem>
- <para>
- The default setting. Activation of a
<sgmltag><rich:tab></sgmltag> component causes the parent
<sgmltag><rich:tabPanel></sgmltag> component to perform a common
submission, completely re-rendering the page. Only one tab at a time is uploaded to the
client side.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ajax</literal></term>
- <listitem>
- <para>
- Activation of a <sgmltag><rich:tab></sgmltag> component
causes the parent <sgmltag><rich:tabPanel></sgmltag> component
to perform an Ajax form submission, and the content of the tab is rendered. Only one tab
at a time is uploaded to the client side.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>client</literal></term>
- <listitem>
- <para>
- Activation of a <sgmltag><rich:tab></sgmltag> component
causes the parent <sgmltag><rich:tabPanel></sgmltag> component
to update on the client side. JavaScript changes the styles such that one tab becomes
hidden while the other is shown.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <!-- FIXME details on name attribute -->
-
- <!-- TODO not in M3 -->
- <!--
- <section
id="sect-Component_Reference-richtabPanel-Tab_position_and_alignment">
- <title>Tab position and alignment</title>
- <para>
- The tab headers, used for switching between the tabs, can be positioned along any
edge of the panel by using the <varname>headerPosition</varname> attribute.
The possible values for the <varname>headerPosition</varname> attribute are as
follows:
- </para>
- <variablelist>
- <varlistentry>
- <term><literal>top</literal></term>
- <listitem>
- <para>
- The tab headers are positioned along the top of the panel. This is the default
position.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>left</literal></term>
- <listitem>
- <para>
- The tab headers are positioned along the left edge of the panel.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>right</literal></term>
- <listitem>
- <para>
- The tab headers are positioned along the right edge of the panel.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>bottom</literal></term>
- <listitem>
- <para>
- The tab headers are positioned along the bottom of the panel.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- The tab headers themselves can be aligned using the
<code>headerAlignment</code> attribute. The possible values for the
<varname>headerAlignment</varname> attribute are as follows:
- </para>
- <variablelist>
- <varlistentry>
- <term><literal>top</literal></term>
- <listitem>
- <para>
- The tab headers are aligned to the top of the tab header position.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>left</literal></term>
- <listitem>
- <para>
- The tab headers are aligned to the left of the tab header position. This is the
default alignment.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>right</literal></term>
- <listitem>
- <para>
- The tab headers are aligned to the right of the tab header position.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>bottom</literal></term>
- <listitem>
- <para>
- The tab headers are aligned to the bottom of the tab header position.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>center</literal></term>
- <listitem>
- <para>
- The tab headers are aligned in the center of the tab header position.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
- -->
-
- <section
id="sect-Component_Reference-richtabPanel-richtabPanel_client-side_events">
- <title><sgmltag><rich:tabPanel></sgmltag> client-side
events</title>
- <para>
- In addition to the standard Ajax events and HTML events, the
<sgmltag><rich:tabPanel></sgmltag> component uses the
client-side events common to all switchable panels:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The <varname>itemchange</varname> event points to the function to
perform when the switchable item is changed.
- </para>
- </listitem>
- <listitem>
- <para>
- The <varname>beforeitemchange</varname> event points to the function to
perform when before the switchable item is changed.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section
id="sect-Component_Reference-richtabPanel-richtabPanel_server-side_events">
- <title><sgmltag><rich:tabPanel></sgmltag> server-side
events</title>
- <para>
- The <sgmltag><rich:tabPanel></sgmltag> component uses the
server-side events common to all switchable panels:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The <varname>ItemChangeEvent</varname> event occurs on the server side
when an item is changed through Ajax using the <literal>server</literal> mode.
It can be processed using the <varname>ItemChangeListener</varname>
attribute.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="sect-Component_Reference-richtabPanel-JavaScript_API">
- <title>JavaScript API</title>
- <para>
- The <sgmltag><rich:tabPanel></sgmltag> component can be
controlled through the JavaScript API. The JavaScript API provides the following
functions, which are common to all switchable panels:
- </para>
- <variablelist>
- <varlistentry>
- <term><function>getItems()</function></term>
- <listitem>
- <para>
- Return an array of the tabs contained in the tab panel.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>getItemsNames()</function></term>
- <listitem>
- <para>
- Return an array of the names of the tabs contained in the tab panel.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
-
<term><function>switchToItem(itemName)</function></term>
- <listitem>
- <para>
- Switch to and display the item identified by the
<parameter>itemName</parameter> string passed as a parameter.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="sect-Component_Reference-richtabPanel-Reference_data">
- <title>Reference data</title>
- <itemizedlist>
- <listitem>
- <para>
- <parameter>component-type</parameter>:
<classname>org.richfaces.tabPanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlTabPanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-family</parameter>:
<classname>org.richfaces.tabPanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>renderer-type</parameter>:
<classname>org.richfaces.tabPanelRenderer</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.tabPanelTag</classname>
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section
id="sect-Component_Reference-richtabPanel-Style_classes_and_skin_parameters">
- <title>Style classes and skin parameters</title>
- <xi:include href="skinning/tabl-richtabPanel.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- </section>
-
- <!--<rich:tab>-->
- <section id="sect-Component_Reference-Panels_and_containers-richtab">
- <title><sgmltag><rich:tab></sgmltag></title>
- <para>
- The <sgmltag><rich:tab></sgmltag> component represents an
individual tab inside a <sgmltag><rich:tabPanel></sgmltag>
component, including the tab's content. Clicking on the tab header will bring its
corresponding content to the front of other tabs.
- </para>
-
- <section id="sect-Component_Reference-richtab-Basic_usage">
- <title>Basic usage</title>
- <para>
- Basic usage of the <sgmltag><rich:tab></sgmltag> component
requires the <varname>name</varname> attribute to uniquely identify the tab
within the parent <sgmltag><rich:tabPanel></sgmltag> component.
As the tabs are switched, the <varname>name</varname> identifier of the
currently selected tab is stored in the <varname>activeItem</varname>
attribute of the parent <sgmltag><rich:tabPanel></sgmltag>
component.
- </para>
- </section>
-
- <section id="sect-Component_Reference-richtab-Header_labeling">
- <title>Header labeling</title>
- <para>
- In addition to the <varname>name</varname> identifier, the
<varname>header</varname> attribute must be defined. The
<varname>header</varname> attribute provides the text on the tab header. The
content of the tab is then detailed inside the
<sgmltag><rich:tab></sgmltag> tags.
- </para>
- <para>
- Alternatively, the <literal>header</literal> facet could be used in
place of the <varname>header</varname> attribute. This would allow for
additional styles and custom content to be applied to the tab. The component also supports
three facets to customize the appearance depending on the current state of the tab:
- </para>
- <variablelist>
- <varlistentry>
- <term><literal>headerActiveClass</literal> facet</term>
- <listitem>
- <para>
- This facet is used when the tab is the currently active tab.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>headerInactiveClass</literal> facet</term>
- <listitem>
- <para>
- This facet is used when the tab is not currently active.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>headerDisabledClass</literal> facet</term>
- <listitem>
- <para>
- This facet is used when the tab is disabled.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- The <literal>header</literal> facet is used in place of any state-based
facet that has not been defined.
- </para>
- </section>
-
- <section id="sect-Component_Reference-richtab-Switching_tabs">
- <title>Switching tabs</title>
- <para>
- The switching mode for performing submissions can be inherited from the
<varname>switchType</varname> attribute of the parent
<sgmltag><rich:tabPanel></sgmltag> component, or set
individually for each <sgmltag><rich:tab></sgmltag> component.
Refer to <xref
linkend="sect-Component_Reference-Panels_and_containers-richtabPanel" /> for
details on the <varname>switchType</varname> attribute.
- </para>
- <para>
- An individual tab can be disabled by setting
<code><varname>disabled</varname>="true"</code>.
Disabled tabs cannot be activated or switched to.
- </para>
- </section>
-
- <section
id="sect-Component_Reference-richtab-richtab_client-side_events">
- <title><sgmltag><rich:tab></sgmltag> client-side
events</title>
- <para>
- In addition to the standard HTML events, the
<sgmltag><rich:tab></sgmltag> component uses the client-side
events common to all switchable panel items:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The <varname>enter</varname> event points to the function to perform
when the mouse enters the tab.
- </para>
- </listitem>
- <listitem>
- <para>
- The <varname>leave</varname> attribute points to the function to
perform when the mouse leaves the tab.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="sect-Component_Reference-richtab-Reference_data">
- <title>Reference data</title>
- <itemizedlist>
- <listitem>
- <para>
- <parameter>component-type</parameter>:
<classname>org.richfaces.tab</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlTab</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-family</parameter>:
<classname>org.richfaces.tab</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>renderer-type</parameter>:
<classname>org.richfaces.tabRenderer</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.tabTag</classname>
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
- </section>
-
- <!--<rich:togglePanel>-->
- <section
id="sect-Component_Reference-Panels_and_containers-richtogglePanel">
- <title><sgmltag><rich:togglePanel></sgmltag></title>
- <para>
- The <sgmltag><rich:togglePanel></sgmltag> component is a
wrapper for multiple <sgmltag><rich:togglePanelItem></sgmltag>
components. Each child component is displayed after being activated with the
<sgmltag><rich:toggleControl></sgmltag> behavior.
- </para>
- <para>
- Refer to <xref
linkend="sect-Component_Reference-Panels_and_containers-richtoggleControl" />
and <xref
linkend="sect-Component_Reference-Panels_and_containers-richtogglePanel" />
for details on how to use the components together.
- </para>
- <para>
- The <sgmltag><rich:togglePanel></sgmltag> component is used
as a base for the other switchable components, the
<sgmltag><rich:accordion></sgmltag> component and the
<sgmltag><rich:tabPanel></sgmltag> component. It provides an
abstract switchable component without any associated markup. As such, the
<sgmltag><rich:togglePanel></sgmltag> component could be
customized to provide a switchable component when neither an accordion component or a tab
panel component is appropriate.
- </para>
-
- <section id="sect-Component_Reference-richtogglePanel-Basic_usage">
- <title>Basic usage</title>
- <para>
- The initial state of the component can be configured using the
<varname>activeItem</varname> attribute, which points to a child component to
display. Alternatively, if no <varname>activeItem</varname> attribute is
defined, the initial state will be blank until the user activates a child component using
the <sgmltag><rich:toggleControl></sgmltag> component.
- </para>
- <para>
- The child components are shown in the order in which they are defined in the view.
- </para>
- </section>
-
- <section
id="sect-Component_Reference-richtogglePanel-Toggling_between_panels">
- <title>Toggling between components</title>
- <para>
- The switching mode for performing submissions is determined by the
<code>switchType</code> attribute, which can have one of the following three
values:
- </para>
- <variablelist>
- <varlistentry>
- <term><literal>server</literal></term>
- <listitem>
- <para>
- The default setting. Activation of a child component causes the parent
<sgmltag><rich:togglePanel></sgmltag> component to perform a
common submission, completely re-rendering the page. Only one child at a time is uploaded
to the client side.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ajax</literal></term>
- <listitem>
- <para>
- Activation of a child component causes the parent
<sgmltag><rich:togglePanel></sgmltag> component to perform an
Ajax form submission, and the content of the child is rendered. Only one child at a time
is uploaded to the client side.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>client</literal></term>
- <listitem>
- <para>
- Activation of a child component causes the parent
<sgmltag><rich:togglePanel></sgmltag> component to update on the
client side. JavaScript changes the styles such that one child component becomes hidden
while the other is shown.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="sect-Component_Reference-richtogglePanel-JavaScript_API">
- <title>JavaScript API</title>
- <para>
- The <sgmltag><rich:togglePanel></sgmltag> component can
be controlled through the JavaScript API. The JavaScript API provides the following
functions, which are common to all switchable panels:
- </para>
- <variablelist>
- <varlistentry>
- <term><function>getItems()</function></term>
- <listitem>
- <para>
- Return an array of the items contained in the toggle panel.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>getItemsNames()</function></term>
- <listitem>
- <para>
- Return an array of the names of the items contained in the toggle
panel.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
-
<term><function>switchToItem(itemName)</function></term>
- <listitem>
- <para>
- Switch to and display the item identified by the
<parameter>itemName</parameter> string passed as a parameter.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="sect-Component_Reference-richtogglePanel-Reference_data">
- <title>Reference data</title>
- <itemizedlist>
- <listitem>
- <para>
- <parameter>component-type</parameter>:
<classname>org.richfaces.TogglePanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlTogglePanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-family</parameter>:
<classname>org.richfaces.TogglePanel</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>renderer-type</parameter>:
<classname>org.richfaces.TogglePanelRenderer</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.TogglePanelTag</classname>
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <!--<rich:toggleControl>-->
- <section
id="sect-Component_Reference-Panels_and_containers-richtoggleControl">
- <title><sgmltag><rich:toggleControl></sgmltag></title>
- <para>
- The <sgmltag><rich:toggleControl></sgmltag> behavior can be
attached to any interface component. It works with a
<sgmltag><rich:togglePanel></sgmltag> component to switch
between different <sgmltag><rich:togglePanelItem></sgmltag>
components.
- </para>
- <para>
- Refer to <xref
linkend="sect-Component_Reference-Panels_and_containers-richtogglePanel" />
and <xref
linkend="sect-Component_Reference-Panels_and_containers-richtogglePanelItem"
/> for details on how to use the components together.
- </para>
-
- <section id="sect-Component_Reference-richtoggleControl-Basic_usage">
- <title>Basic usage</title>
- <para>
- The <sgmltag><rich:toggleControl></sgmltag> can be used to
switch through <sgmltag><rich:togglePanelItem></sgmltag>
components in a <sgmltag><rich:togglePanel></sgmltag> container.
If the <sgmltag><rich:toggleControl></sgmltag> component is
positioned inside a <sgmltag><rich:togglePanel></sgmltag>
component, no attributes need to be defined, as the control is assumed to switch through
the <sgmltag><rich:togglePanelItem></sgmltag> components of its
parent.
- </para>
- <para>
- A <sgmltag><rich:toggleControl></sgmltag> component can be
located outside the <sgmltag><rich:togglePanel></sgmltag>
component it needs to switch. Where this is the case, the
<sgmltag><rich:togglePanel></sgmltag> is identified using the
<varname>activePanel</varname> attribute. the Cycling through components
requires the <varname>for</varname> attribute, which points to the
<varname>id</varname> identifier of the
<sgmltag><rich:togglePanel></sgmltag> that it controls.
- </para>
- </section>
-
- <section
id="sect-Component_Reference-richtoggleControl-Specifying_the_next_state">
- <title>Specifying the next state</title>
- <para>
- The <sgmltag><rich:toggleControl></sgmltag> component will
cycle through <sgmltag><rich:togglePanelItem></sgmltag>
components in the order they are defined within the view. However, the next item to switch
to can be explicitly defined by including a
<sgmltag><rich:toggleControl></sgmltag> component within a
<sgmltag><rich:togglePanelItem></sgmltag> and using the
<varname>targetItem</varname> attribute. The
<varname>targetItem</varname> attribute points to the
<sgmltag><rich:togglePanelItem></sgmltag> to switch to when the
state is next changed. <xref
linkend="exam-Component_Reference-richtoggleControl-richtoggleControl_example"
/> demonstrates how to specify the next switchable state in this way.
- </para>
- <example
id="exam-Component_Reference-richtoggleControl-richtoggleControl_example">
- <title><sgmltag><rich:toggleControl></sgmltag>
example</title>
- <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richtoggleControl-richtoggleControl_example.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
- </section>
-
- <section
id="sect-Component_Reference-richtoggleControl-Reference_data">
- <title>Reference data</title>
- <itemizedlist>
- <listitem>
- <para>
- <parameter>component-type</parameter>:
<classname>org.richfaces.ToggleControl</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlToggleControl</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-family</parameter>:
<classname>org.richfaces.ToggleControl</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>renderer-type</parameter>:
<classname>org.richfaces.ToggleControlRenderer</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.ToggleControlTag</classname>
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
- <!--<rich:togglePanelItem>-->
- <section
id="sect-Component_Reference-Panels_and_containers-richtogglePanelItem">
- <title><sgmltag><rich:togglePanelItem></sgmltag></title>
- <para>
- The <sgmltag><rich:togglePanelItem></sgmltag> component is
a switchable panel for use with the
<sgmltag><rich:togglePanel></sgmltag> component. Switching
between <sgmltag><rich:togglePanelItem></sgmltag> components is
handled by the <sgmltag><rich:toggleControl></sgmltag>
behavior.
- </para>
-
- <section
id="sect-Component_Reference-richtogglePanelItem-Reference_data">
- <title>Reference data</title>
- <itemizedlist>
- <listitem>
- <para>
- <parameter>component-type</parameter>:
<classname>org.richfaces.TogglePanelItem</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-class</parameter>:
<classname>org.richfaces.component.html.HtmlTogglePanelItem</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>component-family</parameter>:
<classname>org.richfaces.TogglePanelItem</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>renderer-type</parameter>:
<classname>org.richfaces.TogglePanelItemRenderer</classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <parameter>tag-class</parameter>:
<classname>org.richfaces.taglib.TogglePanelItemTag</classname>
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
- </section>
-
-</chapter>
-
Modified:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Processing_management.xml
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Processing_management.xml 2011-03-24
18:55:40 UTC (rev 22303)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Processing_management.xml 2011-03-25
03:29:04 UTC (rev 22304)
@@ -9,9 +9,10 @@
<section id="sect-Component_Reference-Processing_management-a4jqueue">
<title><sgmltag><a4j:queue></sgmltag></title>
<para>
- The <sgmltag><a4j:queue></sgmltag> component manages a queue
of Ajax requests to control message processing.
+ The <sgmltag><a4j:queue></sgmltag> component manages the JSF
queue of Ajax requests. It provides additional options for a finer control of request
processing.
</para>
-
+
+ <!--
<section id="sect-Component_Reference-a4jqueue-Queue_size">
<title>Queue size</title>
<para>
@@ -40,16 +41,17 @@
</listitem>
</itemizedlist>
</section>
+ -->
<section
id="sect-Component_Reference-a4jqueue-a4jqueue_client-side_events">
<title><sgmltag><a4j:queue></sgmltag> client-side
events</title>
<para>
- The <sgmltag><a4j:queue></sgmltag> component features
several events relating to queuing actions:
+ The <sgmltag><a4j:queue></sgmltag> component features
several events relating to queuing actions in addition to the common JSF events:
</para>
<itemizedlist>
<listitem>
<para>
- The <varname>complete</varname> event attribute is fired after a
request is completed. The request object is passed as a parameter to the event handler, so
the queue is accessible using <code>request.queue</code> and the element which
was the source of the request is accessible using <code>this</code>.
+ The <varname>complete</varname> event attribute is fired after a
request is completed. The request object is passed as a parameter to the event handler, so
the queue is accessible using <code>request.queue</code> and the element which
was the source of the request is accessible using <literal>this</literal>.
</para>
</listitem>
<listitem>
@@ -62,21 +64,6 @@
The <varname>requestdequeue</varname> event attribute is fired after a
request has been removed from the queue.
</para>
</listitem>
- <listitem>
- <para>
- The <varname>sizeexceeded</varname> event attribute is fired when the
queue has been exceeded.
- </para>
- </listitem>
- <listitem>
- <para>
- The <varname>submit</varname> event attribute is fired before the
request is sent.
- </para>
- </listitem>
- <listitem>
- <para>
- The <varname>success</varname> event attribute is fired after a
successful request but before the <acronym>DOM</acronym> is updated on the
client side.
- </para>
- </listitem>
</itemizedlist>
</section>
@@ -112,49 +99,79 @@
<para>
The <sgmltag><a4j:log></sgmltag> component generates
JavaScript that opens a debug window, logging application information such as requests,
responses, and <acronym>DOM</acronym> changes.
</para>
+
+ <section id="sect-Component_Reference-a4jlog-Basic_usage">
+ <title>Basic usage</title>
+ <para>
+ The <sgmltag><a4j:log></sgmltag> component doesn't
require any additional attributes for basic functionality.
+ </para>
+ </section>
<section id="sect-Component_Reference-a4jlog-Log_monitoring">
- <title>Log monitoring</title><para>
- The <varname>popup</varname> attribute causes the logging data to appear
in a new pop-up window if set to <literal>true</literal>, or in place on the
current page if set to <literal>false</literal>. The window is set to be
opened by pressing the key combination <keycombo
action="simul"><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>L</keycap></keycombo>;
this can be partially reconfigured with the <varname>hotkey</varname>
attribute, which specifies the letter key to use in combination with
<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap></keycombo>
instead of <keycap>L</keycap>.
+ <title>Log monitoring</title>
+ <para>
+ The <varname>mode</varname> attribute determines how the log appears on
the page.
</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Set <code>mode="inline"</code> to place the logging data
in-line on the current page. This is the default setting.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set <code>mode="popup"</code> to present the logging data in
a new pop-up window. The window is set to be opened by pressing the key combination
<keycombo
action="simul"><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>L</keycap></keycombo>;
this can be partially reconfigured with the <varname>hotkey</varname>
attribute, which specifies the letter key to use in combination with
<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap></keycombo>
instead of <keycap>L</keycap>.
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
The amount of data logged can be determined with the
<varname>level</varname> attribute:
</para>
<itemizedlist>
<listitem>
<para>
- <literal>ERROR</literal>
+ Set <code>level="ERROR"</code> to log all errors.
</para>
</listitem>
<listitem>
<para>
- <literal>FATAL</literal>
+ Set <code>level="FATAL"</code> to log only fatal messages.
</para>
</listitem>
<listitem>
<para>
- <literal>INFO</literal>
+ Set <code>level="INFO"</code> to log only informational
messages.
</para>
</listitem>
<listitem>
<para>
- <literal>WARN</literal>
+ Set <code>level="WARN"</code> to log only warning messages.
</para>
</listitem>
<listitem>
<para>
- <literal>ALL</literal>, the default setting, logs all data.
+ Set <code>level="ALL"</code> to log all data. This is the
default setting.
</para>
</listitem>
</itemizedlist>
<example id="exam-Component_Reference-a4jlog-a4jlog_example">
<title><sgmltag><a4j:log></sgmltag>
example</title>
<programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-a4jlog-a4jlog_example.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/figu-Component_Reference-a4jlog-a4jlog_example.png"
format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ The log readout displays all messages.
+ </para>
+ </textobject>
+ </mediaobject>
</example>
<note>
<title>Log renewal</title>
<para>
- The log is automatically renewed after each Ajax request. It does not need to be
explicitly re-rendered.
+ The log is automatically renewed after each Ajax request. It does not need to be
explicitly re-rendered. To clear previous requests, implement a
<guilabel>Clear</guilabel> button or similar functionality.
</para>
</note>
</section>
@@ -187,6 +204,9 @@
<section
id="sect-Component_Reference-a4jlog-Style_classes_and_skin_parameters">
<title>Style classes and skin parameters</title>
+ <para>
+ The <sgmltag><a4j:log></sgmltag> component is intended
primarily for debugging during development. However it is still possible to style the
component if desired.
+ </para>
<xi:include href="skinning/tabl-a4jlog.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</section>
</section>
@@ -194,14 +214,34 @@
<section id="sect-Component_Reference-Processing_management-a4jstatus">
<title><sgmltag><a4j:status></sgmltag></title>
<para>
- The <sgmltag><a4j:status></sgmltag> component displays the
status of current Ajax requests; the status can be either in progress or complete.
+ The <sgmltag><a4j:status></sgmltag> component displays the
status of current Ajax requests. The status can be either in progress, complete, or an
error is shown after a failed request.
</para>
<section id="sect-Component_Reference-a4jstatus-Customizing_the_text">
<title>Customizing the text</title>
<para>
- The <varname>startText</varname> attribute defines the text shown after
the request has been started and is currently in progress. This text can be styled with
the <varname>startStyle</varname> and
<varname>startStyleClass</varname> attributes. Similarly, the
<varname>stopText</varname> attribute defines the text shown once the request
is complete, and text is styled with the <varname>stopStyle</varname> and
<varname>stopStyleClass</varname> attributes. Alternatively, the text styles
can be customized using facets, with the facet name set to either
<literal>start</literal> or <literal>stop</literal> as required.
If the <varname>stopText</varname> attribute is not defined, and no facet
exists for the stopped state, the status is simply not shown; in this way only the
progress of the request is displayed to the user.
+ The text display can be customized depending on the current status.
</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <varname>startText</varname> attribute defines the text shown after
the request has been started and is currently in progress. Set the styles for the text
with the <varname>startStyle</varname> and
<varname>startStyleClass</varname> attributes. Alternatively, use the
<literal>start</literal> facet to customize the text appearance.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <varname>stopText</varname> attribute defines the text shown once
the request is complete. Set the styles for the text with the
<varname>stopStyle</varname> and <varname>stopStyleClass</varname>
attributes. Alternatively, use the <literal>stop</literal> facet to customize
the text appearance.
+ </para>
+ <para>
+ If the <varname>stopText</varname> attribute is not defined, and no
facet exists for the stopped state, the complete status is simply not shown. In this way,
only the progress of the request is displayed to the user, along with any errors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <varname>errorText</varname> attribute defines the text shown when
an error has occurred. Set the styles for the text with the
<varname>errorStyle</varname> and
<varname>errorStyleClass</varname> attributes. Alternatively, use the
<literal>error</literal> facet to customize the text appearance.
+ </para>
+ </listitem>
+ </itemizedlist>
<example
id="exam-Component_Reference-a4jstatus-Basic_a4jstatus_usage">
<title>Basic <sgmltag><a4j:status></sgmltag>
usage</title>
<programlisting language="XML" role="XML"><xi:include
href="extras/exam-Component_Reference-a4jstatus-Basic_a4jstatus_usage.xml_sample"
parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude"
/></programlisting>
@@ -211,23 +251,26 @@
<section id="sect-Component_Reference-a4jstatus-Specifying_a_region">
<title>Specifying a region</title>
<para>
- The <sgmltag><a4j:status></sgmltag> component works for
each Ajax component inside the local region. If no region is defined, every request made
on the page will activate the <sgmltag><a4j:status></sgmltag>
component. Alternatively, the <sgmltag><a4j:status></sgmltag>
component can be linked to specific components in one of two ways:
+ The <sgmltag><a4j:status></sgmltag> component monitors the
status of the region relevant to where it is placed.
</para>
<itemizedlist>
<listitem>
<para>
- The <varname>for</varname> attribute can be used to specify the
component for which the status is to be monitored.
+ If unnamed and placed outside any forms, it monitors the status at the view level.
</para>
</listitem>
<listitem>
<para>
- With an <varname>id</varname> identifier attribute specified for the
<sgmltag><a4j:status></sgmltag>, individual components can have
their statuses monitored by referencing the identifier with their own
<varname>status</varname> attributes.
+ If unnamed and placed inside a form, it monitors the status at the form level.
</para>
</listitem>
</itemizedlist>
- <example
id="exam-Component_Reference-a4jstatus-Updating_a_common_a4jstatus_component">
- <title>Updating a common
<sgmltag><a4j:status></sgmltag> component</title>
- <programlisting language="XML" role="XML"><xi:include
href="extras/exam-Component_Reference-a4jstatus-Updating_a_common_a4jstatus_component.xml_sample"
parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude"
/></programlisting>
+ <para>
+ However, if identified with the <varname>name</varname> attribute, the
<sgmltag><a4j:status></sgmltag> component can monitor any Ajax
component or behavior. Use the <varname>status</varname> attribute on the Ajax
component or behavior to reference the <varname>name</varname> identifier of
the <sgmltag><a4j:status></sgmltag> component.
+ </para>
+ <example
id="exam-Component_Reference-a4jstatus-Updating_a_referenced_a4jstatus_component">
+ <title>Updating a referenced
<sgmltag><a4j:status></sgmltag> component</title>
+ <programlisting language="XML" role="XML"><xi:include
href="extras/exam-Component_Reference-a4jstatus-Updating_a_referenced_a4jstatus_component.xml_sample"
parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude"
/></programlisting>
</example>
</section>
@@ -241,7 +284,7 @@
<term><function>start()</function></term>
<listitem>
<para>
- Start monitoring the status.
+ Switches status to the <literal>start</literal> state.
</para>
</listitem>
</varlistentry>
@@ -249,10 +292,18 @@
<term><function>stop()</function></term>
<listitem>
<para>
- Stop monitoring the status.
+ Switches status to the <literal>stop</literal> state.
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><function>error()</function></term>
+ <listitem>
+ <para>
+ Switches status to the <literal>error</literal> state.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</section>
Modified:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml 2011-03-24
18:55:40 UTC (rev 22303)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml 2011-03-25
03:29:04 UTC (rev 22304)
@@ -13,6 +13,9 @@
<para>
The <sgmltag><rich:autocomplete></sgmltag> component is an
auto-completing input-box with built-in Ajax capabilities. It supports client-side
suggestions, browser-like selection, and customization of the look and feel.
</para>
+ <para>
+ The auto-complete box is a standard JSF <classname>UIInput</classname>
control with added validation.
+ </para>
<!-- TODO not in Final -->
<!--
<para>
@@ -36,11 +39,48 @@
<section id="sect-Component_Reference-richautocomplete-Basic_usage">
<title>Basic usage</title>
<para>
- The <varname>value</varname> attribute stores the text entered by the
user for the auto-complete box. Suggestions shown in the auto-complete list can be
specified using the <varname>autocompleteMethod</varname> attribute, which
points to a collection of suggestions.
+ The <varname>value</varname> attribute stores the text entered by the
user for the auto-complete box. Suggestions shown in the auto-complete list can be
specified using one of two different methods:
</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <varname>autocompleteMethod</varname> attribute points to a method
which returns a list of suggestions according to a supplied prefix.
+ </para>
+ <note>
+ <title><literal>client</literal> and
<literal>lazyClient</literal> modes</title>
+ <para>
+ The prefix is normally ignored in <literal>client</literal> and
<literal>lazyClient</literal> modes. In these modes, the component requests
the suggestion list once only, and performs filtering on the client.
+ </para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+ The <varname>autocompleteList</varname> attribute points to a
collection of suggestions.
+ </para>
+ </listitem>
+ </itemizedlist>
<example
id="exam-Component_Reference-richautocomplete-Defining_suggestion_values">
<title>Defining suggestion values</title>
- <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term>Using the <varname>autocompleteMethod</varname>
attribute</term>
+ <listitem>
+ <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values-0.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ The <sgmltag><rich:autocomplete></sgmltag> component
uses the <methodname>bean.autocomplete</methodname> method to provide
suggestions, based on the entered prefix.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Using the <varname>autocompleteList</varname>
attribute</term>
+ <listitem>
+ <programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values-1.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ The <sgmltag><rich:autocomplete></sgmltag> component
retrieve the suggestion list from <methodname>bean.suggestions</methodname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</example>
<!--
<itemizedlist>
@@ -56,6 +96,35 @@
</itemizedlist>
-->
</section>
+
+ <section
id="sect-Component_Reference-richautocomplete-Submission_modes">
+ <title>Submission modes</title>
+ <para>
+ Use the <varname>mode</varname> attribute to determine how the suggestion
list is requested:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <literal>client</literal> setting pre-loads data to the client and
uses the input to filter the possible suggestions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>ajax</literal> setting fetches suggestions with every
input change using Ajax requests.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>lazyClient</literal> setting pre-loads data to the client
and uses the input to filter the possible suggestions. The filtering does not start until
the input length matches a minimum value. Set the minimum value with the
<varname>minChars</varname> attribute.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>cachedAjax</literal> setting pre-loads data via Ajax
requests when the input length matches a minimum value. Set the minimum value with the
<varname>minChars</varname> attribute. All suggestions are handled on the
client until the input prefix is changed, at which point a new request is made based on
the new input prefix.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
<section
id="sect-Component_Reference-richautocomplete-Interactivity_options">
<title>Interactivity options</title>
@@ -72,8 +141,8 @@
</para>
</section>
- <section
id="sect-Component_Reference-richautocomplete-Customizing_the_filter">
- <title>Customizing the filter</title>
+ <section
id="sect-Component_Reference-richautocomplete-Customizing_the_filter_in_client_and_lazyClient_modes">
+ <title>Customizing the filter in <literal>client</literal> and
<literal>lazyClient</literal> modes</title>
<para>
The <sgmltag><rich:autocomplete></sgmltag> component uses
the JavaScript <function>startsWith()</function> method to create the list of
suggestions. The filtering is performed on the client side. Alternatively, use the
<varname>clientFilter</varname> attribute to specify a custom filtering
function. The custom function must accept two parameters: the
<varname>subString</varname> parameter is the filtering value as typed into
the text box by the user, and the <varname>value</varname> parameter is an
item in the list of suggestions against which the <varname>subString</varname>
must be checked. Each item is iterated through and passed to the function as the
<varname>value</varname> parameter. The custom function must return a boolean
value indicating whether the passed item meets the conditions of the filter, and the
suggestion list is constructed from successful items.
</para>
@@ -272,7 +341,7 @@
<section
id="sect-Component_Reference-richcalendar-Behavior_and_appearance">
<title>Behavior and appearance</title>
<para>
- The <sgmltag><rich:calendar></sgmltag> component is
presented as a pop-up by default, appearing as a text field with a button to expand the
full pop-up calendar. To render the calendar in-line on the page instead, set
<code>popup="false</code>. This displays the full calendar without the
text field or display button.
+ The <sgmltag><rich:calendar></sgmltag> component is
presented as a pop-up by default, appearing as a text field with a button to expand the
full pop-up calendar. To render the calendar in-line on the page instead, set
<code>popup="false</code>. This displays the full calendar without the
text field and display button.
</para>
<para>
To add keyboard support for manual input, set
<code>enableManualInput="true"</code>. To disable the calendar from
any user input, set <code>disabled="true"</code>.
@@ -313,14 +382,19 @@
</listitem>
<listitem>
<para>
- <literal>select</literal>, the default setting, which scrolls the
calendar to the current month and selects today's date; and
+ <literal>select</literal>, the default setting, which scrolls the
calendar to the current month and selects the date; and
</para>
</listitem>
<listitem>
<para>
- <literal>scroll</literal>, which scrolls the calendar to the current
month but does not select today's date.
+ <literal>scroll</literal>, which scrolls the calendar to the month but
does not select the date.
</para>
</listitem>
+ <listitem>
+ <para>
+ <literal>inactive</literal>, which displays the date but performs no
action when clicked.
+ </para>
+ </listitem>
</itemizedlist>
<para>
To make the entire calendar read-only, set
<code>readonly="true"</code>. This allows months and years to be
browsed through with the arrow controls, but dates and times cannot be selected.
@@ -351,6 +425,9 @@
<para>
The <sgmltag><rich:calendar></sgmltag> component can
additionally allow a time of day to be specified with the date. After selecting a date the
option to set a time becomes available. The default time can be set with the
<varname>defaultTime</varname> attribute. If the time is altered and a new
date is selected, it will not reset unless
<code>resetTimeOnDateSelect="true"</code> is specified.
</para>
+ <para>
+ The date selection feature is activated if the time is present in the
<varname>datePattern</varname> attribute for the calendar.
+ </para>
<note>
<title>Support for seconds</title>
<para>
@@ -455,10 +532,10 @@
The look and feel of the <sgmltag><rich:calendar></sgmltag>
component can be customized through the use of a data model on the server side. The
component supports two different ways of loading data from the server side through
defining the <varname>mode</varname> attribute.
</para>
<para>
- When the <varname>mode</varname> attribute is not specified, the
component uses the <literal>client</literal> mode. The
<literal>client</literal> mode loads an initial portion of data within a set
date range. The range can be defined by using the
<varname>preloadDateRangeBegin</varname> and
<varname>preloadDateRangeEnd</varname> attributes. Additional data requests
are not sent.
+ When the <varname>mode</varname> attribute is not specified, the
component uses the <literal>client</literal> mode. The
<literal>client</literal> mode loads an initial portion of data within a set
date range. The range can be defined by using the
<varname>preloadDateRangeBegin</varname> and
<varname>preloadDateRangeEnd</varname> attributes. Additional data requests
for months outside the range are not sent.
</para>
<para>
- Alternatively, with <code>mode="ajax"</code> the
<sgmltag><rich:calendar></sgmltag> requests portions of data for
rendering from a special data model. The data model can be defined through the
<varname>dataModel</varname> attribute, which points to an object that
implements the <classname>CalendarDataModel</classname> interface. If the
<varname>dataModel</varname> attribute is not defined or has a value of
<literal>null</literal>, the <literal>ajax</literal> mode
functions the same as the <literal>client</literal> mode.
+ Alternatively, with <code>mode="ajax"</code> the
<sgmltag><rich:calendar></sgmltag> requests portions of data
from the data model every time the month is switched. The data model can be defined
through the <varname>dataModel</varname> attribute, which points to an object
that implements the <classname>CalendarDataModel</classname> interface. If the
<varname>dataModel</varname> attribute is not defined or has a value of
<literal>null</literal>, the <literal>ajax</literal> mode
functions the same as the <literal>client</literal> mode.
</para>
</section>
@@ -748,13 +825,13 @@
<section id="sect-Component_Reference-Rich_inputs-richfileUpload">
<title><sgmltag><rich:fileUpload></sgmltag></title>
<para>
- The <sgmltag><rich:fileUpload></sgmltag> component allows
the user to upload files to a server. It features multiple uploads, progress bars,
restrictions on file types, and restrictions on sizes to be uploaded.
+ The <sgmltag><rich:fileUpload></sgmltag> component allows
the user to upload files to a server. It features multiple uploads, progress bars,
restrictions on file types, and restrictions on sizes of the files to be uploaded.
</para>
<section id="sect-Component_Reference-richfileUpload-Basic_usage">
<title>Basic usage</title>
<para>
- Basic usage requires the <varname>fileUploadListener</varname> attribute.
Use the attribute to call a function on the server side after each file is uploaded.
+ Basic usage requires the <varname>fileUploadListener</varname> attribute.
Use the attribute to reference a listener function on the server side after each file is
uploaded. The listener should process files as required, such as storing them in the
<filename>session/db/filesystem/</filename> directory. The component itself
does not store uploaded files, so if the listener is not implemented they are not stored
anywhere.
</para>
<example id="exam-Component_Reference-richfileUpload-Basic_usage">
<title>Basic usage</title>
@@ -765,10 +842,10 @@
<section id="sect-Component_Reference-richfileUpload-Upload_settings">
<title>Upload settings</title>
<para>
- Files are uploaded to either the temporary folder (different for each operating
system) or to <acronym>RAM</acronym> (random-access memory), depending on the
value of the <parameter>org.richfaces.fileUpload.createTempFile</parameter>
parameter of the <filename>web.xml</filename> settings file for the project.
If the parameter is set to <literal>true</literal>, the files are uploaded to
the temporary folder.
+ Files are uploaded to either the temporary folder (different for each operating
system) or to <acronym>RAM</acronym> (random-access memory), depending on the
value of the <parameter>org.richfaces.fileUpload.createTempFiles</parameter>
context parameter of the <filename>web.xml</filename> settings file for the
project. If the parameter is set to <literal>true</literal>, the files are
uploaded to the temporary folder.
</para>
<para>
- To limit the maximum size of the uploaded files, define the byte size with the
<parameter>org.richfaces.fileUpload.maxRequestSize</parameter> parameter of
the <filename>web.xml</filename> settings file for the project.
+ To limit the maximum size of the uploaded files, define the byte size with the
<parameter>org.richfaces.fileUpload.maxRequestSizes</parameter> context
parameter of the <filename>web.xml</filename> settings file for the project.
</para>
</section>
@@ -842,7 +919,7 @@
</itemizedlist>
-->
<para>
- The progress of a file upload operation can be represented using either a referencing
<sgmltag><rich:progressBar></sgmltag> component, or the
<literal>progress</literal> facet. Refer to <xref
linkend="sect-Component_Reference-Output_and_messages-richprogressBar" /> for
details on the <sgmltag><rich:progressBar></sgmltag> component.
+ The <sgmltag><rich:fileUpload></sgmltag> component provides
a built-in progress bar to indicate the progress of each file that is uploaded. This
progress bar can be replaced with a
<sgmltag><rich:progressBar></sgmltag> component added to the
<literal>progress</literal> facet. Refer to <xref
linkend="sect-Component_Reference-Output_and_messages-richprogressBar" /> for
details on the <sgmltag><rich:progressBar></sgmltag> component.
</para>
<para>
To disable the <sgmltag><rich:fileUpload></sgmltag>
component, use the <varname>disabled</varname> attribute.
@@ -936,15 +1013,18 @@
<section id="sect-Component_Reference-richinplaceInput-Basic_usage">
<title>Basic usage</title>
<para>
- Basic usage requires the <varname>value</varname> attribute to point to
the expression for the current value of the component.
+ Basic usage requires the <varname>value</varname> attribute to point to
the expression for the current value of the component. Validation and conversion rules for
the JSF <classname>UIInput</classname> control apply as usual.
</para>
</section>
<section
id="sect-Component_Reference-richinplaceInput-Interactivity_options">
<title>Interactivity options</title>
<para>
- When in the initial <emphasis>view</emphasis> state, the starting label
can be set using the <varname>defaultLabel</varname> attribute. Once the user
has entered text, the label is stored in the model specified by the
<varname>value</varname> attribute. The use of the default label and value is
shown in <xref
linkend="exam-Component_Reference-richinplaceInput-Default_label_and_value"
/>.
+ When in the initial <emphasis>view</emphasis> state, the starting label
can be set using the <varname>defaultLabel</varname> attribute. Alternatively,
if the initial value is already set through the <varname>value</varname>
attribute, this is displayed instead.
</para>
+ <para>
+ Once the user has entered text, the label is stored in the model specified by the
<varname>value</varname> attribute. The use of the default label and value is
shown in <xref
linkend="exam-Component_Reference-richinplaceInput-Default_label_and_value"
/>.
+ </para>
<example
id="exam-Component_Reference-richinplaceInput-Default_label_and_value">
<title>Default label and value</title>
<programlisting language="XML" role="XML"><xi:include
parse="text"
href="extras/exam-Component_Reference-richinplaceInput-Default_label_and_value.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
@@ -953,11 +1033,28 @@
By default, the event to switch the component to the
<emphasis>edit</emphasis> state is a single mouse click. This can be changed
using the <varname>editEvent</varname> attribute to specify a different
event.
</para>
<para>
- The user can confirm and save their input by pressing the
<keycap>Enter</keycap> key or cancel by pressing the
<keycap>Esc</keycap> key. Alternatively, buttons for confirming or canceling
can be added to the component by setting
<code>showControls="true"</code>.
- <!-- TODO not in M4
- These buttons can be positioned using the
<varname>controlsHorizontalPosition</varname> attribute with settings of
<literal>left</literal>, <literal>right</literal>, or
<literal>center</literal>, and the
<varname>controlsVerticalPosition</varname> attribute with settings
<literal>bottom</literal>, <literal>center</literal>, or
<literal>top</literal>. The confirmation control icons can be altered using
the <varname>saveControlIcon</varname> and
<varname>cancelControlIcon</varname>. Further customization is possible
through the use of facets.
- -->
+ The user can confirm and save their input in multiple ways:
</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ By default, pressing the <keycap>Enter</keycap> key will confirm and
save the input.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <code>showControls="true"</code> is set, buttons for
confirming or canceling are added to the component.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If <code>saveOnBlur="true"</code> is set, the input is saved
on the component's blur event.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Pressing the <keycap>Esc</keycap> key cancels editing in all cases.
+ </para>
</section>
<!-- TODO not in M4
@@ -1049,7 +1146,7 @@
<term><function>getInput()</function></term>
<listitem>
<para>
- Return the input entered into the control by the user.
+ Return the DOM element for the input.
</para>
</listitem>
</varlistentry>
@@ -1097,8 +1194,28 @@
<section id="sect-Component_Reference-Rich_inputs-richinplaceSelect">
<title><sgmltag><rich:inplaceSelect></sgmltag></title>
<para>
- The <sgmltag><rich:inplaceSelect></sgmltag> component is
similar to the <sgmltag><rich:inplaceInput></sgmltag> component,
except that the <sgmltag><rich:inplaceSelect></sgmltag>
component uses a drop-down selection box to enter text instead of a regular text field.
Changes can be rendered either in-line or for the whole block, and inputs can be focused
with keyboard navigation. The component has three functional states: the
<emphasis>view</emphasis> state, where the component displays its initial
setting, such as "click to edit"; the <emphasis>edit</emphasis>
state, where the user can select a value from a drop-down list; and the
"changed" state, where the new value for the component has been confirmed but
can be edited again if required.
+ The <sgmltag><rich:inplaceSelect></sgmltag> component is
similar to the <sgmltag><rich:inplaceInput></sgmltag> component,
except that the <sgmltag><rich:inplaceSelect></sgmltag>
component uses a drop-down selection box to enter text instead of a regular text field.
Changes can be rendered either in-line or for the whole block, and inputs can be focused
with keyboard navigation. The component is based on the JSF
<classname>UISelectOne</classname> component, so all the standard rules for
value definition, processing, conversion, and validation apply.
</para>
+ <para>
+ The component has three functional states:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ When in the <emphasis>view</emphasis> state, the component displays its
initial setting, such as "click to edit".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When in the <emphasis>edit</emphasis> state, the user can select a value
from a drop-down list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When in the <emphasis>changed</emphasis> state, the new value for the
component has been confirmed, but it can be edited again if required.
+ </para>
+ </listitem>
+ </itemizedlist>
<figure
id="figu-Component_Reference-richinplaceSelect-richinplaceSelect">
<title><sgmltag><rich:inplaceSelect></sgmltag></title>
<mediaobject>
@@ -1127,18 +1244,18 @@
<section
id="sect-Component_Reference-richinplaceSelect-Interactivity_options">
<title>Interactivity options</title>
<para>
- When in the initial <emphasis>view</emphasis> state, the starting label
can be set using the <varname>defaultLabel</varname> attribute, such as
<code>defaultLabel="click to edit"</code>.
+ When in the initial <emphasis>view</emphasis> state, the starting label
can be set using the <varname>defaultLabel</varname> attribute, such as
<code>defaultLabel="click to edit"</code>. Alternatively, if the
initial value is already set through the <varname>value</varname> attribute,
this is displayed instead.
</para>
<para>
By default, the event to switch the component to the
<emphasis>edit</emphasis> state is a single mouse click. This can be changed
using the <varname>editEvent</varname> attribute to specify a different event.
When switching to <emphasis>edit</emphasis> mode, the drop-down list of
possible values will automatically be displayed; this can be deactivated by setting
<code><varname>openOnEdit</varname>="false"</code>.
</para>
<para>
- Once a new value for the control is saved, the state switches to the
"changed" state. Saving a new value for the control can be performed in three
different ways:
+ Once a new value for the control is saved, the state switches to the
"changed" state. Saving a new value for the control can be performed in a number
of ways:
</para>
<itemizedlist>
<listitem>
<para>
- Once the user selects an item from the drop-down list, the item is saved as the new
control value. This is the default setting.
+ Once the user selects an item from the drop-down list, the item is saved as the new
control value. This is the default setting. If
<code>saveOnSelect="false"</code> is set, the component applies the
selected item but remains in the <emphasis>edit</emphasis> state so a
different selection could be chosen. The value is then applied when the
<keycap>Enter</keycap> key is pressed.
</para>
</listitem>
<listitem>
@@ -1152,6 +1269,9 @@
</para>
</listitem>
</itemizedlist>
+ <para>
+ Pressing the <keycap>Esc</keycap> key cancels editing in all cases.
+ </para>
<!-- TODO not in M4 -->
<!--
<para>
@@ -1348,7 +1468,7 @@
<section
id="sect-Component_Reference-richinputNumberSlider-Basic_usage">
<title>Basic usage</title>
<para>
- Basic use of the component with no attributes specified will render a slider with a
minimum value of 0, a maximum of 100, and a gradient step of 1, together with a text field
for typing the desired numerical value. The slider is labeled with the minimum and maximum
boundary values, and a tool-tip showing the current value is shown while sliding the
slider. The <varname>value</varname> attribute is used for storing the
currently selected value of the slider.
+ Basic use of the component with no attributes specified will render a slider with a
minimum value of 0, a maximum of 100, and a gradient step of 1, together with a text field
for typing the desired numerical value. The slider is labeled with the minimum and maximum
boundary values, and a tool-tip showing the current value is shown while sliding the
slider. The <varname>value</varname> attribute is used for storing the
currently selected value of the slider. Standard conversion and validation for the JSF
<classname>UIInput</classname> component is applied.
</para>
</section>
@@ -1568,7 +1688,7 @@
<section id="sect-Component_Reference-Rich_inputs-richselect">
<title><sgmltag><rich:select></sgmltag></title>
<para>
- The <sgmltag><rich:select></sgmltag> component provides a
drop-down list box for selecting a single value from multiple options. The component
supports keyboard navigation and can optionally accept typed input. The
<sgmltag><rich:select></sgmltag> component functions similarly
to the JavaServer Faces <sgmltag><h:selectOneMenu></sgmltag>
component.
+ The <sgmltag><rich:select></sgmltag> component provides a
drop-down list box for selecting a single value from multiple options. The
<sgmltag><rich:select></sgmltag> component can be configured as
a combo-box, where it will accept typed input. The component also supports keyboard
navigation. The <sgmltag><rich:select></sgmltag> component
functions similarly to the JSF <classname>UISelectOne</classname> component.
</para>
<figure id="figu-Component_Reference-richselect-richselect">
@@ -1588,7 +1708,7 @@
<section id="sect-Component_Reference-richselect-Basic_usage">
<title>Basic usage</title>
<para>
- Simple usage of the <sgmltag><rich:select></sgmltag>
component does not need any attributes declared, but child tags to manage the list of
selections are required. The child tags can either be a number of
<sgmltag><f:selectItem></sgmltag> tags or a
<sgmltag><f:selectItems></sgmltag> tag which points to a data
model containing a list of selection items. The <varname>value</varname>
attribute is used to store the current selection.
+ Simple usage of the <sgmltag><rich:select></sgmltag>
component requires the <varname>value</varname> attribute to store the
selected value. Additionally, child tags to manage the list of selections are required.
The child tags can either be a number of
<sgmltag><f:selectItem></sgmltag> tags or a
<sgmltag><f:selectItems></sgmltag> tag which points to a data
model containing a list of selection items. The <varname>value</varname>
attribute is used to store the current selection.
</para>
<example id="exam-Component_Reference-richselect-Selection_items">
<title>Selection items</title>
@@ -1612,24 +1732,17 @@
</para>
</section>
- <section id="sect-Component_Reference-richselect-Advanced_options">
- <title>Advanced options</title>
- <para>
- Use the <varname>defaultLabel</varname> attribute to set a place-holder
label, such as <code>defaultLabel="select an option"</code>.
- </para>
- <para>
- Server-side processing occurs in the same manner as for an
<sgmltag><h:selectOneMenu></sgmltag> component. As such, custom
objects used for selection items should use the same converters as for an
<sgmltag><h:selectOneMenu></sgmltag> component.
- </para>
- </section>
-
<section id="sect-Component_Reference-richselect-Using_manual_input">
<title>Using manual input</title>
<para>
- Selection lists can allow the user to type into a text field to scroll through or
filter the list. By default, the
<sgmltag><rich:select></sgmltag> component functions as a
drop-down list with no manual input. To add keyboard support for manual input, set
<code>enableManualInput="true"</code>.
+ The <sgmltag><rich:select></sgmltag> component allows the
user to type into a text field to scroll through or filter the list. By default, the
<sgmltag><rich:select></sgmltag> component functions as a
drop-down list with no manual input. To add keyboard support for manual input, set
<code>enableManualInput="true"</code>.
</para>
<para>
Once the user begins typing, the first available matching option is highlighted. If
the typed text does not match any values in the list, no value is chosen and the drop-down
list displays as empty. Other keyboard interaction remains the same as the basic drop-down
list.
</para>
+ <para>
+ The standard JSF <sgmltag><h:selectOne></sgmltag> component
does not offer this extended keyboard support. However, since the
<sgmltag><rich:select></sgmltag> component is still based on the
JSF <classname>UISelectOne</classname> component, it will not accept a value
that does not match any items in the drop-down list. If an invalid value is entered, it is
highlighted as erroneous and validation messages appear with the submission.
+ </para>
<!-- TODO: not in M4 -->
<!--
<para>
@@ -1637,6 +1750,16 @@
</para>
-->
</section>
+
+ <section id="sect-Component_Reference-richselect-Advanced_options">
+ <title>Advanced options</title>
+ <para>
+ Use the <varname>defaultLabel</varname> attribute to set a place-holder
label, such as <code>defaultLabel="select an option"</code>.
+ </para>
+ <para>
+ Server-side processing occurs in the same manner as for an
<sgmltag><h:selectOneMenu></sgmltag> component. As such, custom
objects used for selection items should use the same converters as for an
<sgmltag><h:selectOneMenu></sgmltag> component.
+ </para>
+ </section>
<section id="sect-Component_Reference-richselect-JavaScript_API">
<title>JavaScript API</title>
Modified:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jlog-a4jlog_example.xml_sample
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jlog-a4jlog_example.xml_sample 2011-03-24
18:55:40 UTC (rev 22303)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jlog-a4jlog_example.xml_sample 2011-03-25
03:29:04 UTC (rev 22304)
@@ -1 +1 @@
-<a4j:log level="ALL" popup="false" width="400"
height="200" />
+<a4j:log level="ALL" mode="inline" />
Deleted:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jstatus-Updating_a_common_a4jstatus_component.xml_sample
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jstatus-Updating_a_common_a4jstatus_component.xml_sample 2011-03-24
18:55:40 UTC (rev 22303)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jstatus-Updating_a_common_a4jstatus_component.xml_sample 2011-03-25
03:29:04 UTC (rev 22304)
@@ -1,38 +0,0 @@
-<a4j:region id="extr">
- <h:form>
- <h:outputText value="Status:" />
- <a4j:status id="commonstatus" startText="In Progress...."
stopText="" />
-
- <a4j:region id="intr">
- <h:panelGrid columns="2">
- <h:outputText value="Name" />
- <h:inputText id="name"
value="#{userBean.name}">
- <a4j:support event="keyup" reRender="out"
status="commonstatus" />
- </h:inputText>
-
- <h:outputText value="Job" />
- <h:inputText id="job" value="#{userBean.job}">
- <a4j:support event="keyup" reRender="out"
status="commonstatus" />
- </h:inputText>
-
- <h:panelGroup />
-
- </h:panelGrid>
- </a4j:region>
- <a4j:region>
- <br />
- <rich:spacer height="5" />
- <b><h:outputText id="out"
- value="Name: #{userBean.name}, Job: #{userBean.job}"
/></b>
- <br />
- <rich:spacer height="5" />
- <br />
- <a4j:commandButton ajaxSingle="true" value="Clean Up
Form"
- reRender="name, job, out" status="commonstatus">
- <a4j:actionparam name="n" value=""
assignTo="#{userBean.name}" />
- <a4j:actionparam name="j" value=""
assignTo="#{userBean.job}" />
- </a4j:commandButton>
- </a4j:region>
-
- </h:form>
-</a4j:region>
Copied:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jstatus-Updating_a_referenced_a4jstatus_component.xml_sample
(from rev 22292,
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jstatus-Updating_a_common_a4jstatus_component.xml_sample)
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jstatus-Updating_a_referenced_a4jstatus_component.xml_sample
(rev 0)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-a4jstatus-Updating_a_referenced_a4jstatus_component.xml_sample 2011-03-25
03:29:04 UTC (rev 22304)
@@ -0,0 +1,25 @@
+<rich:panel>
+ <f:facet name="header">
+ <h:outputText value="User Details Panel" />
+ </f:facet>
+ <h:panelGrid columns="3">
+ <h:outputText value="User name:" />
+ <h:inputText value="#{userBean.name}">
+ <a4j:ajax status="nameStatus" event="keyup" />
+ </h:inputText>
+ <a4j:status name="nameStatus">
+ <f:facet name="start">
+ <h:graphicImage value="/images/ai.gif" />
+ </f:facet>
+ </a4j:status>
+ <h:outputText value="Address:" />
+ <h:inputText value="#{userBean.address}">
+ <a4j:ajax status="addressStatus" event="keyup" />
+ </h:inputText>
+ <a4j:status name="addressStatus">
+ <f:facet name="start">
+ <h:graphicImage value="/images/ai.gif" />
+ </f:facet>
+ </a4j:status>
+ </h:panelGrid>
+</rich:panel>
Added:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values-0.xml_sample
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values-0.xml_sample
(rev 0)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values-0.xml_sample 2011-03-25
03:29:04 UTC (rev 22304)
@@ -0,0 +1 @@
+<rich:autocomplete value="#{bean.state}"
autocompleteMethod="#{bean.autocomplete}" />
Copied:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values-1.xml_sample
(from rev 22292,
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values.xml_sample)
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values-1.xml_sample
(rev 0)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values-1.xml_sample 2011-03-25
03:29:04 UTC (rev 22304)
@@ -0,0 +1 @@
+<rich:autocomplete value="#{bean.state}"
autocompleteList="#{bean.suggestions}" />
Deleted:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values.xml_sample
===================================================================
---
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values.xml_sample 2011-03-24
18:55:40 UTC (rev 22303)
+++
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richautocomplete-Defining_suggestion_values.xml_sample 2011-03-25
03:29:04 UTC (rev 22304)
@@ -1 +0,0 @@
-<rich:autocomplete value="#{bean.state}"
autocompleteMethod="#{bean.suggestions}" />
Added:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-a4jlog-a4jlog_example.png
===================================================================
(Binary files differ)
Property changes on:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-a4jlog-a4jlog_example.png
___________________________________________________________________
Added: svn:mime-type
+ application/octet-stream