An Overview of the JSF HTML Tags JSF HTML tags represent the following kinds of components: -
Inputs -
Outputs -
Commands -
Selection -
Others The "others" category includes forms, messages, and components that lay out other components. Table 4-3 lists all the HTML tags. Table 4-3. JSF HTML Tags Tag | Description | form | HTML form | inputText | Single-line text input control | inputTextarea | Multiline text input control | inputSecret | Password input control | inputHidden | Hidden field | outputLabel | Label for another component for accessibility | outputLink | HTML anchor | outputFormat | Like outputText, but formats compound messages | outputText | Single-line text output | commandButton | Button: submit, reset, or pushbutton | commandLink | Link that acts like a pushbutton | message | Displays the most recent message for a component | messages | Displays all messages | graphicImage | Displays an image | selectOneListbox | Single-select listbox | selectOneMenu | Single-select menu | selectOneRadio | Set of radio buttons | selectBooleanCheckbox | Checkbox | selectManyCheckbox | Set of checkboxes | selectManyListbox | Multiselect listbox | selectManyMenu | Multiselect menu | panelGrid | HTML table | panelGroup | Two or more components that are laid out as one | dataTable | A feature-rich table control | column | Column in a dataTable | We can group the HTML tags in the following categories: -
Inputs (input...) -
Outputs (output...) -
Commands (commandButton and commandLink) -
Selections (checkbox, listbox, menu, radio) -
Layouts (panelGrid) -
Data table (dataTable); see Chapter 5 -
Errors and messages (message, messages) The JSF HTML tags share common attributes, HTML pass-through attributes, and attributes that support dynamic HTML. Note | The HTML tags may seem overly verbose for example, selectManyListbox could be more efficiently expressed as multiList. But those verbose names correspond to a component/renderer combination, so selectManyListbox represents a selectMany component paired with a listbox renderer. Knowing the type of component a tag represents is crucial if you want to access components programmatically. | Note | Both JSF and Struts developers implement web pages with JSP custom tags. But Struts tags generate HTML directly, whereas JSF tags represent a component that is independent of the markup technology, and a renderer that generates HTML. That key difference makes it easy to adapt JSF applications to alternative display technologies. For an example, see the chapter on wireless JSF applications that is available on the book's companion web site (http://corejsf.com). | Common Attributes Three types of tag attributes are shared among multiple HTML component tags: -
Basic -
HTML 4.0 -
DHTML events Next, we look at each type. Basic Attributes As you can see from Table 4-4, basic attributes are shared by the majority of JSF HTML tags. Table 4-4. Basic HTML Tag Attributes Attribute | Component Types | Description | id | A (25) | Identifier for a component | binding | A (25) | Links this component with a backing bean property | rendered | A (25) | A Boolean; false suppresses rendering | styleClass | A (23) | CSS (Cascading Style Sheet) class name | value | I, O, C (19) | A component's value, typically a value expression | valueChangeListener | I (11) | A method expression to a method that responds to value changes | converter | I, O (15) | Converter class name | validator | I (11) | Class name of a validator that is created and attached to a component | required | I (11) | A Boolean; if true, requires a value to be entered in the associated field | converterMessage, validatorMessage, requiredMessage(JSF 1.2) | I (11) | A custom message to be displayed when a conversion or validation error occurs, or when required input is missing | The id and binding attributes, applicable to all HTML tags, reference a component the former is used primarily by page authors and the latter is used by Java developers. The value and converter attributes let you specify a component value and a means to convert it from a string to an object, or vice versa. The validator, required, and valueChangeListener attributes are available for input components so that you can validate values and react to changes to those values. See Chapter 6 for more information about validators and converters. The ubiquitous rendered and styleClass attributes affect how a component is rendered. Now we take a brief look at these important attributes. IDs and Bindings The versatile id attribute lets you do the following: -
Access JSF components from other JSF tags -
Obtain component references in Java code -
Access HTML elements with scripts In this section, we discuss the first two tasks listed above. See "Form Elements and JavaScript" on page 105 for more about the last task. The id attribute lets page authors reference a component from another tag. For example, an error message for a component can be displayed like this: <h:inputText .../> <h:message for="name"/> You can also use component identifiers to get a component reference in your Java code. For example, you could access the name component in a listener like this: UIComponent component = event.getComponent().findComponent("name"); The preceding call to findComponent has a caveat: The component that generated the event and the name component must be in the same form (or data table). There is a better way to access a component in your Java code. Define the component as an instance field of a class. Provide property getters and setters for the component. Then use the binding attribute, which you specify in a JSF page, like this: <h:outputText binding="#{form.statePrompt}" .../> The binding attribute is specified with a value expression. That expression refers to a read-write bean property. See "Backing Beans" on page 53 of Chapter 2 for more information about the binding attribute. The JSF implementation sets the property to the component, so you can programatically manipulate components. You can also programmatically create a component that will be used in lieu of the component specified in the JSF page. For example, the form bean's statePrompt property could be implemented like this: private UIComponent statePrompt = new UIOutput(); public UIComponent getStatePrompt() { return statePrompt; } public void setStatePrompt(UIComponent statePrompt) {...} When the #{form.statePrompt} value expression is first encountered, the JSF framework calls Form.getStatePrompt(). If that method returns null as is typically the case the JSF implementation creates the component specified in the JSF page. But if that method returns a reference to a component as is the case in the preceding code fragment that component is used instead. Values, Converters, and Validators Inputs, outputs, commands, and data tables all have values. Associated tags in the HTML library, such as h:inputText and h:dataTable, come with a value attribute. You can specify values with a string, like this: <h:outputText value="William"/> Most of the time you will use a value expression for example: <h:outputText value="#{customer.name}"/> The converter attribute, shared by inputs and outputs, lets you attach a converter to a component. Input tags also have a validator attribute that you can use to attach a validator to a component. Converters and validators are discussed at length in Chapter 6. Styles You can use CSS styles, either inline (style) or classes (styleClass), to influence how components are rendered. Most of the time you will specify string constants instead of value expressions for the style and styleClass attributes for example: <h:outputText value="#{customer.name}" style/> <h:outputText value="#{customer.id}" style="border: thin solid blue"/> Value expressions are useful when you need programmatic control over styles. You can also control whether components are rendered at all with the rendered attribute. That attribute comes in handy in all sorts of situations for example, an optional table column. Tip | Instead of using a hardwired style, it is better to use a style sheet. Define a CSS style such as .prompts { color:red; } Place it in a style sheet, say, styles.css. Add a link element inside the head element in your JSF page: <link href="styles.css" rel="stylesheet" type="text/css"/> Then use the styleClass attribute: <h:outputText value="#{msgs.namePrompt}" style/> Now you can change the appearance of all prompts by updating the style sheet. | Conditional Rendering You use the rendered attribute to include or exclude a component, depending on a condition. For example, you may want to render a "Logout" button only if the user is currently logged in: <h:commandButton ... rendered = "#{user.loggedIn}"/> To conditionally include a group of components, include them in an h:panelGrid with a rendered attribute. See "Panels" on page 163 for more information. Tip | Remember, you can use operators in value expressions. For example, you might have a view that acts as a tabbed pane by optionally rendering a panel depending on the selected tab. In that case, you could use h:panelGrid like this: <h:panelGrid rendered='#{bean.selectedTab == "Movies"}'/> The preceding code renders the movies panel when the user selects the Movies tab. | Note | Sometimes, you will see the JSTL c:if construct used for conditional rendering. However, that is less efficient than the rendered attribute. | HTML 4.0 Attributes JSF HTML tags have appropriate HTML 4.0 pass-through attributes. Those attribute values are passed through to the generated HTML element. For example, <h:inputText value="#{form.name.last}" size="25".../> generates this HTML: <input type="text" size="25".../>. Notice that the size attribute is passed through to HTML. The HTML 4.0 attributes are listed in Table 4-5. Table 4-5. HTML 4.0 Pass-Through Attributes Attribute | Description | accesskey (14) | A key, typically combined with a system-defined metakey, that gives focus to an element. | accept (1) | Comma-separated list of content types for a form. | acceptcharset (1) | Comma- or space-separated list of character encodings for a form. The HTML accept-charset attribute is specified with the JSF attribute named acceptcharset. | alt (4) | Alternative text for nontextual elements such as images or applets. | border (4) | Pixel value for an element's border width. | charset (2) | Character encoding for a linked resource. | coords (2) | Coordinates for an element whose shape is a rectangle, circle, or polygon. | dir (22) | Direction for text. Valid values are "ltr" (left to right) and "rtl" (right to left). | disabled (13) | Disabled state of an input element or button. | hreflang (2) | Base language of a resource specified with the href attribute; hreflang may only be used with href. | lang (22) | Base language of an element's attributes and text. | maxlength (2) | Maximum number of characters for text fields. | readonly (11) | Read-only state of an input field; text can be selected in a read-only field but not edited. | rel (2) | Relationship between the current document and a link specified with the href attribute. | rev (2) | Reverse link from the anchor specified with href to the current document. The value of the attribute is a space-separated list of link types. | rows (1) | Number of visible rows in a text area. h:dataTable has a rows attribute, but it is not an HTML pass-through attribute. | shape (2) | Shape of a region. Valid values: default, rect, circle, poly (default signifies the entire region). | size (4) | Size of an input field. | style (23) | Inline style information. | tabindex (14) | Numerical value specifying a tab index. | target (3) | The name of a frame in which a document is opened. | title (22) | A title, used for accessibility, that describes an element. Visual browsers typically create tooltips for the title's value. | type (3) | Type of a link for example, "stylesheet". | width (3) | Width of an element. | The attributes listed in Table 4-5 are defined in the HTML specification, which you can access online at http://www.w3.org/TR/REC-html40. That web site is an excellent resource for deep digging into HTML. DHTML Events Client-side scripting is useful for all sorts of tasks, such as syntax validation or rollover images, and it is easy to use with JSF. HTML attributes that support scripting, such as onclick and onchange are called DHTML (dynamic HTML) event attributes. JSF supports DHTML event attributes for nearly all of the JSF HTML tags. Those attributes are listed in Table 4-6. Table 4-6. DHTML Event Attributes Attribute | Description | onblur (14) | Element loses focus | onchange (11) | Element's value changes | onclick (17) | Mouse button is clicked over the element | ondblclick (18) | Mouse button is double-clicked over the element | onfocus (14) | Element receives focus | onkeydown (18) | Key is pressed | onkeypress (18) | Key is pressed and subsequently released | onkeyup (18) | Key is released | onmousedown (18) | Mouse button is pressed over the element | onmousemove (18) | Mouse moves over the element | onmouseout (18) | Mouse leaves the element's area | onmouseover (18) | Mouse moves onto an element | onmouseup (18) | Mouse button is released | onreset (1) | Form is reset | onselect (11) | Text is selected in an input field | onsubmit (1) | Form is submitted | The DHTML event attributes listed in Table 4-6 let you associate client-side scripts with events. Typically, JavaScript is used as a scripting language, but you can use any scripting language you like. See the HTML specification for more details. Tip | You will probably add client-side scripts to your JSF pages soon after you start using JSF. One common use is to submit a request when an input's value is changed so that value change listeners are immediately notified of the change, like this: <h:selectOneMenu onchange="submit()"...> | |