Setting Up a Page

To use the JavaServer Faces UI components in your JSP page, you need to give the page access to the two standard tag libraries: JavaServer Faces standard HTML render kit tag library and JavaServer Faces core tag library. The JavaServer Faces standard HTML render kit tag library defines tags that represent common HTML user interface components. The JavaServer Faces core tag library defines tags that perform core actions and are independent of a particular render kit.

Using these tag libraries is similar to using any other custom tag library. This chapter assumes that you are familiar with the basics of using custom tags in JSP pages (see Using Custom Tags).

As is the case with any tag library, each JavaServer Faces tag library must have a TLD that describes it. The html_basic TLD describes the The JavaServer Faces Standard HTML RenderKit tag library. The jsf_core TLD describes the JavaServer Faces Core tag library.

Please refer to the TLD documentation at http://java.sun.com/j2ee/javaserverfaces/1.0/docs/tlddocs/index.html for a complete list of the JavaServer Faces tags and their attributes.

Your application needs access to these TLDs in order for your pages to use them. The Application Server includes these TLDs in the jsf-impl.jar, located in <J2EE_HOME>/lib.

To use any of the JavaServer Faces tags, you need to include these taglib directives at the top of each page containing the tags defined by these tag libraries:

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>

The uri attribute value uniquely identifies the TLD. The prefix attribute value is used to distinguish tags belonging to the tag library. You can use other prefixes rather than the h or f prefixes. However, you must use the prefix you have chosen when including the tag in the page. For example, the form tag must be referenced in the page via the h prefix because the preceding tag library directive uses the h prefix to distinguish the tags defined in the html_basic.tld:

<h:form ...>

A page containing JavaServer Faces tags is represented by a tree of components. At the root of the tree is the UIViewRoot component. The view tag represents this component on the page. Thus, all component tags on the page must be enclosed in the view tag, which is defined in the jsf_core TLD:

<f:view>
  ... other faces tags, possibly mixed with other content ...
</f:view>

You can enclose other content, including HTML and other JSP tags, within the view tag, but all JavaServer Faces tags must be enclosed within the view tag.

The view tag has an optional locale attribute. If this attribute is present, its value overrides the Locale stored in the UIViewRoot. This value is specified as a String and must be of this form:

:language:[{-,_}:country:[{-,_}:variant]

The :language:, :country:, and :variant: parts of the expression are as specified in java.util.Locale.

A typical JSP page includes a form, which is submitted when a button or hyperlink on the page is clicked. For the data of other components on the page to be submitted with the form, the tags representing the components must be nested inside the form tag. See The UIForm Component for more details on using the form tag.

If you want to include a page containing JavaServer Faces tags within another JSP page (which could also contain JavaServer Faces tags), you must enclose the entire nested page in an subview tag. You can add the subview tag on the parent page and nest a jsp:include inside it to include the page:

<f:subview id="myNestedPage">
  <jsp:include page="theNestedPage.jsp" />
</f:subview>

You can also include subview inside the nested page, but it must enclose all the JavaServer Faces tags on the nested page.

In summary, a typical JSP page that uses JavaServer Faces tags will look somewhat like this:

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>

<f:view>
  <h:form>
    other JavaServer Faces tags and core tags, 
    including one or more button or hyperlink components for 
    submitting the form
  </h:form>
</f:view>

The sections Using the Core Tags and Using the HTML Component Tags describe how to use the core tags from the JavaServer Faces Core tag library and the component tags from the JavaServer Faces standard HTML RenderKit tag library.