From richfaces-svn-commits at lists.jboss.org Mon Oct 18 02:53:35 2010
Content-Type: multipart/mixed; boundary="===============2003364710099227777=="
MIME-Version: 1.0
From: richfaces-svn-commits at lists.jboss.org
To: richfaces-svn-commits at lists.jboss.org
Subject: [richfaces-svn-commits] JBoss Rich Faces SVN: r19591 - in
 modules/docs/branches/m4: Migration_Guide/src/main/docbook/en-US and 1 other
 directory.
Date: Mon, 18 Oct 2010 02:53:35 -0400
Message-ID: <201010180653.o9I6rZ0F018784@svn01.web.mwc.hst.phx2.redhat.com>

--===============2003364710099227777==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: SeanRogers
Date: 2010-10-18 02:53:34 -0400 (Mon, 18 Oct 2010)
New Revision: 19591

Modified:
   modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/chap=
-Component_Reference-Rich_inputs.xml
   modules/docs/branches/m4/Migration_Guide/src/main/docbook/en-US/Changes_=
and_new_features.xml
Log:
Started rich:selectOne and rich:calendar

Modified: modules/docs/branches/m4/Component_Reference/src/main/docbook/en-=
US/chap-Component_Reference-Rich_inputs.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/cha=
p-Component_Reference-Rich_inputs.xml	2010-10-18 01:36:56 UTC (rev 19590)
+++ modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/cha=
p-Component_Reference-Rich_inputs.xml	2010-10-18 06:53:34 UTC (rev 19591)
@@ -11,89 +11,143 @@
 		</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> -->
+	<!-- TODO in M4
 	<section id=3D"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 b=
e highly customized.
 		</para>
-		<para>
-			The <sgmltag>&lt;rich:calendar&gt;</sgmltag> component supports two dif=
ferent ways of loading data through defining the <varname>mode</varname> at=
tribute. When not specified, the component uses <literal>client</literal> m=
ode, which loads an initial portion of data within a set date range. The ra=
nge can be defined by using the <varname>preloadDateRangeBegin</varname> an=
d <varname>preloadDateRangeEnd</varname> attributes. Additional data reques=
ts are not sent. Alternatively, with <code>mode=3D"ajax"</code> the <sgmlta=
g>&lt;rich:calendar&gt;</sgmltag> requests portions of data for rendering f=
rom a special data model. The data model can be defined through the <varnam=
e>dataModel</varname> attribute, which points to an object that implements =
the <classname>CalendarDataModel</classname> interface. If the <varname>dat=
aModel</varname> attribute is not defined or has a value of <literal>null</=
literal>, the <literal>ajax</literal> mode functions the same as the <liter=
al>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=3D"false</code> will render th=
e calendar in-line on the page instead, which displays the full calendar wi=
thout the text field or display button. The appearance of the display butto=
n can be altered from the standard calendar icon by defining the <varname>b=
uttonIcon</varname> and <varname>buttonIconDisabled</varname> attributes to=
 replace the icon with a specified file, or by defining the <varname>button=
Label</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=3D"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</varn=
ame> attribute refers to the corner of the text field and button with which=
 the calendar will be aligned and the <varname>direction</varname> specifie=
s which direction the pop-up calendar will span relative to the joint point=
. The default settings are <code>jointPoint=3D"bottom-left"</code> and <cod=
e>direction=3D"bottom-right"</code>, causing the pop-up calendar to align w=
ith 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 an=
d directions that can be used. Alternatively, both <varname>jointPoint</var=
name> 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 locatin=
g today's date on the calendar. This can be set to three different values u=
sing 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 cal=
endar 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 wit=
h the <varname>defaultTime</varname> attribute. If the time is altered and =
a new date is selected, it will not reset unless <code>resetTimeOnDateSelec=
t=3D"true"</code> is specified.
-		</para>
-		<para>
-			There are several event handlers that are unique to the <sgmltag>&lt;ri=
ch:calendar&gt;</sgmltag> component.
-		</para>
-		<itemizedlist>
-			<listitem>
-				<para>
-					<varname>ondateselect</varname> is triggered when the date is selecte=
d by the user, before the update request is sent.
-				</para>
-			</listitem>
-			<listitem>
-				<para>
-					<varname>ondateselected</varname> is triggered after the date is sele=
cted by the user.
-				</para>
-			</listitem>
-			<listitem>
-				<para>
-					<varname>oncurrentdateselect</varname> is triggered when any of the y=
ear- or month-changing buttons are pressed, before the update request is se=
nt.
-				</para>
-			</listitem>
-			<listitem>
-				<para>
-					<varname>oncurrentdateselected</varname> is triggered after any of th=
e 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 bee=
n set by the user.
-				</para>
-			</listitem>
-		</itemizedlist>
-		<para>
-			The entire calendar can be set as read-only with <code>readonly=3D"true=
"</code>. This allows months and years to be browsed through with the arrow=
 controls, but dates and times cannot be selected.
-		</para>
+
+		<section id=3D"sect-Component_Reference-richcalendar-Basic_usage">
+			<title>Basic usage</title>
+			<para>
+				The <sgmltag>&lt;rich:calendar&gt;</sgmltag> component supports two di=
fferent ways of loading data through defining the <varname>mode</varname> a=
ttribute. When not specified, the component uses <literal>client</literal> =
mode, which loads an initial portion of data within a set date range. The r=
ange can be defined by using the <varname>preloadDateRangeBegin</varname> a=
nd <varname>preloadDateRangeEnd</varname> attributes. Additional data reque=
sts are not sent.
+			</para>
+		</section>
+
+		<section id=3D"sect-Component_Reference-richcalendar-Using_a_data_model">
+			<title>Using a data model</title>
+			<para>
+				Alternatively, with <code>mode=3D"ajax"</code> the <sgmltag>&lt;rich:c=
alendar&gt;</sgmltag> requests portions of data for rendering from a specia=
l data model. The data model can be defined through the <varname>dataModel<=
/varname> attribute, which points to an object that implements the <classna=
me>CalendarDataModel</classname> interface. If the <varname>dataModel</varn=
ame> attribute is not defined or has a value of <literal>null</literal>, th=
e <literal>ajax</literal> mode functions the same as the <literal>client</l=
iteral> mode.
+			</para>
+		</section>
+
+		<section id=3D"sect-Component_Reference-richcalendar-Behavior_and_appear=
ance">
+			<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=3D"false</code>. This displays the full calendar without th=
e text field or display button.
+			</para>
+			<para>
+				To change the appearance of the display button from the standard calen=
dar icon, use the <varname>buttonIcon</varname> and <varname>buttonIconDisa=
bled</varname> attributes to replace the icon with a specified file. Altern=
atively, use the <varname>buttonLabel</varname> attribute to display text o=
n the button without an icon. If <varname>buttonLabel</varname> is specifie=
d then both the <varname>buttonIcon</varname> and <varname>buttonIconDisabl=
ed</varname> attributes are ignored. To hide the text field box, set <code>=
showInput=3D"false"</code>.
+			</para>
+			<para>
+				To change the default position at which the pop-up calendar is shown r=
elative to the text field and button, use the <varname>jointPoint</varname>=
 and <varname>direction</varname> attributes. The <varname>jointPoint</varn=
ame> attribute refers to the corner of the text field and button with which=
 the calendar will be aligned and the <varname>direction</varname> specifie=
s which direction the pop-up calendar will span relative to the joint point=
. The default settings are <code>jointPoint=3D"bottom-left"</code> and <cod=
e>direction=3D"bottom-right"</code>, causing the pop-up calendar to align w=
ith 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 an=
d directions that can be used. Alternatively, set both <varname>jointPoint<=
/varname> and <varname>direction</varname> attributes to <literal>auto</lit=
eral> to allow smart pop-up positioning.
+			</para>
+			<para>
+				The calendar features a <guibutton>Today</guibutton> button for locati=
ng 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 ca=
lendar 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=3D"true"</co=
de>. This allows months and years to be browsed through with the arrow cont=
rols, but dates and times cannot be selected.
+			</para>
+		</section>
+
+		<section id=3D"sect-Component_Reference-richcalendar-Time_of_day">
+			<title>Time of day</title>
+			<para>
+				The <sgmltag>&lt;rich:calendar&gt;</sgmltag> component can additionall=
y 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 wi=
th the <varname>defaultTime</varname> attribute. If the time is altered and=
 a new date is selected, it will not reset unless <code>resetTimeOnDateSele=
ct=3D"true"</code> is specified.
+			</para>
+		</section>
+
+		<section id=3D"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;r=
ich:calendar&gt;</sgmltag> component.
+			</para>
+			<itemizedlist>
+				<listitem>
+					<para>
+						<varname>ondateselect</varname> is triggered when the date is select=
ed by the user, before the update request is sent.
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						<varname>ondateselected</varname> is triggered after the date is sel=
ected 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 s=
ent.
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						<varname>oncurrentdateselected</varname> is triggered after any of t=
he 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 be=
en set by the user.
+					</para>
+				</listitem>
+			</itemizedlist>
+		</section>
+		=

+		<section id=3D"sect-Component_Reference-richcalendar-Reference_data">
+			<title>Reference data</title>
+			<itemizedlist>
+				<listitem>
+					<para>
+						<parameter>component-type</parameter>: <classname>org.richfaces.cale=
ndar</classname>
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						<parameter>component-class</parameter>: <classname>org.richfaces.com=
ponent.html.HtmlCalendar</classname>
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						<parameter>component-family</parameter>: <classname>org.richfaces.ca=
lendar</classname>
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						<parameter>renderer-type</parameter>: <classname>org.richfaces.rende=
rkit.calendarRenderer</classname>
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						<parameter>tag-class</parameter>: <classname>org.richfaces.taglib.ca=
lendarTag</classname>
+					</para>
+				</listitem>
+			</itemizedlist>
+		</section>
 	</section>
 	-->
 	=

@@ -725,32 +779,55 @@
 			</itemizedlist>
 		</section>
 	</section>
-	=

-	<!-- TODO not in M3 -->
-	<!--<rich:suggestionBox>-->
-	<!--
-	<section id=3D"sect-Component_Reference-Rich_inputs-richsuggestionBox">
-		<title><sgmltag>&lt;rich:suggestionBox&gt;</sgmltag></title>
+
+	<!-- <rich:selectOne> -->
+	<section id=3D"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 feat=
ure-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 comp=
onent 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 a=
ttributes defined for basic use: <varname>for</varname>, which identifies t=
he component to attach the suggestion box to; <varname>suggestionAction</va=
rname>, which defines the method for getting the collection of suggestion d=
ata; 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</acr=
onym> components.
-		</para>
-		<para>
-			For suggestion lists with multiple columns, the <varname>fetchValue</va=
rname> 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 n=
ew suggestion made for each value. For example, <code>tokens=3D","</code> (=
a comma) will begin a new suggestion query each time a comma is typed. Mult=
iple separators can be defined with spaces in between (<code>tokens=3D", . =
; [ ]"</code>) or linking to a bean property that holds the collection of s=
eparator 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 c=
an be returned to the client and handled appropriately. This is done by spe=
cifying <code>usingSuggestObjects=3D"true"</code> and setting the <varname>=
onobjectchange</varname> attribute to a JavaScript method to handle the obj=
ect, passing the <literal>suggestion</literal> object as a parameter.
-		</para>
+
+		<section id=3D"sect-Component_Reference-richselectOne-Basic_usage">
+			<title>Basic usage</title>
+			<para>
+				Simple usage of the <sgmltag>&lt;rich:selectOne&gt;</sgmltag> componen=
t 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&g=
t;</sgmltag> tag points to the list of selection items.
+			</para>
+		</section>
+
+		<!--FIXME: finish draft -->
+		=

+		<section id=3D"sect-Component_Reference-richselectOne-Reference_data">
+			<title>Reference data</title>
+			<itemizedlist>
+				<listitem>
+					<para>
+						<parameter>component-type</parameter>: <classname>org.richfaces.sele=
ctOne</classname>
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						<parameter>component-class</parameter>: <classname>org.richfaces.com=
ponent.html.HtmlSelectOne</classname>
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						<parameter>component-family</parameter>: <classname>org.richfaces.se=
lectOne</classname>
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						<parameter>renderer-type</parameter>: <classname>org.richfaces.rende=
rkit.selectOneRenderer</classname>
+					</para>
+				</listitem>
+				<listitem>
+					<para>
+						<parameter>tag-class</parameter>: <classname>org.richfaces.taglib.se=
lectOneTag</classname>
+					</para>
+				</listitem>
+			</itemizedlist>
+		</section>
+		=

 	</section>
-	-->
 =

 </chapter>
 =


Modified: modules/docs/branches/m4/Migration_Guide/src/main/docbook/en-US/C=
hanges_and_new_features.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- modules/docs/branches/m4/Migration_Guide/src/main/docbook/en-US/Changes=
_and_new_features.xml	2010-10-18 01:36:56 UTC (rev 19590)
+++ modules/docs/branches/m4/Migration_Guide/src/main/docbook/en-US/Changes=
_and_new_features.xml	2010-10-18 06:53:34 UTC (rev 19591)
@@ -949,7 +949,7 @@
 		<section id=3D"sect-Migration_Guide-Consolidated_or_renamed_components-r=
ichautocomplete">
 			<title><sgmltag>&lt;rich:autocomplete&gt;</sgmltag></title>
 			<para>
-				The <sgmltag>&lt;rich:autocomplete&gt;</sgmltag> component combines an=
d replaces the old <sgmltag>&lt;rich:comboBox&gt;</sgmltag> and <sgmltag>&l=
t;rich:suggestionBox&gt;</sgmltag> components.
+				The <sgmltag>&lt;rich:autocomplete&gt;</sgmltag> component replaces th=
e 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=3D"sect-Migration_Guide-Consolidated_or_renamed_components-r=
ichselectOne">
+			<title><sgmltag>&lt;rich:selectOne&gt;</sgmltag></title>
+			<para>
+				The <sgmltag>&lt;rich:selectOne&gt;</sgmltag> component replaces the o=
ld <sgmltag>&lt;rich:comboBox&gt;</sgmltag> component.
+			</para>
+		</section>
 		=

 		<section id=3D"sect-Migration_Guide-Consolidated_or_renamed_components-r=
ichtogglePanel_and_richtogglePanelItem">
 			<title><sgmltag>&lt;rich:togglePanel&gt;</sgmltag> and <sgmltag>&lt;ric=
h:togglePanelItem&gt;</sgmltag></title>
@@ -1037,10 +1044,10 @@
 			</para>
 		</section>
 		=

-		<section id=3D"sect-Migration_Guide-Deprecated_components_and_behaviors-=
richcomboBox_and_richsuggestionBox">
-			<title><sgmltag>&lt;rich:comboBox&gt;</sgmltag> and <sgmltag>&lt;rich:s=
uggestionBox&gt;</sgmltag></title>
+		<section id=3D"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 availab=
le 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;</sgm=
ltag> component.
 			</para>
 		</section>
 		=

@@ -1079,6 +1086,13 @@
 			</para>
 		</section>
 		=

+		<section id=3D"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;</sgml=
tag> component is now available through the <sgmltag>&lt;rich:autocomplete&=
gt;</sgmltag> component.
+			</para>
+		</section>
+		=

 	</section>
 </chapter>
 =



--===============2003364710099227777==--