Section B.2. JSF HTML Tags

B.2. JSF HTML Tags

The JSF HTML tags provide access to components that relate specifically to the HTML rendering model, including all of the standard HTML input components.

Several tag attributes are shared by all of the HTML tags or all of the tags in a particular category, such as the data input tags.

Table B-19. Shared tag attributes

Attribute	Description	Supported by
binding	A JSF EL expression identifying a backing bean property to bind this component to.	All tags (but not relevant for some)
converter	The name of a data converter instance associated with this component.	Input and output tags
id	A custom identifier for this component, allowing access to the underlying HTML element via JavaScript.	All tags
rendered	Boolean expression indicating whether this component and its children should be rendered.	All tags
required	A Boolean expression indicating whether data must be entered into the component in order to perform an action on the surrounding form.	Input tags
styleClass	Specifies the name of the CSS style to be applied to the generated element. Multiple styles can be specified via a comma-separated list.	All but <h:column> and <h:inputHidden>
validator	The name of a validator associated with this component.	Input tags
value	A JSF EL expression indicating the current value of this component. Used for values that are not manipulated by the user. For user-entered data, the binding attribute should be used instead.	Input, output, and control tags
valueChangeListener	JSF EL expression identifying an event-handling method for use when the value of an input component changes. All value change listeners in a view will be processed when the view is submitted.	Input tags

B.2.1. Pass-Through Attributes

Since the JSF HTML tags are responsible for rendering HTML for consumption by the browser, they include pass-through attributes for standard HTML attributes and for DHTML event attributes, which are used to integrate JavaScript with your application. To minimize repetition, we'll summarize the pass-through attributes here rather than include them with each individual tag.

All standard HTML 4.0 elements are supported by the corresponding JSF UI tags. The most common attributes are listed in Table B-20. Specific interpretation of some of these values depends on the element itself.

Table B-20. Common HTML 4.0 pass-through elements

Attribute	Description
accesskey	Identifies a hotkey that will give focus to an element (usually used in accessible browsers in combination with an external command).
accept	The content type or types generated by the form.
alt	Alternative text to display for this component in nongraphical browsers.
border	Width of the element's border, in pixels.
charset	Character set in use.
cols	Number of columns in a text area.
coords	Coordinates for image map elements.
dir	Text direction.
disabled	Indicates whether or not a form input element is disabled.
maxlength	The maximum length of the input allowed in a field.
readonly	Indicates that an input component is read-only.
rows	Number of rows in a TEXTAREA.
shape	The shape of an image map region. Acceptable values are default, circle, poly, and rect.
size	The size of an input field, for display purposes.
style	Inline CSS stylesheet information for the current element.
tabindex	The tab index for this element. Used by the browser to determine the order in which fields receive focus when the user presses the Tab key.
target	The name of the target frame for a link or a form submission.
title	A description of the element's content, generally used to create more easily accessible applications.
width	The width of this element.

The DHTML pass-through attributes are listed in Table B-21. Like the HTML 4.0 attributes, DHTML attributes are only supported for HTML components that originally supported the attribute.

Table B-21. DHTML pass-through attributes

Attribute	Description
onblur	Script invoked when an element loses focus
onchange	Script invoked when an element's value changes
onclick	Script invoked when an element is clicked on
ondblclick	Script invoked when an element is double-clicked on
onfocus	Script invoked when an element gains focus
onkeydown	Script invoked when a key is pressed while the element has focus
onkeypress	Script invoked when a key is pressed and released while the element has focus
onkeyup	Script invoked when a key is released
onmousedown	Script invoked when the mouse is clicked while the pointer is positioned over the element
onmousemove	Script invoked when the mouse moves over the element
onmouseout	Script invoked when the mouse moves out of the element
onmouseover	Script invoked when the mouse moves over the element
onreset	Script invoked when the form is reset
onselect	Script involved when text within the element is selected
onsubmit	Script invoked when the form is submitted

B.2.2. <h:column>

Represents a column of data within a multicolumn user interface component. See <h:dataTable> for more information.

B.2.3. <h:commandButton>

Renders an HTML form submission button element and wires the button to an outcome.

Table B-22. Attributes for <h:commandButton>

Attribute	Description
action	JSF EL expression specifying the navigation outcome from clicking this button. The outcome may be hardcoded or produced by a backing bean method that returns a string.
actionListener	Method binding for an action listener for this button. Must map to a valid listener method.
image	Absolute or relative URL pointing to an image file. If specified, the type attribute will be ignored and the button will be generated as type image.
immediate	Indicates that the results of pressing this button should be applied to the application immediately (during the first phase of JSF request processing, before validation) rather than during the Invoke Application phase.
type	The type of button. Valid values are submit and reset.
value	The text displayed on the button.

B.2.4. <h:commandLink>

Renders an HTML link, which, when clicked, will submit the current view for processing by the JSF engine.

Table B-23. Attributes for <h:commandLink>

Attribute	Description
action	JSF EL expression specifying the navigation outcome from clicking the link. The outcome may be hardcoded or produced by a backing bean method that returns a string.
actionListener	Method binding for an action listener for this button. Must map to a valid listener method.
charset	The character encoding of the resource at the other end of the link.
immediate	Indicates that the results of clicking the link should be applied to the application immediately (during the first phase of JSF request processing, before validation) rather than during the Invoke Application phase.
type	The content type associate with the link (HTML pass-through).
value	The link text.

B.2.5. <h:dataTable>

Renders an HTML table, iterating through a set of JavaBeans and processing the body content for each bean. This tag also supports two facets, header and footer, for creating table headers and footers.

Table B-24. Attributes for <h:dataTable >

Attribute	Description
first	Index of the first row of data to display. Defaults to 0, which is the first row.
rows	Number of rows to display. If omitted or set to 0, all rows will be displayed.
value	Valid values for this attribute are an array, a collection, a javax.faces.model.DataModel, a java.sql.ResultSet, a javax.servlet.jsp.jstl.sql.ResultSet, or a javax.sql.RowSet.
var	The name of a request-scoped variable to which each object in the underlying data model will be assigned.
columnClasses	A comma-separated list of CSS classes to be applied, in order, to the columns in the table. Multiple classes may be applied to a single column by separating them by spaces within the comma-separated list. If there are more columns than CSS classes, the extra columns will not have stylesheet information.
footerClass	CSS class to apply to footer elements.
headerClass	CSS class to apply to header elements.
rowClasses	Comma-separated list of CSS classes to be applied in sequence to the rows within the table. If there are more rows than CSS classes, the sequence will repeat until the table is complete.
width	Width of the table.

B.2.6. <h:form>

Root element for an HTML form. Accepts attributes for all standard HTML form tag elements.

Table B-25. Attributes for <h:form>

Attribute	Description
enctype	The content type used to submit the form. The default is application/x-www-form-urlencoded.

B.2.7. <h:graphicImage>

Renders an HTML <img> tag.

Table B-26. Additional attributes for <h:graphicImage>

Attribute	Description
ismap	Indicates that this image is associated with a server-side image map
usemap	The name of a client-side image map definition associated with this image
value	The path to the image

B.2.8. <h:inputHidden>

Renders a hidden form field. Used primarily when using JSF to generate forms that will be submitted to non-JSF destinations.

Table B-27. Attributes for <h:inputHidden>

Attribute	Description
value	The value for the field, if no binding is used

B.2.9. <h:inputSecret>

Renders an HTML password field. Supports pass-through attributes for the <input> HTML tag.

B.2.10. <h:inputText>

Renders an HTML text input field. Supports pass-through attributes for the <input> HTML tag.

B.2.11. <h:inputTextarea>

Renders an HTML text area input field. The content of the text area is specified by the value or binding attributes, not, as in the HTML <textarea> tag, by the tag contents.

Table B-28. Attributes for <h:inputTextarea>

Attribute	Description
cols	The number of columns in this text area
rows	The number of rows in this text area
title	Title of this text area, used for accessible browsing
value	JSF EL expression evaluating to the value of the text area, if no binding is used

B.2.12. <h:message>

Displays messages, such as validation errors, associated with a particular component. Specifically, the tag will display a single message associated with a particular component.

The various style and class attributes of this tag allow you to specify a CSS class for particular message types or to directly define the style to be used.

Table B-29. Attributes for <h:message>

Attribute	Description
for	Specifies the ID of the component to display a message for. Required.
showDetail	Indicates whether the message detail will be displayed. Default is true.
showSummary	Indicates whether the message summary will be displayed. Default is false.
errorClass	CSS style class for messages with severity level ERROR.
errorStyle	CSS style for messages with severity level ERROR.
fatalClass	CSS style class for messages with severity level FATAL.
fatalStyle	CSS style for messages with severity level FATAL.
infoClass	CSS style class for messages with severity level INFO.
infoStyle	CSS style for messages with severity level INFO.
warnClass	CSS style class for messages with severity level WARN.
warnStyle	CSS style for messages with severity level WARN.

B.2.13. <h:messages>

Displays an HTML table or list containing all of the messages for the current view. The standard style and styleClass attributes should be used to provide formatting.

The defaults for the showDetail and showSummary attributes are the reverse of the defaults for the <h:message> tag.

Table B-30. Attributes for <h:messages>

Attribute	Description
globalOnly	Indicates that only global messages (not associated with a particular component) are to be displayed. Default is false.
layout	Format to use when displaying the list of messages. Options are "list" (the default) and "table".
showDetail	Indicates whether the message detail will be displayed. Default is false.
showSummary	Indicates whether the message summary will be displayed. Default is TRue.
errorClass	CSS style class for messages with severity level ERROR.
errorStyle	CSS style for messages with severity level ERROR.
fatalClass	CSS style class for messages with severity level FATAL.
fatalStyle	CSS style for messages with severity level FATAL.
infoClass	CSS style class for messages with severity level INFO.
infoStyle	CSS style for messages with severity level INFO.
warnClass	CSS style class for messages with severity level WARN.
warnStyle	CSS style for messages with severity level WARN.

B.2.14. <h:outputFormat>

Outputs formatted text output, following the rules for the java.text.MessageFormat class. To pass parameters to the message formatter, embed one or more <f:param> tags in the body of the <h:outputFormat> tag.

Table B-31. Attributes for <h:outputFormat>

Attribute	Description
value	The string to format

B.2.15. <h:outputLabel>

Generates an HTML <label> tag for a component.

Table B-32. Attributes for <h:outputLabel>

Attribute	Description
for	The ID of the component that this label references

B.2.16. <h:outputLink>

Generates an HTML link tag (<a>) around a specified piece of content. To display a link, the <h:outputLink> tag must surround another JSF tag, such as <h:outputText> , <h:graphicImage>, or <f:verbatim>, that provides the link text or image.

Table B-33. Additional attributes for <h:outputLink>

Attribute	Description
title	An optional title for this link
value	The destination of this link

B.2.17. <h:outputText>

Outputs a bound value or a specified value.

B.2.18. <h:panelGrid>

Generates an HTML table. Each JSF user interface component within the body of the tag will be used as a cell value. To combine multiple JSF elements into a single cell, enclose them in an <h:panelGroup> component.

This tag supports a header and footer facet (see <f:facet>) for rendering table headers and footers.

Table B-34. Attributes for <h:panelGrid>

Attribute	Description
bgcolor	Background color for this table, as a color constant or RGB value.
border	Width of the border around this table, in pixels. The default is 0.
cellpadding	Specifies the amount of space between the border of a cell and its contents.
cellspacing	Specifies the spacing between cells within the table and between cells and the edge of the table.
columnClasses	A comma-separated list of CSS classes to be applied, in order, to the columns in the table. Multiple classes may be applied to a single column by separating them by spaces within the comma-separated list. If there are more columns than CSS classes, the extra columns will not have stylesheet information.
columns	Specifies the number of columns in this table. The number of rows is determined automatically.
footerClass	CSS class to apply to any footer generated for this table.
frame	Indicates which sides of the table will be visible. Values are none (default), above, below, hsides (top and bottom), vsides (right and left), lhs (left side), rhs (right side), box (all four sides, with a line), and border (all four sides, width specified by the border attribute).
headerClass	CSS class to apply to any header generated for this table.
rowClasses	Comma-separated list of CSS classes to be applied in sequence to the rows within the table. If there are more rows than CSS classes, the sequence will repeat until the table is complete.
rules	Indicates which rules will be rendered between cells in the table. Values are none (the default), groups (between groups of rows only), rows (between individual rows), cols (between columns), and all (between all rows and columns).
summary	Summary of the contents of this table.

B.2.19. <h:panelGroup>

Groups several JSF components (contained in the tag body) into a single unit. Panel groups are used to control component rendering en masse and to group components for use within the <h:panelGrid> tag.

B.2.20. <h:selectBooleanCheckbox>

Renders an HTML checkbox, bound to a Boolean property on a backing bean or from a Boolean value attribute.

B.2.21. <h:selectManyCheckbox>

Renders a set of checkboxes. The binding for the component must be an array or a collection capable of holding the selected values. The content of the set of checkboxes must be provided via an <f:selectItems> tag or a set of one or more <f:selectItem> tags embedded within the body of the <h:selectManyCheckbox> tag.

Table B-35. Attributes for <h:selectManyCheckbox>

Attribute	Description
layout	Specifies the order in which the checkboxes should be laid out. Options are lineDirection (the default) and pageDirection (a vertical arrangement).

B.2.22. <h:selectManyListbox>

Renders a listbox using the HTML <select> tag. The binding for the component must be an array or a collection capable of holding the selected values. The contents of the listbox must be provided via an <f:selectItems> tag or a set of one or more <f:selectItem> tags embedded within the body of the <h:selectManyListbox> tag.

Table B-36. Attributes for <h:selectManyListbox>

Attribute	Description
size	Indicates the number of items to display on screen at once

B.2.23. <h:selectManyMenu>

Generates a multiselection menu. For HTML rendering, this is equivalent to a <select> tag with the multiple attribute set to true and the size attribute set to 1. We're not saying that this is an entirely useless tag for HTML user interfaces, but let's just say we haven't found a use for it either.

Like <h:selectManyListbox>, the menu contents must be provided via an <f:selectItems> tag or a set of <f:selectItem> tags.

B.2.24. <h:selectOneListbox>

Renders a listbox using the HTML <select> tag. The binding for the component must be an array or a collection capable of holding the selected values. The contents of the listbox must be provided via an <f:selectItems> tag or a set of one or more <f:selectItem> tags embedded within the body of the <h:selectManyListbox> tag.

The listbox rendered by the tag allows only a single item to be selected at a time.

Table B-37. Attribute for <h:selectOneListbox>

Attribute	Description
size	Indicates the number of items to display on screen at once

B.2.25. <h:selectOneMenu>

For HTML, this tag is about as useful as the <h:selectManyMenu> tag, which isn't particularly useful. Renders a menu item, allowing a single selection. Slightly more useful for WML or other non-HTML output formats that support a native menu component.

B.2.26. <h:selectOneRadio>

Generates a set of radio buttons using a set of selection items.

Table B-38. Additional attributes for <h:selectOneRadio>

Attribute	Description
layout	Specifies the order in which the radio buttons should be laid out. Options are lineDirection (the default) and pageDirection (a vertical arrangement).