Using Jakarta Faces Technology in Web Pages

Most of the component tags support the attributes shown in Common Component Tag Attributes.

All the tag attributes except id can accept expressions, as defined by the Expression Language, described in Expression Language.

An attribute such as rendered or value can be set on the page and then modified in the backing bean for the page.

The HTML head (h:head) and body (h:body) tags add HTML page structure to Jakarta Faces web pages.

The following is an example of an XHTML page using the usual head and body markup tags:

The following is an example of an XHTML page using h:head and h:body tags:

Both of the preceding example code segments render the same HTML elements. The head and body tags are useful mainly for resource relocation. For more information on resource relocation, see Resource Relocation Using h:outputScript and h:outputStylesheet Tags.

An h:form tag represents an input form, which includes child components that can contain data that is either presented to the user or submitted with the form.

Figure 1, “A Typical Form” shows a typical login form in which a user enters a user name and password, then submits the form by clicking the Login button.

The h:form tag represents the form on the page and encloses all the components that display or collect data from the user, as shown here:

The h:form tag can also include HTML markup to lay out the components on the page. Note that the h:form tag itself does not perform any layout; its purpose is to collect data and to declare attributes that can be used by other components in the form.

A page can include multiple h:form tags, but only the values from the form submitted by the user will be included in the postback request.

Text components allow users to view and edit text in web applications. The basic types of text components are as follows:

Figure 2, “Example Text Components” shows examples of these text components.

Text components can be categorized as either input or output. A Jakarta Faces output component, such as a label, is rendered as read-only text. A Jakarta Faces input component, such as a field, is rendered as editable text.

The input and output components can each be rendered in various ways to display more specialized text.

Input Tags lists the tags that represent the input components.

The input tags support the tag attributes shown in Input Tag Attributes in addition to those described in Common Component Tag Attributes. Note that this table does not include all the attributes supported by the input tags but just those that are used most often. For the complete list of attributes, refer to the Jakarta Faces Facelets Tag Library documentation.

Output Tags lists the tags that represent the output components.

The output tags support the converter tag attribute in addition to those listed in Common Component Tag Attributes.

The rest of this section explains how to use some of the tags listed in Output Tags. The other tags are written in a similar way.

In Jakarta Faces applications, the button and link component tags are used to perform actions, such as submitting a form, and for navigating to another page. These tags are called command component tags because they perform an action when activated.

The h:commandButton tag is rendered as a button. The h:commandLink tag is rendered as a link.

In addition to the tag attributes listed in Common Component Tag Attributes, the h:commandButton and h:commandLink tags can use the following attributes.

See Referencing a Method That Performs Navigation for more information on using the action attribute. See Referencing a Method That Handles an Action Event for details on using the actionListener attribute.

In a Jakarta Faces application, use the h:graphicImage tag to render an image on a page:

In this example, the url attribute specifies the path to the image. The URL of the example tag begins with a slash (/), which adds the relative context path of the web application to the beginning of the path to the image.

Alternatively, you can use the facility described in Web Resources to point to the image location. Here are two examples:

You can use similar syntax to refer to an image in a style sheet. The following syntax in a style sheet specifies that the image is to be found at resources/img/top-background.jpg:

In a Jakarta Faces application, you use a panel as a layout container for a set of other components. A panel is rendered as an HTML table. Panel Component Tags lists the tags used to create panels.

The h:panelGrid tag is used to represent an entire table. The h:panelGroup tag is used to represent rows in a table. Other tags are used to represent individual cells in the rows.

The columns attribute defines how to group the data in the table and therefore is required if you want your table to have more than one column. The h:panelGrid tag also has a set of optional attributes that specify CSS classes: columnClasses, footerClass, headerClass, panelClass, and rowClasses. The role attribute can have the value "presentation" to indicate that the purpose of the table is to format the display rather than to show data.

If the headerClass attribute value is specified, the h:panelGrid tag must have a header as its first child. Similarly, if a footerClass attribute value is specified, the h:panelGrid tag must have a footer as its last child.

Here is an example:

The preceding h:panelGrid tag is rendered as a table that contains components in which a customer inputs personal information. This h:panelGrid tag uses style sheet classes to format the table. The following code shows the list-header definition:

Because the h:panelGrid tag specifies a headerClass, the h:panelGrid tag must contain a header. The example h:panelGrid tag uses an f:facet tag for the header. Facets can have only one child, so an h:panelGroup tag is needed if you want to group more than one component within an f:facet. The example h:panelGrid tag has only one cell of data, so an h:panelGroup tag is not needed. (For more information about facets, see Using Data-Bound Table Components.

The h:panelGroup tag has an attribute, layout, in addition to those listed in Common Component Tag Attributes. If the layout attribute has the value block, an HTML div element is rendered to enclose the row; otherwise, an HTML span element is rendered to enclose the row. If you are specifying styles for the h:panelGroup tag, you should set the layout attribute to block in order for the styles to be applied to the components within the h:panelGroup tag. You should do this because styles, such as those that set width and height, are not applied to inline elements, which is how content enclosed by the span element is defined.

An h:panelGroup tag can also be used to encapsulate a nested tree of components so that the tree of components appears as a single component to the parent component.

Data, represented by the nested tags, is grouped into rows according to the value of the columns attribute of the h:panelGrid tag. The columns attribute in the example is set to 2, and therefore the table will have two columns. The column in which each component is displayed is determined by the order in which the component is listed on the page modulo 2. So, if a component is the fifth one in the list of components, that component will be in the 5 modulo 2 column, or column 1.

Another commonly used component is one that allows a user to select one value, whether it is the only value available or one of a set of choices. The most common tags for this kind of component are as follows:

Figure 3, “Example Components for Selecting One Item” shows examples of these components.

In some cases, you need to allow your users to select multiple values rather than just one value from a list of choices. You can do this using one of the following component tags:

Figure 4, “Example Components for Selecting Multiple Values” shows examples of these components.

These tags allow the user to select zero or more values from a set of values. This section explains the h:selectManyCheckbox tag. The h:selectManyListbox and h:selectManyMenu tags are used in a similar way.

Unlike a menu, a list displays a subset of items in a box; a menu displays only one item at a time when the user is not selecting the menu. The size attribute of the h:selectManyListbox tag determines the number of items displayed at one time. The box includes a scroll bar for scrolling through any remaining items in the list.

The h:selectManyCheckbox tag renders a group of check boxes, with each check box representing one value that can be selected:

The value attribute of the h:selectManyCheckbox tag identifies the newsletters property of the CashierBean managed bean. This property holds the values of the currently selected items from the set of check boxes. You are not required to provide a value for the currently selected items. If you don’t provide a value, the first item in the list is selected by default. In the CashierBean managed bean, this value is instantiated to 0, so no items are selected by default.

The layout attribute indicates how the set of check boxes is arranged on the page. Because layout is set to pageDirection, the check boxes are arranged vertically. The default is lineDirection, which aligns the check boxes horizontally.

The h:selectManyCheckbox tag must also contain a tag or set of tags representing the set of check boxes. To represent a set of items, you use the f:selectItems tag. To represent each item individually, you use the f:selectItem tag. The following section explains these tags in more detail.

The f:selectItem and f:selectItems tags represent components that can be nested inside a component that allows you to select one or multiple items. An f:selectItem tag contains the value, label, and description of a single item. An f:selectItems tag contains the values, labels, and descriptions of the entire list of items.

You can use either a set of f:selectItem tags or a single f:selectItems tag within your component tag.

The advantages of using the f:selectItems tag are as follows.

The advantages of using f:selectItem are as follows.

The rest of this section shows you how to use the f:selectItems and f:selectItem tags.

If you display components that allow a user to select values, you may also want to display the result of the selection.

For example, you might want to thank a user who selected the checkbox to join the Duke Fan Club, as described in Displaying a Check Box Using the h:selectBooleanCheckbox Tag. Because the checkbox is bound to the specialOffer property of CashierBean, a UISelectBoolean value, you can call the isSelected method of the property to determine whether to render a thank-you message:

Similarly, you might want to acknowledge that a user subscribed to newsletters using the h:selectManyCheckbox tag, as described in Displaying Components for Selecting Multiple Values. To do so, you can retrieve the value of the newsletters property, the String array that holds the selected items:

An introductory thank-you message is displayed only if the newsletters array is not empty. Then a ui:repeat tag, a simple way to show values in a loop, displays the contents of the selected items in an itemized list. (This tag is listed in Facelets Templating Tags.)

Data-bound table components display relational data in a tabular format. In a Jakarta Faces application, the h:dataTable component tag supports binding to a collection of data objects and displays the data as an HTML table. The h:column tag represents a column of data within the table, iterating over each record in the data source, which is displayed as a row. Here is an example:

The example h:dataTable tag displays the books in the shopping cart as well as the quantity of each book in the shopping cart, the prices, and a set of buttons the user can click to remove books from the shopping cart.

The h:column tags represent columns of data in a data component. While the data component is iterating over the rows of data, it processes the column component associated with each h:column tag for each row in the table.

The h:dataTable tag shown in the preceding code example iterates through the list of books (cart.items) in the shopping cart and displays their titles, authors, and prices. Each time the h:dataTable tag iterates through the list of books, it renders one cell in each column.

The h:dataTable and h:column tags use facets to represent parts of the table that are not repeated or updated. These parts include headers, footers, and captions.

In the preceding example, h:column tags include f:facet tags for representing column headers or footers. The h:column tag allows you to control the styles of these headers and footers by supporting the headerClass and footerClass attributes. These attributes accept space-separated lists of CSS classes, which will be applied to the header and footer cells of the corresponding column in the rendered table.

Facets can have only one child, so an h:panelGroup tag is needed if you want to group more than one component within an f:facet. Because the facet tag representing the footer includes more than one tag, the h:panelGroup tag is needed to group those tags. Finally, this h:dataTable tag includes an f:facet tag with its name attribute set to caption, causing a table caption to be rendered above the table.

This table is a classic use case for a data component because the number of books might not be known to the application developer or the page author when that application is developed. The data component can dynamically adjust the number of rows of the table to accommodate the underlying data.

The value attribute of an h:dataTable tag references the data to be included in the table. This data can take the form of any of the following:

All data sources for data components have a DataModel wrapper. Unless you explicitly construct a DataModel wrapper, the Jakarta Faces implementation will create one around data of any of the other acceptable types. See Writing Bean Properties for more information on how to write properties for use with a data component.

The var attribute specifies a name that is used by the components within the h:dataTable tag as an alias to the data referenced in the value attribute of h:dataTable.

In the example h:dataTable tag, the value attribute points to a list of books. The var attribute points to a single book in that list. As the h:dataTable tag iterates through the list, each reference to item points to the current book in the list.

The h:dataTable tag also has the ability to display only a subset of the underlying data. This feature is not shown in the preceding example. To display a subset of the data, you use the optional first and rows attributes.

The first attribute specifies the first row to be displayed. The rows attribute specifies the number of rows, starting with the first row, to be displayed. For example, if you wanted to display records 2 through 10 of the underlying data, you would set first to 2 and rows to 9. When you display a subset of the data in your pages, you might want to consider including a link or button that causes subsequent rows to display when clicked. By default, both first and rows are set to zero, and this causes all the rows of the underlying data to display.

Optional Attributes for the h:dataTable Tag shows the optional attributes for the h:dataTable tag.

Each of the attributes in Optional Attributes for the h:dataTable Tag can specify more than one style. If columnClasses or rowClasses specifies more than one style, the styles are applied to the columns or rows in the order that the styles are listed in the attribute. For example, if columnClasses specifies styles list-column-center and list-column-right, and if the table has two columns, the first column will have style list-column-center, and the second column will have style list-column-right.

If the style attribute specifies more styles than there are columns or rows, the remaining styles will be assigned to columns or rows starting from the first column or row. Similarly, if the style attribute specifies fewer styles than there are columns or rows, the remaining columns or rows will be assigned styles starting from the first style.

The h:message and h:messages tags are used to display error messages when conversion or validation fails. The h:message tag displays error messages related to a specific input component, whereas the h:messages tag displays the error messages for the entire page.

Here is an example h:message tag from the guessnumber-faces application:

The for attribute refers to the ID of the component that generated the error message. The error message is displayed at the same location that the h:message tag appears in the page. In this case, the error message will appear below the Submit button.

The style attribute allows you to specify the style of the text of the message. In the example in this section, the text will be a shade of red, New Century Schoolbook, serif font family, and oblique style, and a line will appear over the text. The message and messages tags support many other attributes for defining styles. For more information on these attributes, refer to the Jakarta Faces Facelets Tag Library documentation.

Another attribute supported by the h:messages tag is the layout attribute. Its default value is list, which indicates that the messages are displayed in a bullet list using the HTML ul and li elements. If you set the attribute value to table, the messages will be rendered in a table using the HTML table element.

The preceding example shows a standard validator that is registered on the input component. The message tag displays the error message that is associated with this validator when the validator cannot validate the input component’s value. In general, when you register a converter or validator on a component, you are queueing the error messages associated with the converter or validator on the component. The h:message and h:messages tags display the appropriate error messages that are queued on the component when the validators or converters registered on that component fail to convert or validate the component’s value.

Standard error messages are provided with standard converters and standard validators. An application architect can override these standard messages and supply error messages for custom converters and validators by registering custom error messages with the application.

The ability to create bookmarkable URLs refers to the ability to generate links based on a specified navigation outcome and on component parameters.

In HTTP, most browsers by default send GET requests for URL retrieval and POST requests for data processing. The GET requests can have query parameters and can be cached, which is not advised for POST requests, which send data to servers for processing. The other Jakarta Faces tags capable of generating links use either simple GET requests, as in the case of h:outputLink, or POST requests, as in the case of h:commandLink or h:commandButton tags. GET requests with query parameters provide finer granularity to URL strings. These URLs are created with one or more name=value parameters appended to the simple URL after a ? character and separated by either &; or & strings.

To create a bookmarkable URL, use an h:link or h:button tag. Both of these tags can generate a link based on the outcome attribute of the component. For example:

The h:link tag will generate a URL link that points to the somepage.xhtml file on the same server. The following sample HTML is generated from the preceding tag, assuming that the application name is simplebookmark:

This is a simple GET request that cannot pass any data from page to page. To create more complex GET requests and utilize the complete functionality of the h:link tag, use view parameters.

To pass a parameter from one page to another, use the includeViewParams attribute in your h:link tag and, in addition, use an f:param tag to specify the name and value to be passed. Here the h:link tag specifies the outcome page as personal.xhtml and provides a parameter named Result whose value is a managed bean property:

If the includeViewParams attribute is set on the component, the view parameters are added to the hyperlink. Therefore, the resulting URL will look something like this if the value of hello.name is Timmy:

On the outcome page, specify the core tags f:metadata and f:viewparam as the source of parameters for configuring the URLs. View parameters are declared as part of f:metadata for a page, as shown in the following example:

This allows you to specify the bean property value on the page:

As a view parameter, the name also appears in the page’s URL. If you edit the URL, you change the output on the page.

Because the URL can be the result of various parameter values, the order of the URL creation has been predefined. The order in which the various parameter values are read is as follows:

The bookmarks example application modifies the hello1 application described in A Web Module That Uses Jakarta Faces Technology: The hello1 Example to use a bookmarkable URL that uses view parameters.

Like hello1, the application includes the Hello.java managed bean, an index.xhtml page, and a response.xhtml page. In addition, it includes a personal.xhtml page, to which a bookmarkable URL and view parameters are passed from the response.xhtml page, as described in Using View Parameters to Configure Bookmarkable URLs.

You can use either NetBeans IDE or Maven to build, package, deploy, and run the bookmarks example. The source code for this example is in the jakartaee-examples/tutorial/web/faces/bookmarks/ directory.

Resource relocation refers to the ability of a Jakarta Faces application to specify the location where a resource can be rendered. Resource relocation can be defined with the following HTML tags:

These tags have name and target attributes, which can be used to define the render location. For a complete list of attributes for these tags, see the Jakarta Faces Facelets Tag Library documentation.

For the h:outputScript tag, the name and target attributes define where the output of a resource may appear. Here is an example:

Because the target attribute is not defined in the tags, the style sheet hello.css is rendered in the head element of the page, and the hello.js script is rendered in the body of the page.

Here is the HTML generated by the preceding code:

If you set the target attribute for the h:outputScript tag, the incoming GET request provides the location parameter. Here is an example:

In this case, if the incoming request does not provide a location parameter, the default locations will still apply: The style sheet is rendered in the head, and the script is rendered inline. However, if the incoming request specifies the location parameter as the head, both the style sheet and the script will be rendered in the head element.

The HTML generated by the preceding code is as follows:

Similarly, if the incoming request provides the location parameter as the body, the script will be rendered in the body element.

The preceding section describes simple uses for resource relocation. That feature can add even more functionality for the components and pages. A page author does not have to know the location of a resource or its placement.

By using a @ResourceDependency annotation for the components, component authors can define the resources for the component, such as a style sheet and script. This allows the page authors freedom from defining resource locations.