Chapter 28. Seam JSF controls

`<s:button>`	Description A button that supports invocation of an action with control over conversation propagation. Does not submit the form. Attributes `value` — the label. `action` — a method binding that specified the action listener. `view` — the JSF view id to link to. `fragment` — the fragment identifier to link to. `disabled` — is the link disabled? `propagation` — determines the conversation propagation style: `begin`, `join`, `nest`, `none` or `end`. `pageflow` — a pageflow definition to begin. (This is only useful when `propagation="begin"` or `propagation="join"`.) Usage <s:button id="cancel" value="Cancel" action="#{hotelBooking.cancel}"/> You can specify both `view` and `action` on `<s:link />`. In this case, the action will be called once the redirect to the specified view has occured.
`<s:cache>`	Description Cache the rendered page fragment using JBoss Cache. Note that `<s:cache>` actually uses the instance of JBoss Cache managed by the built-in `pojoCache` component. Attributes `key` — 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 `key="Document-#{document.id}"`. `enabled` — a value expression that determines if the cache should be used. `region` — a JBoss Cache node to use (different nodes can have different expiry policies). Usage <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>
`<s:conversationId>`	Description Add the conversation id to JSF link or button (e.g. `<h:commandLink />`, `<s:button />`). Attributes None.
`<s:conversationPropagation>`	Description Customize the conversation propagation for a command link or button (or similar JSF control). Facelets only. Attributes `type` — determines the conversation propagation style: `begin`, `join`, `nest`, `none` or `end`. `pageflow` — a pageflow definition to begin. (This is only useful when `propagation="begin"` or `propagation="join"`.) Usage <h:commandButton value="Apply" action="#{personHome.update}"> <s:conversationPropagation type="join" /> </h:commandButton>
`<s:convertDateTime>`	Description Perform date or time conversions in the Seam timezone. Attributes None. Usage <h:outputText value="#{item.orderDate}"> <s:convertDateTime type="both" dateStyle="full"/> </h:outputText>
`<s:convertEntity>`	Description Assigns an entity converter to the current component. This is primarily useful for radio button and dropdown controls. The converter works with any managed entity which has an `@Id` annotation - either simple or composite. Attributes None. Configuration You must use Seam managed transactions (see Section 8.2, “Seam managed transactions”) with `<s:convertEntity />`. If your Managed Persistence Context isn't called `entityManager`, then you need to set it in components.xml: <component name="org.jboss.seam.ui.EntityConverter"> <property name="entityManager">#{em}</property> </component> If you are using a Managed Hibernate Session then you need to set it in components.xml: <component name="org.jboss.seam.ui.EntityConverter"> <property name="session">#{hibernateSession}</property> </component> 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: <component name="myEntityConverter" class="org.jboss.seam.ui.converter.EntityConverter"> <property name="entityManager">#{em}</property> </component> <h:selectOneMenu value="#{person.continent}"> <s:selectItems value="#{continents.resultList}" var="continent" label="#{continent.name}" /> <f:converter converterId="myEntityConverter" /> </h:selectOneMenu> Usage <h:selectOneMenu value="#{person.continent}" required="true"> <s:selectItems value="#{continents.resultList}" var="continent" label="#{continent.name}" noSelectionLabel="Please Select..."/> <s:convertEntity /> </h:selectOneMenu>
`<s:convertEnum>`	Description Assigns an enum converter to the current component. This is primarily useful for radio button and dropdown controls. Attributes None. Usage <h:selectOneMenu value="#{person.honorific}"> <s:selectItems value="#{honorifics}" var="honorific" label="#{honorific.label}" noSelectionLabel="Please select" /> <s:convertEnum /> </h:selectOneMenu>
`<s:decorate>`	Description "Decorate" a JSF input field when validation fails or when `required="true"` is set. Attributes `template` — the facelets template to use to decorate the component `#{invalid}` and `#{required}` are available inside `s:decorate`; `#{required}` evaluates to `true` if you have set the input component being decorated as required, and `#{invalid}` evaluates to `true` if a validation error occurs. Usage <s:decorate template="edit.xhtml"> <ui:define name="label">Country:</ui:define> <h:inputText value="#{location.country}" required="true"/> </s:decorate> <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> <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> <s:message styleClass="error"/> </div> </ui:composition>
`<s:defaultAction>`	Description Specify the default action to run when the form is submitted using the enter key. Currently you can only nest it inside buttons (e.g. `<h:commandButton />`, `<a:commandButton />` or `<tr:commandButton />`). You must specify an id on the action source. You can only have one default action per form. Attributes None. Usage <h:commandButton id="foo" value="Foo" action="#{manager.foo}"> <s:defaultAction /> </h:commandButton>
`<s:div>`	Description Render a HTML `<div>`. Attributes None. Usage <s:div rendered="#{selectedMember == null}"> Sorry, but this member does not exist. </s:div>
`<s:enumItem>`	Description Creates a `SelectItem` from an enum value. Attributes `enumValue` — the string representation of the enum value. `label` — the label to be used when rendering the `SelectItem`. Usage <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>
`<s:fileUpload>`	Description Renders a file upload control. This control must be used within a form with an encoding type of `multipart/form-data`, i.e: <h:form enctype="multipart/form-data"> For multipart requests, the Seam Multipart servlet filter must also be configured in `web.xml`: <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> Configuration* The following configuration options for multipart requests may be configured in components.xml: `createTempFiles` — if this option is set to true, uploaded files are streamed to a temporary file instead of in memory. `maxRequestSize` — the maximum size of a file upload request, in bytes. Here's an example: <component class="org.jboss.seam.web.MultipartFilter"> <property name="createTempFiles">true</property> <property name="maxRequestSize">1000000</property> </component> Attributes `data` — this value binding receives the binary file data. The receiving field should be declared as a `byte[]` or `InputStream` (required). `contentType` — this value binding receives the file's content type (optional). `fileName` — this value binding receives the filename (optional). `fileSize` — this value binding receives the file size (optional). `accept` — a comma-separated list of content types to accept, may not be supported by the browser. E.g. `"images/png,images/jpg"`, `"images/"`. `style` — The control's style `styleClass` — The control's style class Usage* <s:fileUpload id="picture" data="#{register.picture}" accept="image/png" contentType="#{register.pictureContentType}" />
`<s:formattedText>`	Description Outputs Seam Text , a rich text markup useful for blogs, wikis and other applications that might use rich text. See the Seam Text chapter for full usage. Attributes `value` — an EL expression specifying the rich text markup to render. Usage <s:formattedText value="#{blog.text}"/> Example
`<s:fragment>`	Description A non-rendering component useful for enabling/disabling rendering of it's children. Attributes None. Usage <s:fragment rendered="#{auction.highBidder ne null}"> Current bid: </s:fragment>
`<s:graphicImage>`	Description An extended `<h:graphicImage>` that allows the image to be created in a Seam Component; further transforms can be applied to the image. All attributes for `<h:graphicImage>` are supported, as well as: Attributes `value` — image to display. Can be a path `String` (loaded from the classpath), a `byte[]`, a `java.io.File`, a `java.io.InputStream` or a `java.net.URL`. Currently supported image formats are `image/png`, `image/jpeg` and `image/gif`. `fileName` — 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 Transformations To apply a transform to the image, you would nest a tag specifying the transform to apply. Seam currently supports these transforms: `<s:transformImageSize>` `width` — new width of the image `height` — new height of the image `maintainRatio` — if `true`, and one of `width`/`height` are specified, the image will be resized with the dimension not specified being calculated to maintain the aspect ratio. `factor` — scale the image by the given factor `<s:transformImageBlur>` `radius` — perform a convolution blur with the given radius `<s:transformImageType>` `contentType` — alter the type of the image to either `image/jpeg` or `image/png` It's easy to create your own transform - create a `UIComponent` which `implements` `org.jboss.seam.ui.graphicImage.ImageTransform`. Inside the `applyTransform()`method use `image.getBufferedImage()` to get the original image and `image.setBufferedImage()` to set your transformed image. Transforms are applied in the order specified in the view. Usage <s:graphicImage rendered="#{auction.image ne null}" value="#{auction.image.data}"> <s:transformImageSize width="200" maintainRatio="true"/> </s:graphicImage>
`<s:label>`	Description "Decorate" a JSF input field with the label. The label is placed inside the HTML `<label>` tag, and is associated with the nearest JSF input component. It is often used with `<s:decorate>`. Attributes `style` — The control's style `styleClass` — The control's style class Usage <s:label styleClass="label"> Country: </s:label> <h:inputText value="#{location.country}" required="true"/>
`<s:link>`	Description A link that supports invocation of an action with control over conversation propagation. Does not submit the form. Attributes `value` — the label. `action` — a method binding that specified the action listener. `view` — the JSF view id to link to. `fragment` — the fragment identifier to link to. `disabled` — is the link disabled? `propagation` — determines the conversation propagation style: `begin`, `join`, `nest`, `none` or `end`. `pageflow` — a pageflow definition to begin. (This is only useful when `propagation="begin"` or `propagation="join"`.) Usage <s:link id="register" view="/register.xhtml" value="Register New User"/> You can specify both `view` and `action` on `<s:link />`. In this case, the action will be called once the redirect to the specified view has occured.
`<s:message>`	Description "Decorate" a JSF input field with the validation error message. Attributes None. Usage <f:facet name="afterInvalidField"> <s:span>  Error:  <s:message/> </s:span> </f:facet>
`<s:remote>`	Description Generates the Javascript stubs required to use Seam Remoting. Attributes `include` — a comma-separated list of the component names (or fully qualified class names) for which to generate Seam Remoting Javascript stubs. See Chapter 21, Remoting for more details. Usage <s:remote include="customerAction,accountAction,com.acme.MyBean"/>
`<s:selectDate>`	Description Deprecated. Use `<rich:calendar />` instead. Displays a dynamic date picker component that selects a date for the specified input field. The body of the `selectDate` 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 must be styled using CSS. An example CSS file can be found in the Seam booking demo as `date.css`, or can be generated using seam-gen. The CSS styles used to control the appearance of the date picker are also described below. Attributes `for` — The id of the input field that the date picker will insert the selected date into. `dateFormat` — The date format string. This should match the date format of the input field. `startYear` — The popup year selector range will start at this year. `endYear` — The popup year selector range will end at this year. `firstDayOfWeek` — 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. Usage <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> Example* CSS Styling The following list describes the CSS class names that are used to control the style of the selectDate control. `seam-date` — This class is applied to the outer `div` containing the popup calendar. (1) It is also applied to the `table` that controls the inner layout of the calendar. (2) `seam-date-header` — This class is applied to the calendar header table row (`tr`) and header table cells (`td`). (3) `seam-date-header-prevMonth` — This class is applied to the "previous month" table cell, (`td`), which when clicked causes the calendar to display the month prior to the one currently displayed. (4) `seam-date-header-nextMonth` — This class is applied to the "next month" table cell, (`td`), which when clicked causes the calendar to display the month following the one currently displayed. (5) `seam-date-headerDays` — This class is applied to the calendar days header row (`tr`), which contains the names of the week days. (6) `seam-date-footer` — This class is applied to the calendar footer row (`tr`), which displays the current date. (7) `seam-date-inMonth` — This class is applied to the table cell (`td`) elements that contain a date within the month currently displayed. (8) `seam-date-outMonth` — This class is applied to the table cell (`td`) elements that contain a date outside of the month currently displayed. (9) `seam-date-selected` — This class is applied to the table cell (`td`) element that contains the currently selected date. (10) `seam-date-dayOff-inMonth` — This class is applied to the table cell (`td`) elements that contain a "day off" date (i.e. weekend days, Saturday and Sunday) within the currently selected month. (11) `seam-date-dayOff-outMonth` — This class is applied to the table cell (`td`) elements that contain a "day off" date (i.e. weekend days, Saturday and Sunday) outside of the currently selected month. (12) `seam-date-hover` — This class is applied to the table cell (`td`) element over which the cursor is hovering. (13) `seam-date-monthNames` — This class is applied to the `div` control that contains the popup month selector. (14) `seam-date-monthNameLink` — This class is applied to the anchor (`a`) controls that contain the popup month names. (15) `seam-date-years` — This class is applied to the `div` control that contains the popup year selector. (16) `seam-date-yearLink` — This class is applied to the anchor (`a`) controls that contain the popup years. (15)
`<s:selectItems>`	Description Creates a `List<SelectItem>` from a List, Set, DataModel or Array. Attributes `value` — an EL expression specifying the data that backs the `List<SelectItem>` `var` — defines the name of the local variable that holds the current object during iteration `label` — the label to be used when rendering the `SelectItem`. Can reference the `var` variable `itemValue` — Value to return to the server if this option is selected. Optional, by default the `var` object is used. Can reference the `var` variable `disabled` — if true the `SelectItem` will be rendered disabled. Can reference the `var` variable `noSelectionLabel` — specifies the (optional) label to place at the top of list (if `required="true"` is also specified then selecting this value will cause a validation error) `hideNoSelectionLabel` — if true, the `noSelectionLabel` will be hidden when a value is selected Usage <h:selectOneMenu value="#{person.age}" converter="ageConverter"> <s:selectItems value="#{ages}" var="age" label="#{age}" /> </h:selectOneMenu>
`<s:span>`	Description Render a HTML `<span>`. Attributes None. Usage <s:span styleClass="required" rendered="#{required}">*</s:span>
`<s:taskId>`	Description Add the task id to an output link (or similar JSF control), when the task is available via `#{task}`. Attributes None.
`<s:validate>`	Description A non-visual control, validates a JSF input field against the bound property using Hibernate Validator. Attributes None. Usage <h:inputText id="userName" required="true" value="#{customer.userName}"> <s:validate /> </h:inputText> <h:message for="userName" styleClass="error" />
`<s:validateAll>`	Description A non-visual control, validates all child JSF input fields against their bound properties using Hibernate Validator. Attributes None. Usage <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>
`<s:validateFormattedText>`	Description Checks that the submitted value is valid Seam Text Attributes None.

Chapter 28. Seam JSF controls

28.1. Tags

28.2. Annotations