Author: SeanRogers
Date: 2010-10-20 21:32:01 -0400 (Wed, 20 Oct 2010)
New Revision: 19623
Added:
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richcalendar-Basic_usage.xml_sample
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richcalendar-Pop-up_positioning.png
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richcalendar-richcalendar.png
Modified:
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml
Log:
Draft of rich:calendar complete
Modified:
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml
===================================================================
---
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml 2010-10-21
00:31:11 UTC (rev 19622)
+++
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Rich_inputs.xml 2010-10-21
01:32:01 UTC (rev 19623)
@@ -21,16 +21,37 @@
The <sgmltag><rich:calendar></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>
+ <figure id="figu-Component_Reference-richcalendar-richcalendar">
+ <title><sgmltag><rich:calendar></sgmltag></title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/figu-Component_Reference-richcalendar-richcalendar.png"
format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ An expanded <sgmltag><rich:calendar></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>
- The <sgmltag><rich:calendar></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.
+ Basic usage of the <sgmltag><rich:calendar></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><rich:calendar></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><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.
</para>
</section>
@@ -44,8 +65,24 @@
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.
+ 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>
+ 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>
+ </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>
@@ -69,6 +106,12 @@
<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">
Added:
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richcalendar-Basic_usage.xml_sample
===================================================================
---
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richcalendar-Basic_usage.xml_sample
(rev 0)
+++
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/extras/exam-Component_Reference-richcalendar-Basic_usage.xml_sample 2010-10-21
01:32:01 UTC (rev 19623)
@@ -0,0 +1 @@
+<rich:calendar value="#{bean.dateTest}" />
Added:
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richcalendar-Pop-up_positioning.png
===================================================================
(Binary files differ)
Property changes on:
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richcalendar-Pop-up_positioning.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added:
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richcalendar-richcalendar.png
===================================================================
(Binary files differ)
Property changes on:
modules/docs/branches/m4/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-richcalendar-richcalendar.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream