[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Shane Bryzak
sbryzak at redhat.com
Thu Mar 15 02:21:51 EDT 2007
User: sbryzak2
Date: 07/03/15 02:21:51
Modified: doc/reference/en/modules controls.xml
Log:
initial formatting - this is a work in progress, and still requires usage examples, screenshots, etc for most controls.
Revision Changes Path
1.26 +1037 -613 jboss-seam/doc/reference/en/modules/controls.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: controls.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/controls.xml,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -b -r1.25 -r1.26
--- controls.xml 10 Mar 2007 19:09:35 -0000 1.25
+++ controls.xml 15 Mar 2007 06:21:51 -0000 1.26
@@ -9,77 +9,203 @@
</para>
<para>
+ To use these controls, define the "<literal>s</literal>" namespace in your page as follows (facelets only):
+ </para>
+
+ <programlisting><![CDATA[
+<html xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:s="http://jboss.com/products/seam/taglib">]]>
+ </programlisting>
+
+ <para>
The ui example demonstrates the use of a number of these tags.
</para>
- <variablelist>
- <varlistentry>
- <term><literal><s:validate></literal></term>
- <listitem>
+ <table>
+ <title>Seam JSF Control Reference</title>
+
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*" />
+ <colspec colnum="2" colwidth="3*" />
+
+ <tbody>
+
+ <row>
+ <entry valign="top">
<para>
- Validate a JSF input field against the bound property using
- Hibernate Validator.
+ <literal><s:validate></literal>
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:validateAll></literal></term>
- <listitem>
+ </entry>
+ <entry valign="top">
+ <para><emphasis>Description</emphasis></para>
<para>
- Validate all child JSF input fields against the bound propertys using
- Hibernate Validator.
+ A non-visual control, validates a JSF input field against the bound
+ property using Hibernate Validator.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:formattedText></literal></term>
- <listitem>
+ <para><emphasis>Attributes</emphasis></para>
+ <para>
+ None.
+ </para>
+ <para><emphasis>Usage</emphasis></para>
+ <programlisting><![CDATA[
+<h:inputText id="userName" required="true" value="#{customer.userName}">
+ <s:validate />
+</h:inputText>
+<h:message for="userName" styleClass="error" />]]></programlisting>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para><literal><s:validateAll></literal></para>
+ </entry>
+ <entry valign="top">
+ <para><emphasis>Description</emphasis></para>
+ <para>
+ A non-visual control, validates all child JSF input fields against their bound
+ properties using Hibernate Validator.
+ </para>
+ <para><emphasis>Attributes</emphasis></para>
+ <para>
+ None.
+ </para>
+ <para><emphasis>Usage</emphasis></para>
+ <programlisting><![CDATA[
+<s:validateAll>
+ <div class="entry">
+ <h:outputLabel for="username">Username:</h:outputLabel>
+ <h:inputText id="username" value="#{user.username}" required="true"/>
+ <h:message for="username" styleClass="error" />
+ </div>
+ <div class="entry">
+ <h:outputLabel for="password">Password:</h:outputLabel>
+ <h:inputSecret id="password" value="#{user.password}" required="true"/>
+ <h:message for="password" styleClass="error" />
+ </div>
+ <div class="entry">
+ <h:outputLabel for="verify">Verify Password:</h:outputLabel>
+ <h:inputSecret id="verify" value="#{register.verify}" required="true"/>
+ <h:message for="verify" styleClass="error" />
+ </div>
+</s:validateAll>]]></programlisting>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para><literal><s:formattedText></literal></para>
+ </entry>
+ <entry valign="top">
+ <para><emphasis>Description</emphasis></para>
<para>
Output <emphasis>Seam Text</emphasis>.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:convertDateTime></literal></term>
- <listitem>
+ <para><emphasis>Attributes</emphasis></para>
+ <para>
+ None.
+ </para>
+ <para><emphasis>Usage</emphasis></para>
+ <para>
+ <programlisting><![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para><literal><s:convertDateTime></literal></para>
+ </entry>
+ <entry valign="top">
+ <para><emphasis>Description</emphasis></para>
<para>
Perform date or time conversions in the Seam timezone.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:convertEnum></literal></term>
- <listitem>
+ <para><emphasis>Attributes</emphasis></para>
+ <para>
+ None.
+ </para>
+ <para><emphasis>Usage</emphasis></para>
+ <programlisting><![CDATA[
+]]></programlisting>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para><literal><s:convertEnum></literal></para>
+ </entry>
+
+ <entry valign="top">
+ <para><emphasis>Description</emphasis></para>
<para>
Assigns an enum converter to the current component. This is primarily
useful for radio button and dropdown controls.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:convertEntity></literal></term>
- <listitem>
+ <para><emphasis>Attributes</emphasis></para>
+ <para>
+ None.
+ </para>
+ <para><emphasis>Usage</emphasis></para>
+ <programlisting><![CDATA[
+]]></programlisting>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para><literal><s:convertEntity></literal></para>
+ </entry>
+ <entry valign="top">
+ <para><emphasis>Description</emphasis></para>
<para>
Assigns an entity converter to the current component. This is primarily
useful for radio button and dropdown controls.
</para>
+
<para>
The converter works with any entity which has an <literal>@Id</literal> annotation -
either simple or composite. If your <emphasis>Managed Persistence Context</emphasis> isn't called
<literal>entityManager</literal>, then you need to set it in components.xml:
</para>
+
+ <para><emphasis>Attributes</emphasis></para>
+
+ <para>
+ None.
+ </para>
+
+ <para><emphasis>Configuration</emphasis></para>
+
<programlisting><![CDATA[
<component name="org.jboss.seam.ui.entityConverter">
<property name="entityManager">#{em}</property>
- </component>]]></programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:enumItem></literal></term>
- <listitem>
+ </component>
+]]></programlisting>
+
+ <para><emphasis>Usage</emphasis></para>
+ <programlisting><![CDATA[
+
+]]></programlisting>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:enumItem></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
Creates a <literal>SelectItem</literal> from an enum value.
</para>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
<itemizedlist>
<listitem>
<para>
@@ -93,14 +219,33 @@
</para>
</listitem>
</itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:selectItems></literal></term>
- <listitem>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:selectItems></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
Creates a <literal>List<SelectItem></literal> from a List, Set, DataModel or Array.
</para>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
<itemizedlist>
<listitem>
<para>
@@ -137,11 +282,27 @@
</para>
</listitem>
</itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:graphicImage></literal></term>
- <listitem>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:graphicImage></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
An extended <literal><h:graphicImage></literal> that allows the image to be created in a Seam Component; further transforms
can be applied to the image. <emphasis>Facelets only.</emphasis>
@@ -149,6 +310,9 @@
<para>
All attributes for <literal><h:graphicImage></literal> are supported, as well as:
</para>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
<itemizedlist>
<listitem>
<para>
@@ -166,12 +330,17 @@
</listitem>
</itemizedlist>
<para>
+<emphasis>Transformations</emphasis>
+</para>
+ <para>
To apply a transform to the image, you would nest a tag specifying the transform to apply. Seam currently supports these
transforms:
</para>
<variablelist>
<varlistentry>
- <term><literal><s:transformImageSize></literal></term>
+ <term>
+<literal><s:transformImageSize></literal>
+</term>
<listitem>
<itemizedlist>
<listitem>
@@ -200,7 +369,9 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><literal><s:transformImageBlur></literal></term>
+ <term>
+<literal><s:transformImageBlur></literal>
+</term>
<listitem>
<itemizedlist>
<listitem>
@@ -212,7 +383,9 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><literal><s:transformImageType></literal></term>
+ <term>
+<literal><s:transformImageType></literal>
+</term>
<listitem>
<itemizedlist>
<listitem>
@@ -224,63 +397,193 @@
</listitem>
</varlistentry>
</variablelist>
+
<para>
It's easy to create your own transform - create a <literal>UIComponent</literal> which <literal>implements</literal>
<literal>org.jboss.seam.ui.graphicImage.ImageTransform</literal>. Inside the <literal>applyTransform()</literal>method
use <literal>image.getBufferedImage()</literal> to get the original image and <literal>image.setBufferedImage()</literal>
to set your transformed image. Transforms are applied in the order specified in the view.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:decorate></literal></term>
- <listitem>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:decorate></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
"Decorate" a JSF input field when validation fails.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:message></literal></term>
- <listitem>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
+ <para>
+ None.
+ </para>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:message></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
"Decorate" a JSF input field with the validation error message.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:span></literal></term>
- <listitem>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
+ <para>
+ None.
+ </para>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:span></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
Render a HTML <literal><span></literal>.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:div></literal></term>
- <listitem>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
+ <para>
+ None.
+ </para>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:div></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
Render a HTML <literal><div></literal>.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:fragment></literal></term>
- <listitem>
<para>
- A non-rendering component useful for enabling/disabling rendering of it's children
+<emphasis>Attributes</emphasis>
+</para>
+ <para>
+ None.
+ </para>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:fragment></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
+ <para>
+ A non-rendering component useful for enabling/disabling rendering of it's children.
+ </para>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
+ <para>
+ None.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:cache></literal></term>
- <listitem>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:cache></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
Cache the rendered page fragment using JBoss Cache. Note that
<literal><s:cache></literal> actually uses the instance
of JBoss Cache managed by the built-in <literal>pojoCache</literal>
component.
</para>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
<itemizedlist>
<listitem>
<para>
@@ -303,15 +606,34 @@
</para>
</listitem>
</itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:link></literal></term>
- <listitem>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:link></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
A link that supports invocation of an action with control over conversation
propagation. <emphasis>Does not submit the form.</emphasis>
</para>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
<itemizedlist>
<listitem>
<para>
@@ -354,15 +676,34 @@
</para>
</listitem>
</itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:button></literal></term>
- <listitem>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:button></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
A button that supports invocation of an action with control
over conversation propagation. <emphasis>Does not submit the form.</emphasis>
</para>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
<itemizedlist>
<listitem>
<para>
@@ -405,12 +746,27 @@
</para>
</listitem>
</itemizedlist>
- </listitem>
- </varlistentry>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
- <varlistentry>
- <term><literal><s:selectDate></literal></term>
- <listitem>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:selectDate></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
Displays a dynamic date picker component that selects a date
for the specified input field. The body of the <literal>selectDate</literal> element should
@@ -418,30 +774,54 @@
to display the date picker. The date picker can be styled using CSS. An example CSS file
can be found in the Seam booking demo as <literal>date.css</literal>.
</para>
-
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
<itemizedlist>
- <listitem><para><literal>for</literal> —
+ <listitem>
+<para>
+<literal>for</literal> —
The id of the input field that the date picker will insert the
selected date into.
- </para></listitem>
- <listitem><para><literal>dateFormat</literal> —
+ </para>
+</listitem>
+ <listitem>
+<para>
+<literal>dateFormat</literal> —
The date format string. This should match the date format of the
input field.
- </para></listitem>
+ </para>
+</listitem>
</itemizedlist>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal><s:conversationPropagation></literal></term>
- <listitem>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:conversationPropagation></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
Customize the conversation propagation for a command link or button
(or similar JSF control).
<emphasis>Facelets only.</emphasis>
</para>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
<itemizedlist>
<listitem>
<para>
@@ -458,30 +838,90 @@
</para>
</listitem>
</itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:conversationId></literal></term>
- <listitem>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:conversationId></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
Add the conversation id to an output link (or similar JSF control).
<emphasis>Facelets only.</emphasis>
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:taskId></literal></term>
- <listitem>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
+ <para>
+ None.
+ </para>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:taskId></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
Add the task id to an output link (or similar JSF control), when the
task is available via <literal>#{task}</literal>.
<emphasis>Facelets only.</emphasis>
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:fileUpload></literal></term>
- <listitem>
+ <para>
+<emphasis>Attributes</emphasis>
+</para>
+ <para>
+ None.
+ </para>
+ <para>
+<emphasis>Usage</emphasis>
+</para>
+ <para>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><s:fileUpload></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+<emphasis>Description</emphasis>
+</para>
<para>
Renders a file upload control. This control must be used within a form with
an encoding type of <literal>multipart/form-data</literal>, i.e:
@@ -500,7 +940,6 @@
<programlisting>
<![CDATA[
-
<filter>
<filter-name>Seam Filter</filter-name>
<filter-class>org.jboss.seam.web.SeamFilter</filter-class>
@@ -510,11 +949,14 @@
<filter-name>Seam Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
-
]]>
</programlisting>
<para>
+<emphasis>Configuration</emphasis>
+</para>
+
+ <para>
The following configuration options for multipart requests may be configured in components.xml:
</para>
@@ -546,9 +988,8 @@
</programlisting>
<para>
- And here's a list of the supported attributes for the <literal>fileUpload</literal> control:
- </para>
-
+<emphasis>Attributes</emphasis>
+</para>
<itemizedlist>
<listitem>
<para>
@@ -585,37 +1026,20 @@
</para>
</listitem>
</itemizedlist>
-
- </listitem>
- </varlistentry>
-
- <!-- varlistentry>
- <term><literal><s:action></literal></term>
- <listitem>
<para>
- Attach an action listener to an output link (or similar JSF control).
- <emphasis>Facelets only.</emphasis>
- </para>
- <itemizedlist>
- <listitem>
+<emphasis>Usage</emphasis>
+</para>
<para>
- <literal>action</literal> — a method binding that specified
- the action listener.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal><s:selection></literal></term>
- <listitem>
- <para>
- Propagate the selected row of a <literal>DataModel</literal> with an
- output link (or similar JSF control).
- <emphasis>Facelets only.</emphasis>
+ <programlisting>
+<![CDATA[
+]]></programlisting>
</para>
- </listitem>
- </varlistentry-->
- </variablelist>
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+
+ </table>
</chapter>
More information about the jboss-cvs-commits
mailing list