12:24 p.m.
Author: pete.muir(a)jboss.org
Date: 2008-04-08 13:24:42 -0400 (Tue, 08 Apr 2008)
New Revision: 7876
Modified:
branches/Seam_2_0/doc/Seam_Reference_Guide/en-US/Controls.xml
Log:
JBSEAM-2806
Modified: branches/Seam_2_0/doc/Seam_Reference_Guide/en-US/Controls.xml
===================================================================
--- branches/Seam_2_0/doc/Seam_Reference_Guide/en-US/Controls.xml 2008-04-08 15:10:51 UTC
(rev 7875)
+++ branches/Seam_2_0/doc/Seam_Reference_Guide/en-US/Controls.xml 2008-04-08 17:24:42 UTC
(rev 7876)
@@ -2,870 +2,611 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id="controls">
- <title>Seam JSF controls</title>
- <para>
- Seam includes a number of JSF controls that are useful for working with
- Seam. These are intended to complement the built-in JSF controls, and
- controls from other third-party libraries. We recommend
- JBoss RichFaces, and Apache MyFaces Trinidad tag libraries for use with Seam.
- We do not recommend the use of the Tomahawk tag library.
- </para>
+ <title>Seam JSF controls</title>
+ <para>
+ Seam includes a number of JSF controls that are useful for working with
+ Seam. These are intended to complement the built-in JSF controls, and
+ controls from other third-party libraries. We recommend
+ JBoss RichFaces, and Apache MyFaces Trinidad tag libraries for use with Seam.
+ We do not recommend the use of the Tomahawk tag library.
+ </para>
- <section id="controls.tags">
- <title>Tags</title>
+ <section id="controls.tags">
+ <title>Tags</title>
- <para>
- To use these tags, define the "<literal>s</literal>" namespace
in your page
- as follows (facelets only):
- </para>
+ <para>
+ To use these tags, define the "<literal>s</literal>"
namespace in your page
+ as follows (facelets only):
+ </para>
- <programlisting role="XHTML"><![CDATA[<html
xmlns="http://www.w3.org/1999/xhtml"
+ <programlisting role="XHTML"><![CDATA[<html
xmlns="http://www.w3.org/1999/xhtml"
xmlns:s="http://jboss.com/products/seam/taglib">]]></p...
- <para>
- The ui example demonstrates the use of a number of these tags.
- </para>
-
- <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>
- <literal><s:button></literal>
- </para>
- </entry>
- <entry valign="top">
+ <para>
+ The ui example demonstrates the use of a number of these tags.
+ </para>
+
+ <section>
+ <title>Navigation Controls</title>
+
+ <section>
+
<title><literal><s:button></literal></title>
+
<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>
+ 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>
- <literal>value</literal> — the label.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>action</literal> — a method binding that
specified
- the action listener.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>view</literal> — the JSF view id to link
to.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fragment</literal> — the fragment
identifier to link to.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>disabled</literal> — is the link
disabled?
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>propagation</literal> — determines the
conversation
- propagation style: <literal>begin</literal>,
<literal>join</literal>,
- <literal>nest</literal>,
<literal>none</literal> or <literal>end</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pageflow</literal> — a pageflow
definition to begin.
- (This is only useful when
<literal>propagation="begin"</literal> or
- <literal>propagation="join"</literal>.)
- </para>
- </listitem>
+ <listitem>
+ <para>
+ <literal>value</literal> — the label.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>action</literal> — a method binding
that
+ specified the action
+ listener.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>view</literal> — the JSF view id to
link to.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fragment</literal> — the fragment
+ identifier to link to.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>disabled</literal> — is the link
disabled?
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>propagation</literal> — determines
the
+ conversation propagation style:
<literal>begin</literal>,
+ <literal>join</literal>,
<literal>nest</literal>,
+ <literal>none</literal> or
<literal>end</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>pageflow</literal> — a pageflow
definition
+ to begin. (This is only useful when
+ <literal>propagation="begin"</literal> or
+ <literal>propagation="join"</literal> is
used).
+ </para>
+ </listitem>
</itemizedlist>
+
<para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:button
id="cancel" value="Cancel"
+
+ <programlisting role="XHTML"><![CDATA[<s:button
id="cancel"
+ value="Cancel"
action="#{hotelBooking.cancel}"/>]]></programlisting>
<para>
- You can specify both <literal>view</literal> and
<literal>action</literal>
- on <literal><s:link /></literal>. In this case,
the action
- will be called once the redirect to the specified view has
- occured.
+ You can specify both <literal>view</literal> and
+ <literal>action</literal> on <literal><s:link
/></literal>.
+ In this case, the action wil be called once the redirect to the
+ specified view has occured.
</para>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
+
+ </section>
+
+ <section>
+
<title><literal><s:conversationId></literal></title>
+
+ <para><emphasis>Description</emphasis></para>
+
<para>
- <literal><s:cache></literal>
+ Add the conversation id to JSF link or button (e.g.
+ <literal><h:commandLink /></literal> ,
+ <literal><s:button /></literal>).
</para>
- </entry>
- <entry valign="top">
+
+ <para><emphasis>Attributes</emphasis></para>
+
+ <para>None</para>
+
+ </section>
+
+ <section>
+
<title><literal><s:taskId></literal></title>
+
<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.
+ Add the task id to an output link (or similar JSF control),
+ when the task is available via <literal>#{task}</literal>.
</para>
+
<para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>key</literal> — the key to cache
rendered content,
- often a value expression. For example, if we were caching a page
- fragment that displays a document, we might use
-
<literal>key="Document-#{document.id}"</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>enabled</literal> — a value expression
that determines
- if the cache should be used.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>region</literal> — a JBoss Cache node to
use (different
- nodes can have different expiry policies).
- </para>
- </listitem>
- </itemizedlist>
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:cache
key="entry-#{blogEntry.id}" region="pageFragments">
- <div class="blogEntry">
- <h3>#{blogEntry.title}</h3>
- <div>
- <s:formattedText value="#{blogEntry.body}"/>
- </div>
- <p>
- [Posted on 
- <h:outputText value="#{blogEntry.date}">
- <f:convertDateTime timezone="#{blog.timeZone}"
locale="#{blog.locale}"
- type="both"/>
- </h:outputText>]
- </p>
- </div>
-</s:cache>]]></programlisting>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
<para>
- <literal><s:conversationId></literal>
+ None.
</para>
- </entry>
- <entry valign="top">
+
+ </section>
+
+ <section>
+
<title><literal><s:link></literal></title>
+
<para><emphasis>Description</emphasis></para>
<para>
- Add the conversation id to JSF link or button (e.g.
<literal><h:commandLink /></literal>,
<literal><s:button /></literal>).
+ 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>
+ <literal>value</literal> — the label.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>action</literal> — a method binding
that
+ specified the action listener.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>view</literal> — the JSF view id to
link to.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fragment</literal> — the fragment
identifier
+ to link to.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>disabled</literal> — is the link
disabled?
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>propagation</literal> — determines
the
+ conversation propagation style:
<literal>begin</literal>,
+ <literal>join</literal>,
<literal>nest</literal>,
+ <literal>none</literal> or
<literal>end</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>pageflow</literal> — a pageflow
definition
+ to begin. (This is only useful when using
+ <literal>propagation="begin"</literal> or
+ <literal>propagation="join"</literal>.)
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para><emphasis>Usage</emphasis></para>
+ <programlisting role="XHTML"><![CDATA[<s:link
id="register" view="/register.xhtml"
+ value="Register New User"/>]]></programlisting>
<para>
- None.
+ You can specify both <literal>view</literal> and
+ <literal>action</literal> on <literal><s:link
/></literal>.
+ In this case, the action will be called once the redirect to the
+ specified view has occured.
</para>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
+
+ </section>
+
+ <section>
+
<title><literal><s:conversationPropagation></literal></title>
+
+ <para><emphasis>Description</emphasis></para>
<para>
- <literal><s:conversationPropagation></literal>
+ Customize the conversation propagation for a command link or button
+ (or similar JSF control). <emphasis>Facelets only.</emphasis>
</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><emphasis>Attributes</emphasis></para>
+ <itemizedlist>
+ <listitem>
<para>
<literal>type</literal> — determines the
conversation
- propagation style: <literal>begin</literal>,
<literal>join</literal>,
- <literal>nest</literal>,
<literal>none</literal> or <literal>end</literal>.
+ propagation style: <literal>begin</literal>,
+ <literal>join</literal>,
<literal>nest</literal>,
+ <literal>none</literal> or
<literal>end</literal>.
</para>
- </listitem>
- <listitem>
+ </listitem>
+ <listitem>
<para>
- <literal>pageflow</literal> — a pageflow
definition to begin.
- (This is only useful when
<literal>propagation="begin"</literal> or
- <literal>propagation="join"</literal>.)
+ <literal>pageflow</literal> — a pageflow
definition to
+ begin. (This is only useful when using
+ <literal>propagation="begin"</literal> or
+ <literal>propagation="join"</literal>.)
</para>
- </listitem>
- </itemizedlist>
- <para><emphasis>Usage</emphasis></para>
- <programlisting
role="XHTML"><![CDATA[<h:commandButton value="Apply"
action="#{personHome.update}">
- <s:conversationPropagation type="join" />
+ </listitem>
+ </itemizedlist>
+ <para><emphasis>Usage</emphasis></para>
+ <programlisting role="XHTML"><![CDATA[<h:commandButton
value="Apply" action="#{personHome.update}">
+ <s:conversationPropagation type="join" />
</h:commandButton>]]></programlisting>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
-
<para><literal><s:convertDateTime></literal></para>
- </entry>
- <entry valign="top">
- <para><emphasis>Description</emphasis></para>
+ </section>
+
+ <section>
+ <title>
+ <literal><s:defaultAction></literal>
+ </title>
+
<para>
- Perform date or time conversions in the Seam timezone.
+ <emphasis>Description</emphasis>
</para>
- <para><emphasis>Attributes</emphasis></para>
<para>
- None.
+ Specify the default action to run when the form is submitted using
+ the enter key.
</para>
+ <para>
+ Currently you can only nest it inside buttons (e.g.
+ <literal><h:commandButton /></literal>,
+ <literal><a:commandButton /></literal> or
+ <literal><tr:commandButton /></literal>).
+ </para>
+ <para>
+ You must specify an id on the action source. You can only have one
+ default action per form.
+ </para>
+
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>None.</para>
+
<para><emphasis>Usage</emphasis></para>
+ <programlisting role="XHTML"><![CDATA[<h:commandButton
id="foo" value="Foo" action="#{manager.foo}">
+ <s:defaultAction />
+</h:commandButton>]]></programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Converters and Validators</title>
+
+ <section>
+
<title><literal><s:convertDateTime></literal></title>
+
+ <para><emphasis>Description</emphasis></para>
+ <para>Perform date or time conversions in the Seam
timezone.</para>
+
+ <para><emphasis>Attributes</emphasis></para>
+ <para>None.</para>
+
+ <para><emphasis>Usage</emphasis></para>
<programlisting role="XHTML"><![CDATA[<h:outputText
value="#{item.orderDate}">
- <s:convertDateTime type="both" dateStyle="full"/>
+ <s:convertDateTime type="both" dateStyle="full"/>
</h:outputText>]]></programlisting>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
-
<para><literal><s:convertEntity></literal></para>
- </entry>
- <entry valign="top">
+
+ </section>
+
+ <section>
+
<title><literal><s:convertEntity></literal></title>
+
<para><emphasis>Description</emphasis></para>
<para>
- Assigns an entity converter to the current component. This is primarily
- useful for radio button and dropdown controls.
+ 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 managed entity which has an
<literal>@Id</literal> annotation -
- either simple or composite.
+ The converter works with any managed entity which has an
+ <literal>@Id</literal>
+ annotation - either simple or composite.
</para>
-
+
<para><emphasis>Attributes</emphasis></para>
-
- <para>
- None.
- </para>
-
+ <para>None.</para>
+
<para><emphasis>Configuration</emphasis></para>
-
+
<para>
- You must use <emphasis>Seam managed transactions</emphasis>
(see <xref linkend="persistence.seam-managed-transactions" />) with
<literal><s:convertEntity /></literal>.
+ You must use <emphasis>Seam managed transactions</emphasis>
(see
+ <xref linkend="persistence.seam-managed-transactions" />)
with
+ <literal><s:convertEntity /></literal>.
</para>
-
+
<para>
- If your <emphasis>Managed Persistence Context</emphasis>
isn't called
- <literal>entityManager</literal>, then you need to set it in
components.xml:
+ If your <emphasis>Managed Persistence Context</emphasis>
isn't
+ called <literal>entityManager</literal>, then you need to set
it in
+ components.xml:
</para>
<programlisting role="XML"><![CDATA[<component
name="org.jboss.seam.ui.EntityConverter">
- <property name="entityManager">#{em}</property>
+ <property name="entityManager">#{em}</property>
</component>]]></programlisting>
-
+
<para>
- If you are using a <emphasis>Managed Hibernate
Session</emphasis>
- then you need to set it in components.xml:
+ If you are using a <emphasis>Managed Hibernate
Session</emphasis>
+ then you need to set it in components.xml:
</para>
<programlisting role="XML"><![CDATA[<component
name="org.jboss.seam.ui.EntityConverter">
- <property name="session">#{hibernateSession}</property>
+ <property name="session">#{hibernateSession}</property>
</component>]]></programlisting>
-
+
<para>
- If you want to use more than one entity manager with the entity
- converter, you can create a copy of the entity converter for each
- entity manager in components.xml:
+ If you want to use more than one entity manager with the entity
+ converter, you can create a copy of the entity converter for each
+ entity manager in components.xml:
</para>
-
+
<programlisting role="XML"><![CDATA[<component
name="myEntityConverter"
class="org.jboss.seam.ui.converter.EntityConverter">
- <property name="entityManager">#{em}</property>
+ <property name="entityManager">#{em}</property>
</component>]]></programlisting>
-
+
<programlisting role="XHTML"><![CDATA[<h:selectOneMenu
value="#{person.continent}">
- <s:selectItems value="#{continents.resultList}" var="continent"
- label="#{continent.name}" />
- <f:converter converterId="myEntityConverter" />
+ <s:selectItems value="#{continents.resultList}" var="continent"
+ label="#{continent.name}" />
+ <f:converter converterId="myEntityConverter" />
</h:selectOneMenu>]]></programlisting>
-
+
<para><emphasis>Usage</emphasis></para>
<programlisting role="XHTML"><![CDATA[<h:selectOneMenu
value="#{person.continent}" required="true">
- <s:selectItems value="#{continents.resultList}" var="continent"
- label="#{continent.name}"
- noSelectionLabel="Please Select..."/>
- <s:convertEntity />
+ <s:selectItems value="#{continents.resultList}" var="continent"
+ label="#{continent.name}"
+ noSelectionLabel="Please Select..."/>
+ <s:convertEntity />
</h:selectOneMenu>]]></programlisting>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
-
<para><literal><s:convertEnum></literal></para>
- </entry>
-
- <entry valign="top">
+ </section>
+
+ <section>
+
<title><literal><s:convertEnum></literal></title>
+
<para><emphasis>Description</emphasis></para>
<para>
- Assigns an enum converter to the current component. This is primarily
- useful for radio button and dropdown controls.
+ Assigns an enum converter to the current component. This is
+ primarily useful for radio button and dropdown controls.
</para>
+
<para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
+ <para>None.</para>
+
<para><emphasis>Usage</emphasis></para>
<programlisting role="XHTML"><![CDATA[<h:selectOneMenu
value="#{person.honorific}">
- <s:selectItems value="#{honorifics}" var="honorific"
+ <s:selectItems value="#{honorifics}" var="honorific"
label="#{honorific.label}"
noSelectionLabel="Please select" />
- <s:convertEnum />
+ <s:convertEnum />
</h:selectOneMenu>]]></programlisting>
- </entry>
- </row>
+ </section>
+
+ <section>
+
<title><literal><s:validate></literal></title>
+
+ <para><emphasis>Description</emphasis></para>
+ <para>
+ A non-visual control, validates a JSF input field against the
+ bound property using Hibernate Validator.
+ </para>
+
+ <para><emphasis>Attributes</emphasis></para>
+ <para>
+ None.
+ </para>
+
+ <para><emphasis>Usage</emphasis></para>
+ <programlisting role="XHTML"><![CDATA[<h:inputText
id="userName" required="true"
+ value="#{customer.userName}">
+ <s:validate />
+</h:inputText>
+<h:message for="userName" styleClass="error"
/>]]></programlisting>
+ </section>
+
+ <section>
+
<title><literal><s:validateAll></literal></title>
- <row>
- <entry valign="top">
+ <para><emphasis>Description</emphasis></para>
<para>
- <literal><s:decorate></literal>
+ A non-visual control, validates all child JSF input fields
+ against their bound properties using Hibernate Validator.
</para>
- </entry>
- <entry valign="top">
+
+ <para><emphasis>Attributes</emphasis></para>
+ <para>
+ None.
+ </para>
+
+ <para><emphasis>Usage</emphasis></para>
+ <programlisting
role="XHTML"><![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>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Formatting</title>
+
+ <section>
+
<title><literal><s:decorate></literal></title>
+
<para><emphasis>Description</emphasis></para>
<para>
- "Decorate" a JSF input field when validation fails or when
- <literal>required="true"</literal> is set.
+ "Decorate" a JSF input field when validation fails or when
+ <literal>required="true"</literal> is set.
</para>
<para><emphasis>Attributes</emphasis></para>
<itemizedlist>
- <listitem>
- <para>
- <literal>template</literal> — the facelets
template to use to decorate the component
+ <listitem>
+ <para>
+ <literal>template</literal> — the facelets
template
+ to use to decorate the component
</para>
</listitem>
</itemizedlist>
<para>
- <literal>#{invalid}</literal> and
<literal>#{required}</literal> are
- available inside <literal>s:decorate</literal>;
<literal>#{required}</literal>
- evaluates to <literal>true</literal> if you have set the input
component
- being decorated as required, and <literal>#{invalid}</literal>
evaluates
- to <literal>true</literal> if a validation error occurs.
+ <literal>#{invalid}</literal> and
<literal>#{required}</literal>
+ are available inside <literal>s:decorate</literal>;
+ <literal>#{required}</literal> evaluates to
+ <literal>true</literal> if you have set the input component
being
+ decorated as required, and <literal>#{invalid}</literal>
+ evaluates to <literal>true</literal> if a validation error
occurs.
</para>
+
<para><emphasis>Usage</emphasis></para>
<programlisting role="XHTML"><![CDATA[<s:decorate
template="edit.xhtml">
- <ui:define name="label">Country:</ui:define>
- <h:inputText value="#{location.country}" required="true"/>
- </s:decorate>]]></programlisting>
- <programlisting role="XHTML"><![CDATA[<ui:composition
xmlns="http://www.w3.org/1999/xhtml"
- xmlns:ui="http://java.sun.com/jsf/facelets"
- xmlns:h="http://java.sun.com/jsf/html"
- xmlns:f="http://java.sun.com/jsf/core"
- xmlns:s="http://jboss.com/products/seam/taglib">
+ <ui:define name="label">Country:</ui:define>
+ <h:inputText value="#{location.country}"
required="true"/>
+ </s:decorate>]]></programlisting>
+ <programlisting role="XHTML"><![CDATA[<ui:composition
xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:ui="http://java.sun.com/jsf/facelets"
+ xmlns:h="http://java.sun.com/jsf/html"
+ xmlns:f="http://java.sun.com/jsf/core"
+ xmlns:s="http://jboss.com/products/seam/taglib">
- <div>
+ <div>
- <s:label styleClass="#{invalid?'error':''}">
- <ui:insert name="label"/>
- <s:span styleClass="required"
rendered="#{required}">*</s:span>
- </s:label>
+ <s:label styleClass="#{invalid?'error':''}">
+ <ui:insert name="label"/>
+ <s:span styleClass="required"
rendered="#{required}">*</s:span>
+ </s:label>
- <span class="#{invalid?'error':''}">
- <s:validateAll>
- <ui:insert/>
- </s:validateAll>
- </span>
+ <span class="#{invalid?'error':''}">
+ <s:validateAll>
+ <ui:insert/>
+ </s:validateAll>
+ </span>
- <s:message styleClass="error"/>
+ <s:message styleClass="error"/>
- </div>
+ </div>
</ui:composition>]]></programlisting>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
- <para>
- <literal><s:defaultAction></literal>
- </para>
- </entry>
- <entry valign="top">
+ </section>
+
+ <section>
+
<title><literal><s:div></literal></title>
+
<para><emphasis>Description</emphasis></para>
<para>
- Specify the default action to run when the form is submitted using
- the enter key.
+ Render a HTML <literal><div></literal>.
</para>
- <para>
- Currently you can only nest it inside buttons (e.g.
- <literal><h:commandButton /></literal>,
- <literal><a:commandButton /></literal> or
- <literal><tr:commandButton /></literal>).
- </para>
- <para>
- You must specify an id on the action source. You can only have one
- default action per form.
- </para>
+
<para><emphasis>Attributes</emphasis></para>
<para>
- None.
+ None.
</para>
+
<para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<h:commandButton
id="foo" value="Foo" action="#{manager.foo}">
- <s:defaultAction />
-</h:commandButton>]]></programlisting>
- </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>
- <para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:div
rendered="#{selectedMember == null}">
- Sorry, but this member does not exist.
+ <programlisting role="XHTML"><![CDATA[<s:div
rendered="#{selectedMember == null}">
+ Sorry, but this member does not exist.
</s:div>]]></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>
- <literal>enumValue</literal> — the string
representation of the enum
- value.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>label</literal> — the label to be used
when rendering the <literal>SelectItem</literal>.
- </para>
- </listitem>
- </itemizedlist>
- <para><emphasis>Usage</emphasis></para>
- <programlisting
role="XHTML"><![CDATA[<h:selectOneRadio id="radioList"
- layout="lineDirection"
- value="#{newPayment.paymentFrequency}">
- <s:convertEnum />
- <s:enumItem enumValue="ONCE" label="Only Once" />
- <s:enumItem enumValue="EVERY_MINUTE" label="Every Minute" />
- <s:enumItem enumValue="HOURLY" label="Every Hour" />
- <s:enumItem enumValue="DAILY" label="Every Day" />
- <s:enumItem enumValue="WEEKLY" label="Every Week" />
-</h:selectOneRadio>]]></programlisting>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
- <para>
- <literal><s:fileUpload></literal>
- </para>
- </entry>
- <entry valign="top">
+ </section>
+
+ <section>
+
<title><literal><s:span></literal></title>
+
<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:
+ Render a HTML <literal><span></literal>.
</para>
-
- <programlisting role="XHTML"><![CDATA[<h:form
enctype="multipart/form-data">]]></programlisting>
-
- <para>
- For multipart requests, the Seam Multipart servlet filter must also be
configured
- in <literal>web.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<filter>
- <filter-name>Seam Filter</filter-name>
- <filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
-</filter>
-
-<filter-mapping>
- <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>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>createTempFiles</literal> — if this
option is set to true, uploaded files are
- streamed to a temporary file instead of in memory.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>maxRequestSize</literal> — the maximum
size of a file upload request, in bytes.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Here's an example:
- </para>
-
- <programlisting role="XML"><![CDATA[<component
class="org.jboss.seam.web.MultipartFilter">
- <property name="createTempFiles">true</property>
- <property name="maxRequestSize">1000000</property>
-</component>]]></programlisting>
-
+
<para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>data</literal> — this value binding
receives the binary file data.
- The receiving field should be declared as a
<literal>byte[]</literal> or <literal>InputStream</literal>
(required).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>contentType</literal> — this value
binding receives the file's
- content type (optional).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fileName</literal> — this value binding
receives the filename (optional).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fileSize</literal> — this value binding
receives the file size (optional).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>accept</literal> — a comma-separated
list of content types to accept,
- may not be supported by the browser. E.g.
<literal>"images/png,images/jpg"</literal>,
- <literal>"images/*"</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>style</literal> — The control's
style
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>styleClass</literal> — The control's
style class
- </para>
- </listitem>
- </itemizedlist>
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:fileUpload
id="picture" data="#{register.picture}"
- accept="image/png"
- contentType="#{register.pictureContentType}"
/>]]></programlisting>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
-
<para><literal><s:formattedText></literal></para>
- </entry>
- <entry valign="top">
- <para><emphasis>Description</emphasis></para>
<para>
- Outputs <emphasis>Seam Text</emphasis>, a rich text markup
useful for blogs, wikis and
- other applications that might use rich text. See the Seam Text chapter
for full usage.
+ None.
</para>
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — an EL expression
specifying the rich text markup to render.
- </para>
- </listitem>
- </itemizedlist>
+
<para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:formattedText
value="#{blog.text}"/>]]></programlisting>
- <para><emphasis>Example</emphasis></para>
- <mediaobject>
- <imageobject role="fo" scalefit="1">
- <imagedata fileref="images/controls-seamtext.png"
align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/controls-seamtext.png"
align="center"/>
- </imageobject>
- </mediaobject>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
- <para>
- <literal><s:fragment></literal>
- </para>
- </entry>
- <entry valign="top">
+ <programlisting role="XHTML"><![CDATA[<s:span
styleClass="required"
rendered="#{required}">*</s:span>]]></programlisting>
+
+ </section>
+
+ <section>
+
<title><literal><s:fragment></literal></title>
+
<para><emphasis>Description</emphasis></para>
<para>
- A non-rendering component useful for enabling/disabling rendering of
it's children.
+ A non-rendering component useful for enabling/disabling rendering
+ of it's children.
</para>
+
<para><emphasis>Attributes</emphasis></para>
<para>
- None.
+ None.
</para>
+
<para><emphasis>Usage</emphasis></para>
<programlisting role="XHTML"><![CDATA[<s:fragment
rendered="#{auction.highBidder ne null}">
- Current bid:
+ Current bid:
</s:fragment>]]></programlisting>
- </entry>
- </row>
+
+ </section>
+
+ <section>
+
<title><literal><s:label></literal></title>
- <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.
+ "Decorate" a JSF input field with the label. The label is
placed
+ inside the HTML <literal><label></literal> tag,
and is
+ associated with the nearest JSF input component. It is often
+ used with <literal><s:decorate></literal>.
</para>
- <para>
- All attributes for
<literal><h:graphicImage></literal> are supported, as well as:
- </para>
<para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
+ <itemizedlist>
<listitem>
- <para>
- <literal>value</literal> — image to display. Can
be a path <literal>String</literal>
- (loaded from the classpath), a <literal>byte[]</literal>, a
<literal>java.io.File</literal>,
- a <literal>java.io.InputStream</literal> or a
<literal>java.net.URL</literal>. Currently supported
- image formats are <literal>image/png</literal>,
<literal>image/jpeg</literal> and <literal>image/gif</literal>.
- </para>
+ <para>
+ <literal>style</literal> — The control's
style
+ </para>
</listitem>
- <listitem>
- <para>
- <literal>fileName</literal> — if not specified the
served image will have a generated file name.
- If you want to name your file, you should specify it here. This name
should be unique
- </para>
+ <listitem>
+ <para>
+ <literal>styleClass</literal> — The
control's style class
+ </para>
</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>
- <listitem>
- <itemizedlist>
- <listitem>
- <para>
- <literal>width</literal> — new width of the
image
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>height</literal> — new height of
the image
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>maintainRatio</literal> — if
<literal>true</literal>, and <emphasis>one</emphasis> of
-
<literal>width</literal>/<literal>height</literal> are specified,
the image will be resized with the
- dimension not specified being calculated to maintain the aspect
ratio.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>factor</literal> — scale the image
by the given factor
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
-
<term><literal><s:transformImageBlur></literal></term>
- <listitem>
- <itemizedlist>
- <listitem>
- <para>
- <literal>radius</literal> — perform a
convolution blur with the given radius
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
-
<term><literal><s:transformImageType></literal></term>
- <listitem>
- <itemizedlist>
- <listitem>
- <para>
- <literal>contentType</literal> — alter the
type of the image to either <literal>image/jpeg</literal> or
<literal>image/png</literal>
- </para>
- </listitem>
- </itemizedlist>
- </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>
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:graphicImage
rendered="#{auction.image ne null}"
- value="#{auction.image.data}">
- <s:transformImageSize width="200" maintainRatio="true"/>
-</s:graphicImage>]]></programlisting>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
- <para>
- <literal><s:label></literal>
- </para>
- </entry>
- <entry valign="top">
- <para><emphasis>Description</emphasis></para>
- <para>
- "Decorate" a JSF input field with the label. The label is placed
inside
- the HTML <literal><label></literal> tag, and is
associated with the
- nearest JSF input component. It is often used with
<literal><s:decorate></literal>.
- </para>
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>style</literal> — The control's
style
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>styleClass</literal> — The control's
style class
- </para>
- </listitem>
</itemizedlist>
+
<para><emphasis>Usage</emphasis></para>
<programlisting role="XHTML"><![CDATA[<s:label
styleClass="label">
Country:
</s:label>
<h:inputText value="#{location.country}"
required="true"/>]]></programlisting>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
- <para>
- <literal><s:link></literal>
- </para>
- </entry>
- <entry valign="top">
+ </section>
+
+ <section>
+
<title><literal><s:message></literal></title>
+
<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>
+ "Decorate" a JSF input field with the validation error message.
</para>
+
<para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — the label.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>action</literal> — a method binding that
specified
- the action listener.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>view</literal> — the JSF view id to link
to.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fragment</literal> — the fragment
identifier to link to.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>disabled</literal> — is the link
disabled?
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>propagation</literal> — determines the
conversation
- propagation style: <literal>begin</literal>,
<literal>join</literal>,
- <literal>nest</literal>,
<literal>none</literal> or <literal>end</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pageflow</literal> — a pageflow
definition to begin.
- (This is only useful when
<literal>propagation="begin"</literal> or
- <literal>propagation="join"</literal>.)
- </para>
- </listitem>
- </itemizedlist>
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:link
id="register" view="/register.xhtml"
- value="Register New User"/>]]></programlisting>
<para>
- You can specify both <literal>view</literal> and
<literal>action</literal>
- on <literal><s:link /></literal>. In this case,
the action
- will be called once the redirect to the specified view has
- occured.
+ None.
</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>
- <para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
+
<para><emphasis>Usage</emphasis></para>
<programlisting role="XHTML"><![CDATA[<f:facet
name="afterInvalidField">
<s:span>
@@ -873,486 +614,579 @@
<s:message/>
</s:span>
</f:facet>]]></programlisting>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
- <para>
- <literal><s:remote></literal>
- </para>
- </entry>
- <entry valign="top">
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Seam Text</title>
+
+ <section>
+
<title><literal><s:validateFormattedText></literal></title>
+
<para><emphasis>Description</emphasis></para>
<para>
- Generates the Javascript stubs required to use Seam Remoting.
+ Checks that the submitted value is valid Seam Text
</para>
+
<para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>include</literal> — a comma-separated
list of the component names (or fully qualified class names)
- for which to generate Seam Remoting Javascript stubs. See <xref
linkend="remoting"/> for more details.
- </para>
- </listitem>
- </itemizedlist>
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:remote
include="customerAction,accountAction,com.acme.MyBean"/>]]></programlisting>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
<para>
- <literal><s:selectDate></literal>
+ None.
</para>
- </entry>
- <entry valign="top">
+ </section>
+
+ <section>
+
<title><literal><s:formattedText></literal></title>
+
<para><emphasis>Description</emphasis></para>
<para>
- <emphasis>Deprecated. Use <literal><rich:calendar
/></literal> instead.</emphasis>
+ Outputs <emphasis>Seam Text</emphasis>, a rich text markup
useful
+ for blogs, wikis and other applications that might use rich text.
+ See the Seam Text chapter for full usage.
</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
contain HTML elements, such as
- text or an image, that prompt the user to click to display the date
picker. The date picker
- <emphasis>must</emphasis> be styled using CSS. An example CSS
file can be found in the Seam
- booking demo as <literal>date.css</literal>, or can be
generated using seam-gen. The CSS
- styles used to control the appearance of the date picker are also
described below.
- </para>
-
+
<para><emphasis>Attributes</emphasis></para>
<itemizedlist>
<listitem>
- <para>
- <literal>for</literal> — The id of the input
field that the date picker will insert the
- selected date into.
- </para>
+ <para>
+ <literal>value</literal> — an EL expression
specifying
+ the rich text markup to render.
+ </para>
</listitem>
- <listitem>
- <para>
- <literal>dateFormat</literal> — The date format
string. This should match the date format of the
- input field.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>startYear</literal> — The popup year
selector range will start at this year.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>endYear</literal> — The popup year
selector range will end at this year.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>firstDayOfWeek</literal> — Controls
which day is the first day of the week
- (0 = Sunday, 6 = Saturday). If this attribute is not set, then the
first day of the week will
- default based on the user's locale.
- </para>
- </listitem>
</itemizedlist>
-
+
<para><emphasis>Usage</emphasis></para>
+ <programlisting role="XHTML"><![CDATA[<s:formattedText
value="#{blog.text}"/>]]></programlisting>
- <programlisting role="XHTML"><![CDATA[<div
class="row">
- <h:outputLabel for="dob">Date of
birth<em>*</em></h:outputLabel>
- <h:inputText id="dob" value="#{user.dob}"
required="true">
- <s:convertDateTime pattern="MM/dd/yyyy"/>
- </h:inputText>
- <s:selectDate for="dob" startYear="1910"
endYear="2007">
- <img src="img/datepicker.png"/>
- </s:selectDate>
- <div class="validationError"><h:message
for="dob"/></div>
-</div>]]></programlisting>
-
-
<para><emphasis>Example</emphasis></para>
<mediaobject>
<imageobject role="fo">
- <imagedata fileref="images/controls-selectdate.png"
align="center"/>
+ <imagedata fileref="images/controls-seamtext.png"
align="center" scalefit="1"/>
</imageobject>
<imageobject role="html">
- <imagedata fileref="images/controls-selectdate.png"
align="center"/>
+ <imagedata fileref="images/controls-seamtext.png"
align="center"/>
</imageobject>
</mediaobject>
-
- <para><emphasis>CSS Styling</emphasis></para>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Dropdowns</title>
+
+ <section>
+
<title><literal><s:enumItem></literal></title>
+
+ <para><emphasis>Description</emphasis></para>
<para>
- The following list describes the CSS class names that are used to control
the style of the selectDate control.
+ Creates a <literal>SelectItem</literal> from an enum value.
</para>
+
+ <para><emphasis>Attributes</emphasis></para>
<itemizedlist>
- <listitem>
- <para>
- <literal>seam-date</literal> — This class is
applied to the outer <literal>div</literal> containing the
- popup calendar. (1) It is also applied to the
<literal>table</literal> that controls the inner layout of the
- calendar. (2)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-header</literal> — This class
is applied to the calendar header table row (<literal>tr</literal>)
- and header table cells (<literal>td</literal>). (3)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-header-prevMonth</literal> —
This class is applied to the "previous month" table cell,
- (<literal>td</literal>), which when clicked causes the
calendar to display the month prior to the one currently
- displayed. (4)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-header-nextMonth</literal> —
This class is applied to the "next month" table cell,
- (<literal>td</literal>), which when clicked causes the
calendar to display the month following the one currently
- displayed. (5)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-headerDays</literal> — This
class is applied to the calendar days header row
- (<literal>tr</literal>), which contains the names of the
week days. (6)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-footer</literal> — This class
is applied to the calendar footer row
- (<literal>tr</literal>), which displays the current date.
(7)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-inMonth</literal> — This class
is applied to the table cell
- (<literal>td</literal>) elements that contain a date within
the month currently displayed. (8)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-outMonth</literal> — This
class is applied to the table cell
- (<literal>td</literal>) elements that contain a date
outside of the month currently displayed. (9)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-selected</literal> — This
class is applied to the table cell
- (<literal>td</literal>) element that contains the currently
selected date. (10)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-dayOff-inMonth</literal> —
This class is applied to the table cell
- (<literal>td</literal>) elements that contain a "day
off" date (i.e. weekend days, Saturday and Sunday)
- within the currently selected month. (11)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-dayOff-outMonth</literal> —
This class is applied to the table cell
- (<literal>td</literal>) elements that contain a "day
off" date (i.e. weekend days, Saturday and Sunday)
- outside of the currently selected month. (12)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-hover</literal> — This class
is applied to the table cell
- (<literal>td</literal>) element over which the cursor is
hovering. (13)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-monthNames</literal> — This
class is applied to the <literal>div</literal>
- control that contains the popup month selector. (14)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-monthNameLink</literal> — This
class is applied to the anchor (<literal>a</literal>)
- controls that contain the popup month names. (15)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-years </literal> — This class
is applied to the <literal>div</literal>
- control that contains the popup year selector. (16)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>seam-date-yearLink</literal> — This
class is applied to the anchor (<literal>a</literal>)
- controls that contain the popup years. (15)
- </para>
- </listitem>
+ <listitem>
+ <para>
+ <literal>enumValue</literal> — the string
+ representation of the enum value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>label</literal> — the label to be
used when
+ rendering the <literal>SelectItem</literal>.
+ </para>
+ </listitem>
</itemizedlist>
+
+ <para><emphasis>Usage</emphasis></para>
+ <programlisting role="XHTML"><![CDATA[<h:selectOneRadio
id="radioList"
+ layout="lineDirection"
+ value="#{newPayment.paymentFrequency}">
+ <s:convertEnum />
+ <s:enumItem enumValue="ONCE" label="Only Once" />
+ <s:enumItem enumValue="EVERY_MINUTE" label="Every Minute"
/>
+ <s:enumItem enumValue="HOURLY" label="Every Hour" />
+ <s:enumItem enumValue="DAILY" label="Every Day" />
+ <s:enumItem enumValue="WEEKLY" label="Every Week" />
+</h:selectOneRadio>]]></programlisting>
+ </section>
+
+ <section>
+
<title><literal><s:selectItems></literal></title>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/controls-selectdatecss.png"
align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/controls-selectdatecss.png"
align="center"/>
- </imageobject>
- </mediaobject>
- </entry>
- </row>
-
- <row>
- <entry valign="top">
+ <para><emphasis>Description</emphasis></para>
<para>
- <literal><s:selectItems></literal>
+ Creates a <literal>List<SelectItem></literal>
from a List, Set, DataModel or Array.
</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>
+
+ <para><emphasis>Attributes</emphasis></para>
+ <itemizedlist>
<listitem>
- <para>
- <literal>value</literal> — an EL expression
specifying the data that backs the
<literal>List<SelectItem></literal>
- </para>
+ <para>
+ <literal>value</literal> — an EL expression
+ specifying the data that backs the
+ <literal>List<SelectItem></literal>
+ </para>
</listitem>
- <listitem>
- <para>
- <literal>var</literal> — defines the name of
the local variable that holds the current object during iteration
- </para>
+ <listitem>
+ <para>
+ <literal>var</literal>— defines the name of
the local
+ variable that holds the current object during iteration
+ </para>
</listitem>
<listitem>
- <para>
- <literal>label</literal> — the label to be
used when rendering the <literal>SelectItem</literal>. Can reference
- the <literal>var</literal> variable
- </para>
+ <para>
+ <literal>label</literal> — the label to be
used when
+ rendering the <literal>SelectItem</literal>. Can
reference
+ the <literal>var</literal> variable.
+ </para>
</listitem>
<listitem>
- <para>
- <literal>itemValue</literal> — Value to return
to the server if this option is selected. Optional, by default the
<literal>var</literal> object is used. Can reference the
<literal>var</literal> variable
- </para>
+ <para>
+ <literal>itemValue</literal> — Value to return
to the
+ server if this option is selected. Optional, by default the
+ <literal>var</literal> object is used. Can reference
the
+ <literal>var</literal> variable.
+ </para>
</listitem>
-
- <listitem>
- <para>
- <literal>disabled</literal> — if true the
<literal>SelectItem</literal> will be rendered disabled. Can reference
- the <literal>var</literal> variable
- </para>
+
+ <listitem>
+ <para>
+ <literal>disabled</literal>
+ — if true the <literal>SelectItem</literal>
will be
+ rendered disabled. Can reference the
<literal>var</literal>
+ variable.
+ </para>
</listitem>
<listitem>
- <para>
- <literal>noSelectionLabel</literal> —
specifies the (optional) label to place at the top of list (if
- <literal>required="true"</literal> is also
specified then selecting this value will cause a validation error)
- </para>
+ <para>
+ <literal>noSelectionLabel</literal> —
specifies the
+ (optional) label to place at the top of list (if
+ <literal>required="true"</literal> is also
specified then
+ selecting this value will cause a validation error).
+ </para>
</listitem>
<listitem>
- <para>
- <literal>hideNoSelectionLabel</literal> — if
true, the <literal>noSelectionLabel</literal> will be hidden
- when a value is selected
- </para>
+ <para>
+ <literal>hideNoSelectionLabel</literal> — if
true,
+ the <literal>noSelectionLabel</literal> will be hidden
when
+ a value is selected
+ </para>
</listitem>
- </itemizedlist>
- <para><emphasis>Usage</emphasis></para>
+ </itemizedlist>
+ <para><emphasis>Usage</emphasis></para>
<programlisting role="XHTML"><![CDATA[<h:selectOneMenu
value="#{person.age}"
converter="ageConverter">
<s:selectItems value="#{ages}" var="age"
label="#{age}" />
</h:selectOneMenu>]]></programlisting>
- </entry>
- </row>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Other</title>
+
+ <section>
+
<title><literal><s:cache></literal></title>
- <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>.
+ 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>
- <para>
- None.
- </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>key</literal> — the key to cache
rendered
+ content, often a value expression. For example, if we were
+ caching a page fragment that displays a document, we might
+ use
<literal>key="Document-#{document.id}"</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>enabled</literal> — a value
expression that
+ determines if the cache should be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>region</literal> — a JBoss Cache node
to use
+ (different nodes can have different expiry policies).
+ </para>
+ </listitem>
+ </itemizedlist>
+
<para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:span
styleClass="required"
rendered="#{required}">*</s:span>]]></programlisting>
- </entry>
- </row>
+ <programlisting role="XHTML"><![CDATA[<s:cache
key="entry-#{blogEntry.id}" region="pageFragments">
+ <div class="blogEntry">
+ <h3>#{blogEntry.title}</h3>
+ <div>
+ <s:formattedText value="#{blogEntry.body}"/>
+ </div>
+ <p>
+ [Posted on 
+ <h:outputText value="#{blogEntry.date}">
+ <f:convertDateTime timezone="#{blog.timeZone}"
locale="#{blog.locale}"
+ type="both"/>
+ </h:outputText>]
+ </p>
+ </div>
+</s:cache>]]></programlisting>
+
+ </section>
- <row>
- <entry valign="top">
- <para>
- <literal><s:taskId></literal>
- </para>
- </entry>
- <entry valign="top">
+ <section>
+
<title><literal><s:fileUpload></literal></title>
+
<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>.
- </para>
- <para><emphasis>Attributes</emphasis></para>
<para>
- None.
+ 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:
</para>
- </entry>
- </row>
- <row>
- <entry valign="top">
+ <programlisting role="XHTML"><![CDATA[<h:form
enctype="multipart/form-data">]]></programlisting>
+
<para>
- <literal><s:validate></literal>
+ For multipart requests, the Seam Multipart servlet filter must
+ also be configured in <literal>web.xml</literal>:
</para>
- </entry>
- <entry valign="top">
- <para><emphasis>Description</emphasis></para>
+
+ <programlisting role="XML"><![CDATA[<filter>
+ <filter-name>Seam Filter</filter-name>
+ <filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
+</filter>
+
+<filter-mapping>
+ <filter-name>Seam Filter</filter-name>
+ <url-pattern>/*</url-pattern>
+</filter-mapping>]]></programlisting>
+
+ <para><emphasis>Configuration</emphasis></para>
+
<para>
- A non-visual control, validates a JSF input field against the bound
- property using Hibernate Validator.
+ The following configuration options for multipart requests may be
+ configured in components.xml:
</para>
- <para><emphasis>Attributes</emphasis></para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>createTempFiles</literal> — if this
option
+ is set to true, uploaded files are streamed to a temporary
+ file instead of in memory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>maxRequestSize</literal> — the
maximum size
+ of a file upload request, in bytes.
+ </para>
+ </listitem>
+ </itemizedlist>
+
<para>
- None.
+ Here's an example:
</para>
+
+ <programlisting role="XML"><![CDATA[<component
class="org.jboss.seam.web.MultipartFilter">
+ <property name="createTempFiles">true</property>
+ <property name="maxRequestSize">1000000</property>
+</component>]]></programlisting>
+
+ <para><emphasis>Attributes</emphasis></para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>data</literal> — this value binding
receives
+ the binary file data. The receiving field should be
+ declared as a <literal>byte[]</literal> or
+ <literal>InputStream</literal> (required).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>contentType</literal> — this value
binding
+ receives the file's content type (optional).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fileName</literal> — this value
binding
+ receives the filename (optional).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fileSize</literal> — this value
binding
+ receives the file size (optional).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>accept</literal> — a comma-separated
list of
+ content types to accept, may not be supported by the
+ browser. E.g.
<literal>"images/png,images/jpg"</literal>,
+ <literal>"images/*"</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>style</literal> — The control's
style
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>styleClass</literal> — The
control's style
+ class
+ </para>
+ </listitem>
+ </itemizedlist>
<para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<h:inputText
id="userName" required="true"
- value="#{customer.userName}">
- <s:validate />
-</h:inputText>
-<h:message for="userName" styleClass="error"
/>]]></programlisting>
- </entry>
- </row>
+ <programlisting role="XHTML"><![CDATA[<s:fileUpload
id="picture" data="#{register.picture}"
+ accept="image/png"
+ contentType="#{register.pictureContentType}"
/>]]></programlisting>
+
+ </section>
- <row>
- <entry valign="top">
-
<para><literal><s:validateAll></literal></para>
- </entry>
- <entry valign="top">
+ <section>
+
<title><literal><s:graphicImage></literal></title>
+
<para><emphasis>Description</emphasis></para>
<para>
- A non-visual control, validates all child JSF input fields against their
bound
- properties using Hibernate Validator.
+ 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.
</para>
+ <para>
+ All attributes for
<literal><h:graphicImage></literal> are
+ supported, as well as:
+ </para>
+
<para><emphasis>Attributes</emphasis></para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — image to display.
Can be
+ a path <literal>String</literal> (loaded from the
+ classpath), a <literal>byte[]</literal>, a
+ <literal>java.io.File</literal>, a
+ <literal>java.io.InputStream</literal> or a
+ <literal>java.net.URL</literal>. Currently supported
image
+ formats are <literal>image/png</literal>,
+ <literal>image/jpeg</literal> and
+ <literal>image/gif</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fileName</literal> — if not specified
the
+ served image will have a generated file name. If you want
+ to name your file, you should specify it here. This name
+ should be unique
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para><emphasis>Transformations</emphasis></para>
<para>
- None.
+ To apply a transform to the image, you would nest a tag
+ specifying the transform to apply. Seam currently supports these
+ transforms:
</para>
- <para><emphasis>Usage</emphasis></para>
- <programlisting
role="XHTML"><![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">
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal><s:transformImageSize></literal>
+ </term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>width</literal> — new width
of the
+ image
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>height</literal> — new
height of the
+ image
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>maintainRatio</literal> —
if
+ <literal>true</literal>, and
+ <emphasis>one</emphasis> of
+
<literal>width</literal>/<literal>height</literal>
+ are specified, the image will be resized with the
+ dimension not specified being calculated to
+ maintain the aspect ratio.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>factor</literal> — scale the
image
+ by the given factor
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal><s:transformImageBlur></literal>
+ </term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>radius</literal> — perform a
+ convolution blur with the given radius
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal><s:transformImageType></literal>
+ </term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>contentType</literal> —
alter the
+ type of the image to either
+ <literal>image/jpeg</literal> or
+ <literal>image/png</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
<para>
- <literal><s:validateFormattedText></literal>
+ It's easy to create your own transform - create a
+ <literal>UIComponent</literal> which implements
+
<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>
- </entry>
- <entry valign="top">
+ <para><emphasis>Usage</emphasis></para>
+ <programlisting role="XHTML"><![CDATA[<s:graphicImage
rendered="#{auction.image ne null}"
+ value="#{auction.image.data}">
+ <s:transformImageSize width="200" maintainRatio="true"/>
+</s:graphicImage>]]></programlisting>
+ </section>
+
+ <section>
+
<title><literal><s:remote></literal></title>
+
<para><emphasis>Description</emphasis></para>
<para>
- Checks that the submitted value is valid Seam Text
+ Generates the Javascript stubs required to use Seam Remoting.
</para>
+
<para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
- </entry>
- </row>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>include</literal> — a comma-separated
list
+ of the component names (or fully qualified class names)for
+ which to generate Seam Remoting Javascript stubs. See
+ <xref linkend="remoting"/> for more details.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para><emphasis>Usage</emphasis></para>
+ <programlisting role="XHTML"><![CDATA[<s:remote
include="customerAction,accountAction,com.acme.MyBean"/>]]></programlisting>
+ </section>
+ </section>
+ </section>
- </tbody>
- </tgroup>
- </table>
-</section>
-<section id="controls.annotations">
- <title>Annotations</title>
-
- <para>
- Seam also provides annotations to allow you to use Seam components as JSF
- converters and validators:
-
- </para>
- <variablelist spacing="compact">
- <varlistentry>
- <term>
- <literal>@Converter</literal>
- </term>
- <listitem>
- <programlisting
role="JAVA"><![CDATA[@Name("itemConverter")
-@BypassInterceptors
-@Converter
-public class ItemConverter implements Converter {
-
- @Transactional
- public Object getAsObject(FacesContext context, UIComponent cmp, String value) {
- EntityManager entityManager = (EntityManager)
Component.getInstance("entityManager");
- entityManager.joinTransaction();
- // Do the conversion
- }
-
- public String getAsString(FacesContext context, UIComponent cmp, Object value) {
- // Do the conversion
- }
-
-}]]></programlisting>
- <programlisting role="XHTML"><![CDATA[<h:inputText
value="#{shop.item}" converter="itemConverter"
/>]]></programlisting>
-
- <para>
- Registers the Seam component as a JSF converter. Shown here is a
- converter which is able to access the JPA EntityManager inside a
- JTA transaction, when converting the value back to it's object
- representation.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>@Validator</literal>
- </term>
- <listitem>
- <programlisting
role="JAVA"><![CDATA[@Name("itemValidator")
-@BypassInterceptors
-@Validator
-public class ItemValidator implements Validator {
+ <section id="controls.annotations">
+ <title>Annotations</title>
+
+ <para>
+ Seam also provides annotations to allow you to use Seam components as JSF
+ converters and validators:
+
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>@Converter</literal>
+ </term>
+ <listitem>
+ <programlisting
role="JAVA"><![CDATA[@Name("itemConverter")
+ @BypassInterceptors
+ @Converter
+ public class ItemConverter implements Converter {
+
+ @Transactional
+ public Object getAsObject(FacesContext context, UIComponent cmp, String value) {
+ EntityManager entityManager = (EntityManager)
Component.getInstance("entityManager");
+ entityManager.joinTransaction();
+ // Do the conversion
+ }
+
+ public String getAsString(FacesContext context, UIComponent cmp, Object value) {
+ // Do the conversion
+ }
+
+ }]]></programlisting>
- public void validate(FacesContext context, UIComponent cmp, Object value)
- throws ValidatorException {
- ItemController ItemController = (ItemController)
Component.getInstance("itemController");
- return itemController.validate(value);
- }
-
- }]]></programlisting>
-
- <programlisting role="XHTML"><![CDATA[<h:inputText
value="#{shop.item}" validator="itemValidator"
/>]]></programlisting>
- <para>
- Registers the Seam component as a JSF validator. Shown here is a
- validator which injects another Seam component; the injected
- component is used to validate the value.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-</section>
+ <programlisting role="XHTML"><![CDATA[<h:inputText
value="#{shop.item}" converter="itemConverter"
/>]]></programlisting>
+
+ <para>
+ Registers the Seam component as a JSF converter. Shown here is a
+ converter which is able to access the JPA EntityManager inside a
+ JTA transaction, when converting the value back to it's object
+ representation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <literal>@Validator</literal>
+ </term>
+ <listitem>
+ <programlisting
role="JAVA"><![CDATA[@Name("itemValidator")
+ @BypassInterceptors
+ @Validator
+ public class ItemValidator implements Validator {
+
+ public void validate(FacesContext context, UIComponent cmp, Object value)
+ throws ValidatorException {
+ ItemController ItemController = (ItemController)
Component.getInstance("itemController");
+ return itemController.validate(value);
+ }
+
+ }]]></programlisting>
+
+ <programlisting role="XHTML"><![CDATA[<h:inputText
value="#{shop.item}" validator="itemValidator"
/>]]></programlisting>
+ <para>
+ Registers the Seam component as a JSF validator. Shown here is a
+ validator which injects another Seam component; the injected
+ component is used to validate the value.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
</chapter>
6074
days inactive
6074
days old
0 comments
1 participants
participants (1)
-
seam-commits＠lists.jboss.org