[richfaces-svn-commits] JBoss Rich Faces SVN: r19626 - in modules/docs/trunk: Component_Reference/src/main/docbook/en-US and 3 other directories.

Author: SeanRogers Date: 2010-10-21 02:34:43 -0400 (Thu, 21 Oct 2010) New Revision: 19626 Added: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richcalendar-Basic_usage.xml_sample modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselectOne-Selection_items.xml_sample modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Advanced_tool-tip_usage.xml_sample modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Attaching_the_tool-tip.xml_sample modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Defining_tool-tip_content-0.xml_sample modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Defining_tool-tip_content-1.xml_sample modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Unattached_tool-tips.xml_sample modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richcalendar-Pop-up_positioning.png modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richcalendar-richcalendar.png modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richselectOne-richselectOne.png modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richtoolTip-richtoolTip.png Modified: modules/docs/trunk/ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Output_and_messages.xml modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml modules/docs/trunk/Migration_Guide/src/main/docbook/en-US/Changes_and_new_features.xml Log: Merged revisions 19591,19610-19612,19623-19624 via svnmerge from http://svn.jboss.org/repos/richfaces/modules/docs/branches/m4 ....... r19591 | SeanRogers | 2010-10-18 16:53:34 +1000 (Mon, 18 Oct 2010) | 1 line Started rich:selectOne and rich:calendar ....... r19610 | SeanRogers | 2010-10-20 13:30:01 +1000 (Wed, 20 Oct 2010) | 1 line Draft of richselectOne complete ....... r19611 | SeanRogers | 2010-10-20 13:31:28 +1000 (Wed, 20 Oct 2010) | 1 line Added selectOne extras ....... r19612 | SeanRogers | 2010-10-20 16:14:32 +1000 (Wed, 20 Oct 2010) | 1 line Draft of rich:calendar complete ....... r19623 | SeanRogers | 2010-10-21 11:32:01 +1000 (Thu, 21 Oct 2010) | 1 line Draft of rich:calendar complete ....... r19624 | SeanRogers | 2010-10-21 16:14:48 +1000 (Thu, 21 Oct 2010) | 1 line Draft of rich:toolTip complete ....... Property changes on: modules/docs/trunk ___________________________________________________________________ Name: svnmerge-integrated - /modules/docs/branches/m4:1-19589 + /modules/docs/branches/m4:1-19625 Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Output_and_messages.xml =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Output_and_messages.xml 2010-10-21 06:29:05 UTC (rev 19625) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Output_and_messages.xml 2010-10-21 06:34:43 UTC (rev 19626) @@ -369,10 +369,10 @@ </example> </section> - <section id="sect-Component_Reference-richaccordion-Update_mode"> + <section id="sect-Component_Reference-richprogressBar-Update_mode"> <title>Update mode</title> <para> - The mode for updating the progress bar is determined by the <code>mode</code> attribute, which can have one of the following values: + The mode for updating the progress bar is determined by the <varname>mode</varname> attribute, which can have one of the following values: </para> <variablelist> <varlistentry> @@ -393,16 +393,256 @@ </varlistentry> </variablelist> </section> + + <section id="sect-Component_Reference-richprogressBar-Reference_data"> + <title>Reference data</title> + <itemizedlist> + <listitem> + <para> + <parameter>component-type</parameter>: <classname>org.richfaces.ProgressBar</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>component-class</parameter>: <classname>org.richfaces.component.html.HtmlProgressBar</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>component-family</parameter>: <classname>org.richfaces.component.ProgressBar</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>renderer-type</parameter>: <classname>org.richfaces.renderkit.ProgressBarRenderer</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>tag-class</parameter>: <classname>org.richfaces.taglib.ProgressBarTag</classname> + </para> + </listitem> + </itemizedlist> + </section> </section> <!-- <rich:toolTip> --> - <!-- <section id="sect-Component_Reference-Output_and_messages-richtoolTip"> <title><sgmltag>&lt;rich:toolTip&gt;</sgmltag></title> <para> - Incomplete + The <sgmltag>&lt;rich:toolTip&gt;</sgmltag> component provides an informational tool-tip. The tool-tip can be attached to any control and is displayed when hovering the mouse cursor over the control. </para> + <figure id="figu-Component_Reference-richtoolTip-richtoolTip"> + <title><sgmltag>&lt;rich:toolTip&gt;</sgmltag></title> + <mediaobject> + <imageobject> + <imagedata fileref="images/figu-Component_Reference-richtoolTip-richtoolTip.png" format="PNG" /> + </imageobject> + <textobject> + <para> + A <sgmltag>&lt;rich:toolTip&gt;</sgmltag> component, displayed while hovering the mouse cursor over a button control. + </para> + </textobject> + </mediaobject> + </figure> + + <section id="sect-Component_Reference-richtoolTip-Basic_usage"> + <title>Basic usage</title> + <para> + For basic usage, define the tool-tip text using the <varname>value</varname> attribute. The <sgmltag>&lt;rich:toolTip&gt;</sgmltag> component is then automatically attached to the parent element, and is usually shown when the mouse cursor hovers. + </para> + <para> + Alternatively, the content of the tool-tip can be defined inside the <sgmltag>&lt;rich:toolTip&gt;</sgmltag> tags, and the <varname>value</varname> attribute is not used. This allows HTML tags to be used to define the content, and provides for rich content such as images, links, buttons, and other RichFaces components. + </para> + <example id="exam-Component_Reference-richtoolTip-Defining_tool-tip_content"> + <title>Defining tool-tip content</title> + <variablelist> + <varlistentry> + <term>Basic content</term> + <listitem> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-richtoolTip-Defining_tool-tip_content-0.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </listitem> + </varlistentry> + <varlistentry> + <term>Rich content</term> + <listitem> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-richtoolTip-Defining_tool-tip_content-1.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </listitem> + </varlistentry> + </variablelist> + </example> + </section> + + <section id="sect-Component_Reference-richtoolTip-Attaching_the_tool-tip_to_another_component"> + <title>Attaching the tool-tip to another component</title> + <para> + If not otherwise specified, the tool-tip is attached to the parent element in which it is defined. The <varname>for</varname> attribute is used to attach the tool-tip to another component, pointing to the target component's <varname>id</varname> identifier. This allows the <sgmltag>&lt;rich:toolTip&gt;</sgmltag> component to be specified outside the target element. This approach is demonstrated in <xref linkend="exam-Component_Reference-richtoolTip-Attaching_the_tool-tip" />. + </para> + <example id="exam-Component_Reference-richtoolTip-Attaching_the_tool-tip"> + <title>Attaching the tool-tip</title> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-richtoolTip-Attaching_the_tool-tip.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </example> + <para> + The <sgmltag>&lt;rich:toolTip&gt;</sgmltag> component can alternatively be left unattached, and is instead invoked through an event handler on the target component. To leave the <sgmltag>&lt;rich:toolTip&gt;</sgmltag> component unattached, set <code>attached="false"</code>, and define the event handler to trigger the tool-tip on the target component. This approach is demonstrated in <xref linkend="exam-Component_Reference-richtoolTip-Unattached_tool-tips" />. When leaving the <sgmltag>&lt;rich:toolTip&gt;</sgmltag> component unattached, ensure it has an <varname>id</varname> identifier defined. If the <sgmltag>&lt;rich:toolTip&gt;</sgmltag> component is nested inside the target element, it must be the last child. If it is defined outside the target element, it must be nested in an <sgmltag>&lt;a4j:form&gt;</sgmltag> component. + </para> + <example id="exam-Component_Reference-richtoolTip-Unattached_tool-tips"> + <title>Unattached tool-tips</title> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-richtoolTip-Unattached_tool-tips.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </example> + </section> + + <section id="sect-Component_Reference-richtoolTip-Appearance"> + <title>Appearance</title> + <para> + By default, the <sgmltag>&lt;rich:toolTip&gt;</sgmltag> component is positioned intelligently based on the position of the mouse cursor. Use the <varname>direction</varname> attribute to specify a corner of the target component at which to display the tool-tip instead. Possible values include <literal>top-left</literal>, <literal>top-right</literal>, <literal>bottom-left</literal>, and <literal>bottom-right</literal>. Use the <varname>horizontalOffset</varname> and <varname>verticalOffset</varname> attributes to specify the horizontal offset and vertical offset at which to display the tool-tip. + </para> + <para> + Use the <varname>hideEvent</varname> attribute to specify when the tool-tip is hidden. The default value is <literal>none</literal>, so the tool-tip remains shown. However, it can be linked to an event on the target component, such as the <literal>mouseout</literal> event. + </para> + <para> + Set <code>followMouse="true"</code> to cause the tool-tip to follow the user's mouse movements. + </para> + <para> + Advanced appearance features are demonstrated in <xref linkend="exam-Component_Reference-richtoolTip-Advanced_tool-tip_usage" />. + </para> + </section> + + <section id="sect-Component_Reference-richtoolTip-Update_mode"> + <title>Update mode</title> + <para> + The mode for updating the tool-tip is determined by the <varname>mode</varname> attribute, which can have one of the following values: + </para> + <variablelist> + <varlistentry> + <term><literal>ajax</literal></term> + <listitem> + <para> + The tool-tip content is requested from the server with every activation. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>client</literal></term> + <listitem> + <para> + The tool-tip content is rendered once on the server. An external submit causes the content to re-render. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + When using <code>mode="ajax"</code>, define the <literal>defaultContent</literal> facet. The tool-tip displays the content of the <literal>defaultContent</literal> facet while loading the actual content from the server. + </para> + <example id="exam-Component_Reference-richtoolTip-Advanced_tool-tip_usage"> + <title>Advanced tool-tip usage</title> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-richtoolTip-Advanced_tool-tip_usage.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </example> + </section> + + <section id="sect-Component_Reference-richtoolTip-richtoolTip_client-side_events"> + <title><sgmltag>&lt;rich:toolTip&gt;</sgmltag> client-side events</title> + <para> + The <sgmltag>&lt;rich:toolTip&gt;</sgmltag> component supports the following client-side events: + </para> + <variablelist> + <varlistentry> + <term><literal>onclick</literal></term> + <listitem> + <para> + This event is activated when the tool-tip is clicked with the mouse. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>ondblclick</literal></term> + <listitem> + <para> + This event is activated when the tool-tip is double-clicked with the mouse. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>onmouseout</literal></term> + <listitem> + <para> + This event is activated when the mouse cursor leaves the tool-tip. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>onmousemove</literal></term> + <listitem> + <para> + This event is activated when the mouse cursor moves over the tool-tip. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>onmouseover</literal></term> + <listitem> + <para> + This event is activated when the mouse cursor hovers over the tool-tip. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>onshow</literal></term> + <listitem> + <para> + This event is activated when the tool-tip is shown. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>oncomplete</literal></term> + <listitem> + <para> + This event is activated when the tool-tip is completed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>onhide</literal></term> + <listitem> + <para> + This event is activated when the tool-tip is hidden. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section id="sect-Component_Reference-richtoolTip-Reference_data"> + <title>Reference data</title> + <itemizedlist> + <listitem> + <para> + <parameter>component-type</parameter>: <classname>org.richfaces.component.toolTip</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>component-class</parameter>: <classname>org.richfaces.component.html.HtmlToolTip</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>component-family</parameter>: <classname>org.richfaces.component.toolTip</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>renderer-type</parameter>: <classname>org.richfaces.renderkit.html.toolTipRenderer</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>tag-class</parameter>: <classname>org.richfaces.taglib.HtmlToolTipTag</classname> + </para> + </listitem> + </itemizedlist> + </section> + </section> - --> </chapter> 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 2010-10-21 06:29:05 UTC (rev 19625) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml 2010-10-21 06:34:43 UTC (rev 19626) @@ -11,93 +11,188 @@ </para> </important> <para> - This chapter details those components which act as panels and containers to hold groups of other components. + This chapter details rich components for user input and interaction. </para> - <!-- TODO not in M3 --> - <!-- - <para> - This chapter details rich components for user input and interaction. - </para> + <!-- <rich:calendar> --> <section id="sect-Component_Reference-Rich_inputs-richcalendar"> <title><sgmltag>&lt;rich:calendar&gt;</sgmltag></title> <para> The <sgmltag>&lt;rich:calendar&gt;</sgmltag> component allows the user to enter a date and time through an in-line or pop-up calendar. The pop-up calendar can navigate through months and years, and its look and feel can be highly customized. </para> - <para> - The <sgmltag>&lt;rich:calendar&gt;</sgmltag> component supports two different ways of loading data through defining the <varname>mode</varname> attribute. When not specified, the component uses <literal>client</literal> mode, which 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. Alternatively, with <code>mode="ajax"</code> the <sgmltag>&lt;rich:calendar&gt;</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</liter! al> mode. - </para> - <para> - The <sgmltag>&lt;rich:calendar&gt;</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. Specifying <code>popup="false</code> will render the calendar in-line on the page instead, which displays the full calendar without the text field or display button. The appearance of the display button can be altered from the standard calendar icon by defining the <varname>buttonIcon</varname> and <varname>buttonIconDisabled</varname> attributes to replace the icon with a specified file, or by defining the <varname>buttonLabel</varname> attribute to display text on the button without an icon. If <varname>buttonLabel</varname> is specified then both <varname>buttonIcon</varname> and <varname>buttonIconDisabled</varname> attributes are ignored. The text field box can also be hidden by setting <code>showInput="false"</code>. - </para> - <para> - The position at which the pop-up calendar displays relative to the text field and button can be configured using the <varname>jointPoint</varname> and <varname>direction</varname> attributes. The <varname>jointPoint</varname> attribute refers to the corner of the text field and button with which the calendar will be aligned and the <varname>direction</varname> specifies which direction the pop-up calendar will span relative to the joint point. The default settings are <code>jointPoint="bottom-left"</code> and <code>direction="bottom-right"</code>, causing the pop-up calendar to align with the bottom-left corner of the text field and span to the bottom-right, underneath the text field and button. The diagram shows the joint points and directions that can be used. Alternatively, both <varname>jointPoint</varname> and <varname>direction</varname> can be set to <literal>auto</literal> to allow smart pop-up positioning. - </para> - <para> - The calendar features a <guibutton>Today</guibutton> button for locating today's date on the calendar. This can be set to three different values using the <varname>todayControlMode</varname> attribute: - </para> - <itemizedlist> - <listitem> + + <figure id="figu-Component_Reference-richcalendar-richcalendar"> + <title><sgmltag>&lt;rich:calendar&gt;</sgmltag></title> + <mediaobject> + <imageobject> + <imagedata fileref="images/figu-Component_Reference-richcalendar-richcalendar.png" format="PNG" /> + </imageobject> + <textobject> + <para> + An expanded <sgmltag>&lt;rich:calendar&gt;</sgmltag> component, displaying the calendar month of December, 2010. + </para> + </textobject> + </mediaobject> + </figure> + + <section id="sect-Component_Reference-richcalendar-Basic_usage"> + <title>Basic usage</title> + <para> + Basic usage of the <sgmltag>&lt;rich:calendar&gt;</sgmltag> component requires only the <varname>value</varname> attribute, which holds the currently selected date. <xref linkend="exam-Component_Reference-richcalendar-Basic_usage" /> shows a basic declaration, with the value pointing to a data model. + </para> + <example id="exam-Component_Reference-richcalendar-Basic_usage"> + <title>Basic usage</title> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-richcalendar-Basic_usage.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </example> + </section> + + <section id="sect-Component_Reference-richcalendar-Using_a_data_model"> + <title>Using a data model</title> + <para> + The <sgmltag>&lt;rich:calendar&gt;</sgmltag> component supports two different ways of loading data through defining the <varname>mode</varname> attribute. When not specified, the component uses <literal>client</literal> mode, which 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. + </para> + <para> + Alternatively, with <code>mode="ajax"</code> the <sgmltag>&lt;rich:calendar&gt;</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. + </para> + </section> + + <section id="sect-Component_Reference-richcalendar-Behavior_and_appearance"> + <title>Behavior and appearance</title> + <para> + The <sgmltag>&lt;rich:calendar&gt;</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. + </para> + <para> + To change the appearance of the display button from the standard calendar icon, use the <varname>buttonIcon</varname> and <varname>buttonIconDisabled</varname> attributes to replace the icon with a specified file. Alternatively, use the <varname>buttonLabel</varname> attribute to display text on the button without an icon. If <varname>buttonLabel</varname> is specified then both the <varname>buttonIcon</varname> and <varname>buttonIconDisabled</varname> attributes are ignored. To hide the text field box, set <code>showInput="false"</code>. + </para> + <para> + To change the default position at which the pop-up calendar is shown relative to the text field and button, use the <varname>jointPoint</varname> and <varname>direction</varname> attributes. The <varname>jointPoint</varname> attribute refers to the corner of the text field and button with which the calendar will be aligned and the <varname>direction</varname> specifies which direction the pop-up calendar will span relative to the joint point. The default settings are <code>jointPoint="bottom-left"</code> and <code>direction="bottom-right"</code>, causing the pop-up calendar to align with the bottom-left corner of the text field and span to the bottom-right, underneath the text field and button. The diagram shows the joint points and directions that can be used. Alternatively, set both <varname>jointPoint</varname> and <varname>direction</varname> attributes to <literal>auto</literal> to allow smart pop-up positioning. <xref linkend="figu-Component_Reference-richcalendar! -Pop-up_positioning" /> shows the different possible settings for the <varname>jointPoint</varname> and <varname>direction</varname> attributes. + </para> + <figure id="figu-Component_Reference-richcalendar-Pop-up_positioning"> + <title>Pop-up positioning</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/figu-Component_Reference-richcalendar-Pop-up_positioning.png" format="PNG" /> + </imageobject> + <textobject> + <para> + Pop-up positioning is determined using the <varname>jointPoint</varname> and <varname>direction</varname> attributes. + </para> + </textobject> + </mediaobject> <para> - <literal>hidden</literal>, which does not display the button; + Pop-up positioning is determined using the <varname>jointPoint</varname> and <varname>direction</varname> attributes. Values for the <varname>jointPoint</varname> attribute are shown in red, while values for the <varname>direction</varname> attribute are shown in black. </para> - </listitem> - <listitem> - <para> - <literal>select</literal>, the default setting, which scrolls the calendar to the current month and selects today's date; and - </para> - </listitem> - <listitem> - <para> - <literal>scroll</literal>, which scrolls the calendar to the current month but does not select today's date. - </para> - </listitem> - </itemizedlist> - <para> - The <sgmltag>&lt;rich:calendar&gt;</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> - There are several event handlers that are unique to the <sgmltag>&lt;rich:calendar&gt;</sgmltag> component. - </para> - <itemizedlist> - <listitem> - <para> - <varname>ondateselect</varname> is triggered when the date is selected by the user, before the update request is sent. - </para> - </listitem> - <listitem> - <para> - <varname>ondateselected</varname> is triggered after the date is selected by the user. - </para> - </listitem> - <listitem> - <para> - <varname>oncurrentdateselect</varname> is triggered when any of the year- or month-changing buttons are pressed, before the update request is sent. - </para> - </listitem> - <listitem> - <para> - <varname>oncurrentdateselected</varname> is triggered after any of the year- or month-changing buttons are pressed. - </para> - </listitem> - <listitem> - <para> - <varname>ontimeselect</varname> is triggered when the time is set by the user, before the update request is sent. - </para> - </listitem> - <listitem> - <para> - <varname>ontimeselected</varname> is triggered after the time has been set by the user. - </para> - </listitem> - </itemizedlist> - <para> - The entire calendar can be set as read-only with <code>readonly="true"</code>. This allows months and years to be browsed through with the arrow controls, but dates and times cannot be selected. - </para> + </figure> + <para> + The calendar features a <guibutton>Today</guibutton> button for locating today's date on the calendar. This can be set to three different values using the <varname>todayControlMode</varname> attribute: + </para> + <itemizedlist> + <listitem> + <para> + <literal>hidden</literal>, which does not display the button; + </para> + </listitem> + <listitem> + <para> + <literal>select</literal>, the default setting, which scrolls the calendar to the current month and selects today's date; and + </para> + </listitem> + <listitem> + <para> + <literal>scroll</literal>, which scrolls the calendar to the current month but does not select today's date. + </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. + </para> + <!-- TODO not in M4 --> + <!-- + <para> + The styling and appearance of the calendar can be fully customized using facets. + </para> + --> + </section> + + <section id="sect-Component_Reference-richcalendar-Time_of_day"> + <title>Time of day</title> + <para> + The <sgmltag>&lt;rich:calendar&gt;</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> + </section> + + <section id="sect-Component_Reference-richcalendar-richcalendar_events"> + <title><sgmltag>&lt;rich:calendar&gt;</sgmltag> events</title> + <para> + There are several event handlers that are unique to the <sgmltag>&lt;rich:calendar&gt;</sgmltag> component. + </para> + <itemizedlist> + <listitem> + <para> + <varname>ondateselect</varname> is triggered when the date is selected by the user, before the update request is sent. + </para> + </listitem> + <listitem> + <para> + <varname>ondateselected</varname> is triggered after the date is selected by the user. + </para> + </listitem> + <listitem> + <para> + <varname>oncurrentdateselect</varname> is triggered when any of the year- or month-changing buttons are pressed, before the update request is sent. + </para> + </listitem> + <listitem> + <para> + <varname>oncurrentdateselected</varname> is triggered after any of the year- or month-changing buttons are pressed. + </para> + </listitem> + <listitem> + <para> + <varname>ontimeselect</varname> is triggered when the time is set by the user, before the update request is sent. + </para> + </listitem> + <listitem> + <para> + <varname>ontimeselected</varname> is triggered after the time has been set by the user. + </para> + </listitem> + </itemizedlist> + </section> + + <section id="sect-Component_Reference-richcalendar-Reference_data"> + <title>Reference data</title> + <itemizedlist> + <listitem> + <para> + <parameter>component-type</parameter>: <classname>org.richfaces.calendar</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>component-class</parameter>: <classname>org.richfaces.component.html.HtmlCalendar</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>component-family</parameter>: <classname>org.richfaces.calendar</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>renderer-type</parameter>: <classname>org.richfaces.renderkit.calendarRenderer</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>tag-class</parameter>: <classname>org.richfaces.taglib.calendarTag</classname> + </para> + </listitem> + </itemizedlist> + </section> </section> - --> - <!-- TODO not in M3 --> + <!-- TODO not in M4 --> <!-- <section id="sect-Component_Reference-Rich_inputs-richcolorPicker"> <title><sgmltag>&lt;rich:colorPicker&gt;</sgmltag></title> @@ -231,7 +326,7 @@ </section> </section> - <!-- TODO not in M3 --> + <!-- TODO not in M4 --> <!--<rich:autocompleteBehavior>--> <!-- <section id="sect-Component_Reference-Rich_inputs-richautocompleteBehavior"> @@ -282,7 +377,7 @@ </section> --> - <!-- TODO not in M3 --> + <!-- TODO not in M4 --> <!-- <section id="sect-Component_Reference-Rich_inputs-richeditor"> <title><sgmltag>&lt;rich:editor&gt;</sgmltag></title> @@ -402,13 +497,13 @@ </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 M3 + <!-- 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. --> </para> </section> - <!-- TODO not in M3 + <!-- TODO not in M4 <section id="sect-Component_Reference-richinplaceInput-richinplaceInput_events"> <title><sgmltag>&lt;rich:inplaceInput&gt;</sgmltag> events</title> <para> @@ -471,7 +566,7 @@ </section> </section> - <!-- TODO not in M3 --> + <!-- TODO not in M4 --> <!--<rich:inplaceSelect>--> <!-- <section id="sect-Component_Reference-Rich_inputs-richinplaceSelect"> @@ -725,32 +820,87 @@ </itemizedlist> </section> </section> - - <!-- TODO not in M3 --> - <!--<rich:suggestionBox>--> - <!-- - <section id="sect-Component_Reference-Rich_inputs-richsuggestionBox"> - <title><sgmltag>&lt;rich:suggestionBox&gt;</sgmltag></title> + + <!-- <rich:selectOne> --> + <section id="sect-Component_Reference-Rich_inputs-richselectOne"> + <title><sgmltag>&lt;rich:selectOne&gt;</sgmltag></title> <para> - The <sgmltag>&lt;rich:suggestionBox&gt;</sgmltag> component adds a feature-rich drop-down list of suggestions to any text input component. + The <sgmltag>&lt;rich:selectOne&gt;</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 as a combo-box. </para> - <para> - The <sgmltag>&lt;rich:suggestionBox&gt;</sgmltag> component needs the attributes defined for basic use: <varname>for</varname>, which identifies the component to attach the suggestion box to; <varname>suggestionAction</varname>, which defines the method for getting the collection of suggestion data; and <varname>var</varname>, which defines a collection name for access to the currently highlighted row. Typically the suggestions are presented as a list with one or more columns of suggestion data; the layout of these columns is defined inside the <sgmltag>&lt;rich:suggestionBox&gt;</sgmltag> tags using <sgmltag>&lt;h:column&gt;</sgmltag> and other <acronym>JSF</acronym> components. - </para> - <para> - For suggestion lists with multiple columns, the <varname>fetchValue</varname> attribute can be used to specify which column is used when selecting the value for the input component. - </para> - <para> - The <varname>tokens</varname> attribute can be used to define separator characters, which are used when multiple values need to be entered and a new suggestion made for each value. For example, <code>tokens=","</code> (a comma) will begin a new suggestion query each time a comma is typed. Multiple separators can be defined with spaces in between (<code>tokens=", . ; [ ]"</code>) or linking to a bean property that holds the collection of separator tokens. - </para> - <para> - The <varname>minChars</varname> attribute can be used to limit sending the Ajax request until a certain amount of characters has been entered. If the query returns no results, an appropriate message to display can be set with the <varname>nothingLabel</varname> attribute. - </para> - <para> - Instead of returning just one value from an object, the entire object can be returned to the client and handled appropriately. This is done by specifying <code>usingSuggestObjects="true"</code> and setting the <varname>onobjectchange</varname> attribute to a JavaScript method to handle the object, passing the <literal>suggestion</literal> object as a parameter. - </para> + + <figure id="figu-Component_Reference-richselectOne-richselectOne"> + <title><sgmltag>&lt;rich:selectOne&gt;</sgmltag></title> + <mediaobject> + <imageobject> + <imagedata fileref="images/figu-Component_Reference-richselectOne-richselectOne.png" format="PNG" /> + </imageobject> + <textobject> + <para> + A <sgmltag>&lt;rich:selectOne&gt;</sgmltag> component used as a combo-box. + </para> + </textobject> + </mediaobject> + </figure> + + <section id="sect-Component_Reference-richselectOne-Basic_usage"> + <title>Basic usage</title> + <para> + Simple usage of the <sgmltag>&lt;rich:selectOne&gt;</sgmltag> component does not need any attributes declared, but child tags to manage the list of selections are required. An <sgmltag>&lt;f:selectItem&gt;</sgmltag> tag manages the currently selected value, while an <sgmltag>&lt;f:selectItems&gt;</sgmltag> tag points to the list of selection items. + </para> + <example id="exam-Component_Reference-richselectOne-Selection_items"> + <title>Selection items</title> + <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/exam-Component_Reference-richselectOne-Selection_items.xml_sample" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> + </example> + <para> + The arrow keys on a keyboard can be used to highlight different items in the list, even if the list is closed with the control still focused. If the control loses focus or the <keycap function="enter">Enter</keycap> key is pressed, the highlighted option is chosen as the value and the list is closed. Pressing the <keycap function="escape">Esc</keycap> key will close the list but not change the value. + </para> + </section> + + <section id="sect-Component_Reference-richselectOne-Using_richselectOne_as_a_combo-box"> + <title>Using <sgmltag>&lt;rich:selectOne&gt;</sgmltag> as a combo-box</title> + <para> + Combo-boxes are drop-down lists that allow the user to type into a text field to scroll through or filter the list. By default, the <sgmltag>&lt;rich:selectOne&gt;</sgmltag> component functions as a drop-down list. To add keyboard support to make it function like a combo-box, 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> + Typing text into a combo-box causes the list to scroll to the relevant item by default. This behavior can be changed so that the typed text filters the contents of the list instead, showing only those items that begin with the typed text. To use typed text as a filter for combo-box lists, set <code>filterOnUpdates="true"</code>. + </para> + </section> + + <section id="sect-Component_Reference-richselectOne-Reference_data"> + <title>Reference data</title> + <itemizedlist> + <listitem> + <para> + <parameter>component-type</parameter>: <classname>org.richfaces.selectOne</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>component-class</parameter>: <classname>org.richfaces.component.html.HtmlSelectOne</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>component-family</parameter>: <classname>org.richfaces.selectOne</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>renderer-type</parameter>: <classname>org.richfaces.renderkit.selectOneRenderer</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>tag-class</parameter>: <classname>org.richfaces.taglib.selectOneTag</classname> + </para> + </listitem> + </itemizedlist> + </section> + </section> - --> </chapter> Copied: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richcalendar-Basic_usage.xml_sample (from rev 19624, modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richcalendar-Basic_usage.xml_sample) =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richcalendar-Basic_usage.xml_sample (rev 0) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richcalendar-Basic_usage.xml_sample 2010-10-21 06:34:43 UTC (rev 19626) @@ -0,0 +1 @@ +<rich:calendar value="#{bean.dateTest}" /> Copied: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselectOne-Selection_items.xml_sample (from rev 19624, modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselectOne-Selection_items.xml_sample) =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselectOne-Selection_items.xml_sample (rev 0) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richselectOne-Selection_items.xml_sample 2010-10-21 06:34:43 UTC (rev 19626) @@ -0,0 +1,4 @@ +<rich:selectOne> + <f:selectItem itemLabel="constantOption" itemValue="0"> + <f:selectItems="#{bean.items}"> +</rich:selectOne> Copied: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Advanced_tool-tip_usage.xml_sample (from rev 19624, modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Advanced_tool-tip_usage.xml_sample) =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Advanced_tool-tip_usage.xml_sample (rev 0) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Advanced_tool-tip_usage.xml_sample 2010-10-21 06:34:43 UTC (rev 19626) @@ -0,0 +1,8 @@ +<h:commandLink value="Simple Link" id="link"> + <rich:toolTip followMouse="true" direction="top-right" mode="ajax" value="#{bean.toolTipContent}" + horizontalOffset="5" verticalOffset="5" layout="block"> + <f:facet name="defaultContent"> + <f:verbatim>Loading...</f:verbatim> + </f:facet> + </rich:toolTip> +</h:commandLink> Copied: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Attaching_the_tool-tip.xml_sample (from rev 19624, modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Attaching_the_tool-tip.xml_sample) =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Attaching_the_tool-tip.xml_sample (rev 0) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Attaching_the_tool-tip.xml_sample 2010-10-21 06:34:43 UTC (rev 19626) @@ -0,0 +1,5 @@ +<rich:panel id="panelId"> +... +</rich:panel> + +<rich:toolTip value="This is a tool-tip." for="panelId"/> Copied: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Defining_tool-tip_content-0.xml_sample (from rev 19624, modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Defining_tool-tip_content-0.xml_sample) =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Defining_tool-tip_content-0.xml_sample (rev 0) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Defining_tool-tip_content-0.xml_sample 2010-10-21 06:34:43 UTC (rev 19626) @@ -0,0 +1,3 @@ +<rich:panel> + <rich:toolTip value="This is a tool-tip."/> +</rich:panel> Copied: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Defining_tool-tip_content-1.xml_sample (from rev 19624, modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Defining_tool-tip_content-1.xml_sample) =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Defining_tool-tip_content-1.xml_sample (rev 0) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Defining_tool-tip_content-1.xml_sample 2010-10-21 06:34:43 UTC (rev 19626) @@ -0,0 +1,5 @@ +<rich:panel> + <rich:toolTip> + This is a <b>tool-tip</b>. + </rich:toolTip> +</rich:panel> Copied: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Unattached_tool-tips.xml_sample (from rev 19624, modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Unattached_tool-tips.xml_sample) =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Unattached_tool-tips.xml_sample (rev 0) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richtoolTip-Unattached_tool-tips.xml_sample 2010-10-21 06:34:43 UTC (rev 19626) @@ -0,0 +1,5 @@ +<rich:panel id="panelId" onclick="#{rich:component("tooltipId")}.show(event);" /> + +<a4j:form> + <rich:toolTip id="toolTipId" attached="false" value="This is a tool-tip."/> +</a4j:form> Copied: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richcalendar-Pop-up_positioning.png (from rev 19624, modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richcalendar-Pop-up_positioning.png) =================================================================== (Binary files differ) Copied: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richcalendar-richcalendar.png (from rev 19624, modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richcalendar-richcalendar.png) =================================================================== (Binary files differ) Copied: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richselectOne-richselectOne.png (from rev 19624, modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richselectOne-richselectOne.png) =================================================================== (Binary files differ) Copied: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richtoolTip-richtoolTip.png (from rev 19624, modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richtoolTip-richtoolTip.png) =================================================================== (Binary files differ) Modified: modules/docs/trunk/Migration_Guide/src/main/docbook/en-US/Changes_and_new_features.xml =================================================================== --- modules/docs/trunk/Migration_Guide/src/main/docbook/en-US/Changes_and_new_features.xml 2010-10-21 06:29:05 UTC (rev 19625) +++ modules/docs/trunk/Migration_Guide/src/main/docbook/en-US/Changes_and_new_features.xml 2010-10-21 06:34:43 UTC (rev 19626) @@ -949,7 +949,7 @@ <section id="sect-Migration_Guide-Consolidated_or_renamed_components-richautocomplete"> <title><sgmltag>&lt;rich:autocomplete&gt;</sgmltag></title> <para> - The <sgmltag>&lt;rich:autocomplete&gt;</sgmltag> component combines and replaces the old <sgmltag>&lt;rich:comboBox&gt;</sgmltag> and <sgmltag>&lt;rich:suggestionBox&gt;</sgmltag> components. + The <sgmltag>&lt;rich:autocomplete&gt;</sgmltag> component replaces the old <sgmltag>&lt;rich:suggestionBox&gt;</sgmltag> component. </para> </section> @@ -993,6 +993,13 @@ The <sgmltag>&lt;rich:popupPanel&gt;</sgmltag> component replaces the old <sgmltag>&lt;rich:modalPanel&gt;</sgmltag> component. </para> </section> + + <section id="sect-Migration_Guide-Consolidated_or_renamed_components-richselectOne"> + <title><sgmltag>&lt;rich:selectOne&gt;</sgmltag></title> + <para> + The <sgmltag>&lt;rich:selectOne&gt;</sgmltag> component replaces the old <sgmltag>&lt;rich:comboBox&gt;</sgmltag> component. + </para> + </section> <section id="sect-Migration_Guide-Consolidated_or_renamed_components-richtogglePanel_and_richtogglePanelItem"> <title><sgmltag>&lt;rich:togglePanel&gt;</sgmltag> and <sgmltag>&lt;rich:togglePanelItem&gt;</sgmltag></title> @@ -1037,10 +1044,10 @@ </para> </section> - <section id="sect-Migration_Guide-Deprecated_components_and_behaviors-richcomboBox_and_richsuggestionBox"> - <title><sgmltag>&lt;rich:comboBox&gt;</sgmltag> and <sgmltag>&lt;rich:suggestionBox&gt;</sgmltag></title> + <section id="sect-Migration_Guide-Deprecated_components_and_behaviors-richcomboBox"> + <title><sgmltag>&lt;rich:comboBox&gt;</sgmltag></title> <para> - The functionality of the old <sgmltag>&lt;rich:comboBox&gt;</sgmltag> and <sgmltag>&lt;rich:suggestionBox&gt;</sgmltag> components is now available through the <sgmltag>&lt;rich:autocomplete&gt;</sgmltag> component. + The functionality of the old <sgmltag>&lt;rich:comboBox&gt;</sgmltag> component is now available through the <sgmltag>&lt;rich:selectOne&gt;</sgmltag> component. </para> </section> @@ -1079,6 +1086,13 @@ </para> </section> + <section id="sect-Migration_Guide-Deprecated_components_and_behaviors-richsuggestionBox"> + <title><sgmltag>&lt;rich:suggestionBox&gt;</sgmltag></title> + <para> + The functionality of the old <sgmltag>&lt;rich:suggestionBox&gt;</sgmltag> component is now available through the <sgmltag>&lt;rich:autocomplete&gt;</sgmltag> component. + </para> + </section> + </section> </chapter>