Home | Download | PDF | API | FAQ | Search | Feedback | History

> ## Setting Up a Page

> A typical JavaServer Faces page includes the following elements:

> - A set of tag library declarations that declare the two JavaServer Faces tag libraries.
> - A `view` tag
> - A `form` tag

> This section tells you how to add these elements to your pages and briefly describes the `subview` tag for including JavaServer Faces pages inside other pages.

> To use the JavaServer Faces UI components in your JSP page, you need to give the page access to the two standard tag libraries: the JavaServer Faces HTML render kit tag library and the 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, page 137).

> 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 render kit tag library. The `jsf_core` TLD describes the JavaServer Faces core tag library.

> Please refer to the TLD documentation at `http://java.sun.com/javaee/javaserverfaces/1.2/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 `jsf-impl.jar`, located in `<JavaEE_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 `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. Therefore, all component tags on the page must be enclosed in the `view` tag, which is defined in the `jsf_core` TLD:

>     <f:view>
>       ... other JavaServer 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 four optional attributes:

> - A `locale` attribute. If this attribute is present, its value overrides the `Locale` stored in the `UIViewRoot` component. 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 `renderKitId` attribute. A page author uses this attribute to refer to the ID of the render kit used to render the page, therefore allowing the use of custom render kits. If this attribute is not specified, the default HTML render kit is assumed. The process of creating custom render kits is outside the scope of this tutorial.
> - A `beforePhase` attribute. This attribute references a method that takes a `PhaseEvent` object and returns `void`, causing the referenced method to be called before each phase (except restore view) of the life cycle begins.
> - An `afterPhase` attribute. This attribute references a method that takes a `PhaseEvent` object and returns void, causing the referenced method to be called after each phase (except restore view) in the life cycle ends.

> An advanced developer might implement the methods referenced by `beforePhase` and `afterPhase` to perform such functions as initialize or release resources on a per-page basis. This feature is outside of the scope of this tutorial.

> The `form` tag is nested inside of the `view` tag. As its name suggests, the `form` tag represents 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 Adding a Form Component for more details on using the `form` tag.

> If you want to include a page containing JavaServer Faces tags within another JSP page tht includes JavaServer Faces tags, you must enclose the entire nested page in a `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 the `subview` tag inside the nested page, but it must enclose all the JavaServer Faces tags on the nested page.

> The `subview` tag has two optional attributes: `binding` and `rendered`. The `binding` attribute binds to a component that implements `NamingContainer`. One potential use case of binding a subview component to a bean is if you want to dynamically add components to the subview in the backing bean.

> The `rendered` attribute can be set to true or false, indicating whether or not the components nested in the `subview` tag should be rendered.

> 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 Adding UI Components to a Page 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 render kit tag library.