Describes the JSF development process, standard JSF tags, the JSF expression language, and the faces-config.xml configuration file.
Written By
JavaServer Faces (JSF) is the "official" component-based view technology in the Java EE web tier. JSF includes a set of predefined UI components, an event-driven programming model, and the ability to add third-party components. JSF is designed to be extensible, easy to use, and toolable. This refcard describes the JSF development process, standard JSF tags, the JSF expression language, and the faces-config.xml configuration file.
A developer specifies JSF components in JSF pages, combining JSF component tags with HTML and CSS for styling. Components are linked with managed beans,Java classes that contain presentation logic and connect to business logic and persistence backends. Entries in faces-config.xml contain navigation rules and instructions for loading managed beans.
A JSF page has the following structure:
| JSP Style | Proper XML |
|---|---|
|
|
These common tasks give you a crash course into using JSF.
<h:inputText value="#{bean1.luckyNumber}"><managed-bean>
<managed-bean-name>bean1</managed-bean-name>
<managed-bean-class>com.corejsf.SampleBean</
managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
</managed-bean>public class SampleBean {
public int getLuckyNumber() { ... }
public void setLuckyNumber(int value) { ... }
...
}
<h:commandButton value="press me" action="#{bean1.
login}"/><navigation-rule>
<navigation-case>
<from-outcome>success</from-outcome>
<to-view-id>/success.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>error</from-outcome>
<to-view-id>/error.jspx</to-view-id>
<redirect/>
</navigation-case>
</navigation-rule>public class SampleBean {
public String login() { if (...) return
"success"; else return "error"; }
...
}
<h:selectOneRadio value="#{form.condiment}>
<f:selectItems value="#{form.condimentItems}"/>
</h:selectOneRadio>public class SampleBean {
private Map<String, Object> condimentItem = null;
public Map<String, Object> getCondimentItems() {
if (condimentItem == null) {
condimentItem = new LinkedHashMap<String,
Object>();
condimentItem.put("Cheese", 1); // label, value
condimentItem.put("Pickle", 2);
...
}
return condimentItem;
}
public int getCondiment() { ... }
public void setCondiment(int value) { ... }
...
}<h:inputText value="#{payment.amount}"
required="true">
<f:validateDoubleRange maximum="1000"/>
</h:inputText>
<h:outputText value="#{payment.amount}">
<f:convertNumber type="currency"/>
<!-- number displayed with currency symbol and
group separator: $1,000.00 -->
</h:outputText>
<h:outputText value="Amount"/>
<h:inputText id="amount" label="Amount"
value="#{payment.amount}"/>
<!-- label is used in message text -->
<h:message for="amount"/><head>
<link href="styles.css" rel="stylesheet"
type="text/css"/>
...
</head>
<body>
...
<h:outputText value="#{msgs.goodbye}!"
styleClass="goodbye">
...
</body><application>
<resource-bundle>
<base-name>com.corejsf.messages</base-name>
<var>msgs</var>
</resource-bundle>
</application>goodbye=Goodbyegoodbye=Auf Wiedersehen.goodbye {
font-style: italic;
font-size: 1.5em;
color: #eee;
}| Name | |
|---|---|
| Washington, George | Delete |
| Jefferson, Thomas | Delete |
| Lincoln, Abraham | Delete |
| Roosevelt, Theodore | Delete |
<h:dataTable value="#{bean1.entries}" var="row"
styleClass="table" rowClasses="even,odd">
<h:column>
<f:facet name="header">
<h:outputText value="Name"/>
</f:facet>
<h:outputText value="#{row.name}"/>
</h:column>
<h:column>
<h:commandLink value="Delete" action="#{bean1.
deleteAction}" immediate="true">
<f:setPropertyActionListener target="#{bean1.
idToDelete}"
value="#{row.id}"/>
</h:commandLink>
</h:column>
</h:dataTable>public class SampleBean {
private int idToDelete;
public void setIdToDelete(int value) {idToDelete
= value; }
public String deleteAction() {
// delete the entry whose id is idToDelete
return null;
}
public List<Entry> getEntries() {...}
...
}
The faces-config.xml file contains a sequence of the following entries.
<?xml version="1.0"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
version="2.5">
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</
servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<!-- Add this element to change the extension for
JSF page files (Default: .jsp) -->
<context-param>
<param-name>javax.faces.DEFAULT_SUFFIX</paramname>
<param-value>.jspx</param-value>
</context-param>
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>*.faces</url-pattern>
<!-- Another popular URL pattern is /faces/* -->
</servlet-mapping>
<welcome-file-list>
<welcome-file>index.faces</welcome-file>
<!-- Create a blank index.faces (in addition to
index.jspx) -->
<welcome-file>index.html</welcome-file>
<!-- Use <meta http-equiv="Refresh" content=
"0; URL=index.faces"/> -->
</welcome-file-list>
</web-app>
An EL expression is a sequence of literal strings and expressions of the form base[expr1][expr2]... As in JavaScript, you can write base.identifier instead of base['identifier'] or base["identifier"]. The base is one of the names in the table below or a name defined in faces-config.xml.
| header | A Map of HTTP header parameters, containing only the first value for each name. |
| headerValues | A Map of HTTP header parameters, yielding a String[] array of all values for a given name |
| param | A Map of HTTP request parameters, containing only the first value for each name. |
| paramValues | A Map of HTTP request parameters, yielding a String[] array of all values for a given name. |
| cookie | A Map of the cookie names and values of the current request. |
| initParam | A Map of the initialization parameters of this web application. |
| requestScope | A Map of all request scope attributes. |
| sessionScope | A Map of all session scope attributes. |
| applicationScope | A Map of all application scope attributes. |
| facesContext | The FacesContext instance of this request. |
| view | The UIViewRoot instance of this request. |
There are two expression types:
userBean.name calls getName or setName on the userBean objectpizza.choices[var] calls pizza.getChoices( ).get(var) or pizza.getChoices( ).put(var, ...)userBean.login calls the login method on the userBean object when it is invoked.In JSF, EL expressions are enclosed in #{...} to indicate deferred evaluation. The expression is stored as a string and evaluated when needed. In contrast, JSP uses immediate evaluation, indicated by ${...} delimiters.
| Tag | Description/Attributes | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| f:view | Creates the top-level view
|
||||||||||||||||||||||
| f:subview | Creates a subview of a view
|
||||||||||||||||||||||
| f:facet | Adds a facet to a component
|
||||||||||||||||||||||
| f:attribute | Adds an attribute to a component
|
||||||||||||||||||||||
| f:param | Constructs a parameter child component
|
||||||||||||||||||||||
| f:actionListener f:valueChangeListener |
Adds an action listener or value change listener to a component
|
||||||||||||||||||||||
| f:setPropertyChange Listener (JSF 1.2) | Adds an action listener to a component that sets a bean property to a given value.
|
||||||||||||||||||||||
| f:converter | Adds an arbitary converter to a component
|
||||||||||||||||||||||
| f:convertDateTime | Adds a datetime converter to a component
|
||||||||||||||||||||||
| f:convertNumber | Adds a number converter to a component
|
||||||||||||||||||||||
| f:validator | Adds a validator to a component
|
||||||||||||||||||||||
| f:validateDoubleRange f:validateLongRange f:validateLength |
Validates a double or long value, or the length of a string
|
||||||||||||||||||||||
| f:loadBundle | Loads a resource bundle, stores properties as a Map
|
||||||||||||||||||||||
| f:selectitems | Specifies items for a select one or select many component
|
||||||||||||||||||||||
| f:selectitem | Specifies an item for a select one or select many component
|
||||||||||||||||||||||
| f:verbatim | Adds markup to a JSF page
|
| Tag | Description | |
|---|---|---|
| h:form | HTML form | |
| h:inputText | Single-line text input control |  |
| h:inputTextarea | Multiline text input control |  |
| h:inputSecret | Password input control |  |
| h:inputHidden | Hidden field | |
| h:outputLabel | Label for another component for accessibility | |
| h:outputLink | HTML anchor |  |
| h:outputFormat | Like outputText, but formats compound messages | |
| h:outputText | Single-line text output | |
| h:commandButton | Button: submit, reset, or pushbutton |  |
| h:commandLink | Link that acts like a pushbutton. | register |
| h:message | Displays the most recent message for a component |  |
| h:messages | Displays all messages | |
| h:grapicImage | Displays an image |  |
| h:selectOneListbox | Single-select listbox |  |
| h:selectOneMenu | Single-select menu |  |
| h:selectOneRadio | Set of radio buttons |  |
| h:selectBooleanCheckbox | Checkbox |  |
| h:selectManyCheckbox | Multiselect listbox |  |
| h:selectManyListbox | Multiselect listbox |  |
| h:selectManyMenu | Multiselect menu |  |
| h:panelGrid | HTML table | |
| h:panelGroup | Two or more components that are laid out as one | |
| h:dataTable | A feature-rich table component | |
| h:column | Column in a data table |
Identifier for a component binding Reference to the component that can be used in a backing bean rendered A boolean; false suppresses rendering styleClass Cascading stylesheet (CSS) class name value A component's value, typically a value binding valueChangeListener A method binding to a method that responds to value changes converter Converter class name validator Class name of a validator that's created and attached to a component required A boolean; if true, requires a value to be entered in the associated field
| Attribute | Description |
|---|---|
| id | Identifier for a component |
| binding | Reference to the component that can be used in a backing bean |
| rendered | A boolean; false suppresses rendering |
| styleClass | Cascading stylesheet (CSS) class name |
| value | A component's value, typically a value binding |
| valueChangeListener | A method binding to a method that responds to value changes |
| converter | Converter class name |
| validator | Class name of a validator that's created and attached to a component |
| required | A boolean; if true, requires a value to be entered in the associated field |
| Attribute | Description |
|---|---|
| binding, id, rendered, styleClass | Basic attributes |
| accept, acceptcharset, dir, enctype, lang, style, target, title | HTML 4.0 attributes (acceptcharset corresponds to HTML accept-charset) |
| onblur, onchange, onclick, ondblclick, onfocus, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onreset, onsubmit | DHTML events |
| Attribute | Description |
|---|---|
| cols | For h:inputTextarea only,number of columns |
| immediate | Process validation early in the life cycle |
| redisplay | For h:inputSecret only,when true, the input field's value is redisplayed when the web page is reloaded |
| required | Require input in the component when the form is submitted |
| rows | For h:inputTextarea only,number of rows |
| valueChangeListener | A specified listener that's notified of value changes |
| binding, converter, id, rendered, required, styleClass, value, validator | Basic attributes |
| accesskey, alt, dir, disabled, lang, maxlength, readonly, size, style, tabindex, title | HTML 4.0 pass-through attributes,alt, maxlength, and size do not apply to h:inputTextarea. None apply to h:inputHidden |
| onblur, onchange, onclick, ondblclick, onfocus, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onselect | DHTML events. None apply to h:inputHidden |
| Attribute | Description |
|---|---|
| escape | If set to true, escapes <, >, and & characters. Default value is true. |
| binding, converter, id, rendered, styleClass, value | Basic at tributes |
| style, title | HTML 4.0 |
| Attribute | Description |
|---|---|
| for | The ID of the component to be labeled. |
| binding, converter, id, rendered, value | Basic attributes |
| Attribute | Description |
|---|---|
| binding, id, rendered, styleClass, value | Basic attributes |
| alt, dir, height, ismap, lang, longdesc, style, title, url, usemap, width | HTML 4.0 |
| onblur, onchange, onclick, ondblclick, onfocus, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup | DHTML events |
| Attribute | Description |
|---|---|
| action | If specified as a string: Directly specifies an outcome used by the navigation handler to determine the JSF page to load next as a result of activating the button or link If specified as a method binding: The method has this signature: String methodName(); the string represents the outcome |
| actionListener | A method binding that refers to a method with this signature: void methodName(ActionEvent) |
| charset | For h:commandLink only,The character encoding of the linked reference |
| image | For h:commandButton only,A context-relative path to an image displayed in a button. If you specify this attribute, the HTML input's type will be image. |
| immediate | A boolean. If false (the default), actions and action listeners are invoked at the end of the request life cycle; if true, actions and action listeners are invoked at the beginning of the life cycle. |
| type | For h:commandButton: The type of the generated input element: button, submit, or reset. The default, unless you specify the image attribute, is submit. For h:commandLink: The content type of the linked resource; for example, text/html, image/ gif, or audio/basic |
| value | The label displayed by the button or link. You can specify a string or a value reference expression. |
| accesskey, alt, binding, id, lang, rendered, styleClass, value | Basic attributes |
| coords (h:commandLink only), dir, disabled (h:commandButton only), hreflang (h:commandLink only), lang, readonly, rel (h:commandLink only), rev (h:commandLink only), shape (h:commandLink only), style, tabindex, target (h:commandLink only), title, type | HTML 4.0 |
| onblur, onchange, onclick, ondblclick, onfocus, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselect | DHTML events |
| Attribute | Description |
|---|---|
| accesskey, binding, converter, id, lang, rendered, styleClass, value | Basic attributes |
| charset, coords, dir, hreflang, lang, rel, rev, shape, style, tabindex, target, title, type | HTML 4.0 |
| onblur, onchange, onclick, ondblclick, onfocus, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup | DHTML events |
h:selectBooleanCheckbox,
h:selectManyCheckbox,
h:selectOneRadio,
h:selectOneListbox,
h:selectManyListbox,
h:selectOneMenu,
h:selectManyMenu
| Attribute | Description |
|---|---|
| disabledClass | CSS class for disabled elements,for h:selectOneRadio and h:selectManyCheckbox only |
| enabledClass | CSS class for enabled elements,for h:selectOneRadio and h:selectManyCheckbox only |
| layout | Specification for how elements are laid out: lineDirection (horizontal) or pageDirection (vertical),for h:selectOneRadio and h:selectManyCheckbox only |
| binding, converter, id, immediate, styleClass, required, rendered, validator, value, valueChangeListener | Basic attributes |
| accesskey, border, dir, disabled, lang, readonly, style, size, tabindex, title | HTML 4.0,border is applicable to h:selectOneRadio and h:selectManyCheckbox only. size is applicable to h:selectOneListbox and h:selectManyListbox only |
| onblur, onchange, onclick, ondblclick, onfocus, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onselect | DHTML events |
| Attribute | Description |
|---|---|
| for | The ID of the component whose message is displayed,applicable only to h:message |
| errorClass | CSS class applied to error messages |
| errorStyle | CSS style applied to error messages |
| fatalClass | CSS class applied to fatal messages |
| fatalStyle | CSS style applied to fatal messages |
| globalOnly | Instruction to display only global messages,applicable only to h:messages. Default: false |
| infoClass | CSS class applied to information messages |
| infoStyle | CSS style applied to information messages |
| layout | Specification for message layout: table or list,applicable only to h:messages |
| showDetail | A boolean that determines whether message details are shown. Defaults are false for h:messages, true for h:message |
| showSummary | A boolean that determines whether message summaries are shown. Defaults are true for h:messages, false for h:message |
| tooltip | A boolean that determines whether message details are rendered in a tooltip; the tooltip is only rendered if showDetail and showSummary are true |
| warnClass | CSS class for warning messages |
| warnStyle | CSS style for warning messages |
| binding, id, rendered, styleClass | Basic attributes |
| style, title | HTML 4.0 |
| Attribute | Description |
|---|---|
| bgcolor | Background color for the table |
| border | Width of the table's border |
| cellpadding | Padding around table cells |
| cellspacing | Spacing between table cells |
| columnClasses | Comma-separated list of CSS classes for columns |
| columns | Number of columns in the table |
| footerClass | CSS class for the table footer |
| frame | Specification for sides of the frame surrounding the table that are to be drawn; valid values: none, above, below, hsides, vsides, lhs, rhs, box, border |
| headerClass | CSS class for the table header |
| rowClasses | Comma-separated list of CSS classes for columns |
| rules | Specification for lines drawn between cells; valid values: groups, rows, columns, all |
| summary | Summary of the table's purpose and structure used for non-visual feedback such as speech |
| binding, id, rendered, styleClass, value | Basic attributes |
| dir, lang, style, title, width | HTML 4.0 |
| onclick, ondblclick, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup | DHTML events |
| Attribute | Description |
|---|---|
| binding, id, rendered, styleClass | Basic attributes |
| style | HTML 4.0 |
| Attribute | Description |
|---|---|
| bgcolor | Background color for the table |
| border | Width of the table's border |
| cellpadding | Padding around table cells |
| cellspacing | Spacing between table cells |
| columnClasses | Comma-separated list of CSS classes for columns |
| first | Index of the first row shown in the table |
| footerClass | CSS class for the table footer |
| frame | Frame Specification for sides of the frame surrounding the table that are to be drawn; valid values: none, above, below, hsides, vsides, lhs, rhs, box, border |
| headerClass | CSS class for the table header |
| rowClasses | Comma-separated list of CSS classes for rows |
| rules | Specification for lines drawn between cells; valid values: groups, rows, columns, all |
| summary | Summary of the table's purpose and structure used for nonvisual feedback such as speech |
| var | The name of the variable created by the data table that represents the current item in the value |
| binding, id, rendered, styleClass, value | Basic attributes |
| dir, lang, style, title, width | HTML 4.0 |
| onclick, ondblclick, onkeydown, onkeypress, onkeyup, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup | DHTML events |
| Attribute | Description |
|---|---|
| headerClass (JSF 1.2) | CSS class for the column's header |
| footerClass (JSF 1.2) | CSS class for the column's footer |
| binding, id, rendered | Basic attributes |