Using the Struts-Faces Library with the Mini HR Application | Struts: The Complete Reference, 2nd Edition

The Struts-Faces Tag Library Tags

The following table lists each of the tags in the Struts-Faces Tag Library and provides a short description of each tag's purpose.

Tag	Description
base	Renders an HTML <base> tag with a reference pointing to the absolute location of the enclosing page.
commandLink	Creates an HTML hyperlink that submits the current form.
errors	Displays the set of Struts and JSF error messages generated by the application during data validation.
form	Renders an HTML <form> tag tied to a Struts action and its corresponding form bean from the Struts configuration file (e.g., struts-config.xml).
html	Renders an HTML <html> tag with language attributes set to the current user's locale.
javascript	Generates client-side JavaScript validation code for validations defined in the Jakarta Commons Validator framework's configuration file (e.g., validation.xml).
loadMessages	Exposes a Struts application resource bundle as a java.util.Map instance with request scope so that the messages can be referenced in JSF value binding expressions (and JSP 2.0 EL expressions).
message	Retrieves an internationalized message from the application resource bundle (e.g., MessageResources.properties) and renders it to a JSP's output stream.
stylesheet	Renders an HTML <link> tag with a reference to a Cascading Style Sheet (CSS) at the specified context-relative path.
write	Renders a literal value or the value of a JSF value binding expression to a JSP's output stream.

The remainder of this section discusses each tag in detail, including a complete description of the tag, a table listing each of the tag's attributes, and a usage example for the tag. In the tables that describe each tag's attributes, pay special attention to the Accepts JSP Expression and Required columns.

The Required column simply denotes whether the given attribute is required when using the tag. In addition to the required column denoting whether an attribute is required, the rows for required attributes are highlighted in gray so that you can determine at a glance which attributes are required.

If an attribute is required and you do not specify it when using the tag, the tag will throw a javax.servlet.jsp.JspException at run time. Note that you can declare an error page in your JSP with a page directive to capture any JspExceptions that might be thrown, as shown here:

<%@ page errorPage="error.jsp" %>

If an exception occurs, the page specified by the errorPage attribute will be internally redirected to display an error page.

The Accepts JSP Expression column denotes whether or not the given attribute's value can be specified with a JSP expression. If a JSP expression is used to specify an attribute value, the expression must comprise the complete value, quote (") to quote ("), as shown here. Correct:

<s:javascript formName="<%=searchForm%>"/>

Incorrect:

<s:javascript formName="<%=searchForm%>-name"/>

Notice in the incorrect example that "-name" is used as part of the value for the formName attribute following the expression. This is invalid because there are extra characters between the end of the expression and the ending quote.

A corrected version of the incorrect example follows:

<s:javascript formName="<%=searchForm + "-name"%>"/>

The concatenation of "-name" is now part of the expression, and the expression comprises the complete value for the attribute.

The base Tag

The base tag is used to render an HTML <base> tag with a reference pointing to the absolute location of the enclosing page. The HTML <base> tag defines the page's base URL for resolving relative URLs contained in the page. That said, the base tag is useful for scenarios where relative URLs should be based on the URL of the enclosing page instead of the URL to which the last form submission took place. Following is an example of the output generated by this tag:

<base href="http://www.abc.com/sfapp/myPage.jsp"/>

Note

The base tag must be nested inside an HTML <head> tag.

Attributes

Attribute	Description	Accepts JSP Expression	Required
binding	Specifies the JSF value binding expression that will bind this component to a backing bean property.	No	No
id	Specifies the JSF component ID for this component.	No	No
rendered	Accepts true or false to specify whether this JSF component will be rendered. Defaults to true.	No	No
target	Specifies the name of the target frame in which all links in the page will be rendered. By default all links will be rendered in the same frame as this tag's enclosing page; however, this attribute allows for other frames to be targeted.	No	No

Example Usage

The following example illustrates the basic usage of the base tag.

<html> <head>   <s:base/> </head>

Assuming the URL of the enclosing page is: http://www.abc.com/sfapp/myPage.jsp, the output generated from the example usage will be:

<base href="http://www.abc.com/sfapp/myPage.jsp"/>

The commandLink Tag

The commandLink tag is used to create an HTML hyperlink that submits the current form. This tag mirrors the commandLink tag in the JSF Core Tag Library. The difference, however, between the JSF Core commandLink tag and the Struts-Faces commandLink tag is that the Struts-Faces version is designed to work with the other tags in the Struts-Faces Tag Library. Unfortunately, the tags in different libraries don't intermix and the Struts-Faces version of the tag is required.

Attributes

Attribute	Description	Accepts JSP Expression	Required
accesskey	Same as the corresponding HTML tag's attribute with the same name. Specifies the keyboard key that causes the link to immediately receive focus when the key is pressed.	No	No
action	Specifies the JSF method binding expression that references a method that will be invoked when the link is selected.	No	No
actionListener	Specifies the JSF method binding expression that references a method that will be invoked with action event notifications when the link is selected.	No	No
charset	Same as the corresponding HTML tag's attribute with the same name. Specifies the character encoding for the link.	No	No
dir	Same as the corresponding HTML tag's attribute with the same name. Specifies the directionality of the link's text.	No	No
hreflang	Same as the corresponding HTML tag's attribute with the same name. Specifies the language for the link.	No	No
id	Specifies the JSF component ID for this component.	No	No
immediate	Accepts true or false to specify whether this JSF component will have its action listener invoked immediately. That is, if true, the action listener will be invoked during the Apply Request Values phase of the JSF request processing lifecycle rather than during the Invoke Application phase. Defaults to true.	No	No
lang	Same as the corresponding HTML tag's attribute with the same name. Specifies the language for the link's text.	No	No
onblur	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the link loses input focus.	No	No
onclick	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the link receives a mouse click.	No	No
ondblclick	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the link receives a mouse double-click.	No	No
onfocus	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the link receives input focus.	No	No
onkeydown	Same as the corresponding HTML tag's attribute with the same name.Specifies the JavaScript code to execute when the link has focus and a key is pressed.	No	No
onkeypress	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the link has focus and a key is pressed and released.	No	No
onkeyup	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the link has focus and a key is released.	No	No
onmousedown	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the link is under the mouse pointer and a mouse button is pressed.	No	No
onmousemove	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the link is under the mouse pointer and the mouse is moved.	No	No
onmouseout	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the link is under the mouse pointer and is then moved away from the link.	No	No
onmouseover	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the link is not under the mouse pointer and is then moved to the link.	No	No
onmouseup	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the link is under the mouse pointer and a mouse button is released.	No	No
rel	Same as the corresponding HTML tag's attribute with the same name. Specifies the relationship from the current page to the page specified with the link.	No	No
rendered	Accepts true or false to specify whether this JSF component will be rendered. Defaults to true.	No	No
rev	Same as the corresponding HTML tag's attribute with the same name. Specifies the relationship from the page specified with the link to the current page.	No	No
style	Specifies the CSS style to be applied to this JSF component.	No	No
styleClass	Specifies the CSS style class to be applied to this JSF component.	No	No
tabindex	Same as the corresponding HTML tag's attribute with the same name. Specifies the tab order for the link.	No	No
target	Same as the corresponding HTML tag's attribute with the same name. Specifies the frame or window target in which the link will be displayed.	No	No
title	Same as the corresponding HTML tag's attribute with the same name. Specifies the title for the link.	No	No
type	Same as the corresponding HTML tag's attribute with the same name. Specifies the content type for the link.	No	No
value	Specifies the text for the link.	No	No

Example Usage

The following example illustrates the basic usage of the commandLink tag.

<s:commandLink actionListener="#{searchAction.search}">   <h:outputText value="Search Employees"/> </s:commandLink>

The Struts-Faces commandLink tag is used exactly the same way as the commandLink tag from the JSF Core Tag Library is used.

The errors Tag

The errors tag is used to display the set of Struts and JSF error messages generated by the application during data validation. This tag will take the stored error messages and iterate over them, displaying them in succession. The following table lists a set of keys from the application resource bundle file (e.g., MessageResources.properties) that will be used to format the messages for display.

Key	Purpose
errors.header	Text that will be output before the list of error messages.
errors.footer	Text that will be output after the list of error messages.
errors.prefix	Text that will be output before each error message.
errors.suffix	Text that will be output after each error message.

Attributes

Attribute	Description	Accepts JSP Expression	Required
binding	Specifies the JSF value binding expression that will bind this component to a backing bean property.	No	No
bundle	Specifies the logical name of a resource bundle that will be used when looking up message keys. The referenced resource bundle must be defined in the application's Struts configuration file.	No	No
id	Specifies the JSF component ID for this component.	No	No
property	Specifies the field for which messages will be displayed. If not specified, all messages, regardless of property, will be displayed.		No
rendered	Accepts true or false to specify whether this JSF component will be rendered. Defaults to true.	No	No

Example Usage

The following snippet illustrates the basic usage of the errors tag:

<s:errors/>

This example will display all the errors currently stored. If you want to limit the errors that are displayed to a specific property, you can specify that property when using the errors tag, as shown here:

<s:errors property="username"/>

In this case, only the errors associated with the property specified by the property attribute will be displayed. Additionally, you can specify the resource bundle from which error messages will be retrieved using the bundle attribute:

<s:errors bundle="CustomBundleName"/>

The bundle specified with the bundle attribute must be configured in the Struts configuration file.

The form Tag

The form tag is used to render an HTML <form> tag tied to a Struts action and its corresponding form bean from the Struts configuration file (e.g., struts-config.xml). The action's form bean will be used by JSF components to populate themselves with data when they are nested inside this tag. This tag differs from the form tag in the JSF HTML Tag Library in that it interfaces with Struts actions and form beans instead of JSF managed beans.

Attributes

Attribute	Description	Accepts JSP Expression	Required
action	Specifies the logical name of an action, defined in the Struts configuration file, to which the form will be submitted.	No	Yes
binding	Specifies the JSF value binding expression that will bind this component to a backing bean property.	No	No
enctype	Same as the corresponding HTML tag's attribute with the same name. Specifies the encoding type that will be used if the form is submitted using the POST method. This attribute must be set to multipart/form-data if the form includes a file upload field.	No	No
focus	Specifies the name of a field inside the form that initial focus will be assigned to using JavaScript once the page has been rendered.	No	No
focusIndex	Specifies an index to be used if the field specified with the focus attribute is a field array such as a radio button group.	No	No
id	Specifies the JSF component ID for this component.	No	No
onreset	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the form is reset.	No	No
onsubmit	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when the form is submitted.	No	No
rendered	Accepts true or false to specify whether this JSF component will be rendered. Defaults to true.	No	No
style	Specifies the CSS style to be applied to this JSF component.	No	No
styleClass	Specifies the CSS style class to be applied to this JSF component.	No	No
target	Same as the corresponding HTML tag's attribute with the same name. Specifies the name of the target frame in which the form will be submitted. By default the form will be submitted in the same frame as this tag's enclosing page; however, this attribute allows for other frames to be targeted.	No	No

Example Usage

The following snippet illustrates the basic usage of the form tag:

 <s:form  action="/search"> Name: <h:inputText  value="#{searchForm.name}"/><br> Social Security Number: <h:inputText  value="#{searchForm.ssNum}"/><br> <h:commandButton  value="Search"/> </s:form>

The Form Bean associated with the action specified by the action attribute will be used for populating the nested JSF components inside the opening and closing form tags.

The html Tag

The html tag is used to render an HTML <html> tag with language attributes set to the current user's locale. Additionally, you can use this tag to instruct nested tags from the Struts HTML Tag Library to generate their output as XHTML instead of HTML. More information on XHTML can be found at http://www.xhtml.org/.

Attributes

Attribute	Description	Accepts JSP Expression	Required
binding	Specifies the JSF value binding expression that will bind this component to a backing bean property.	No	No
id	Specifies the JSF component ID for this component.	No	No
locale	Accepts true or false to specify whether a java. util.Locale object, set to the current request's AcceptLanguage HTTP header, will be placed into the session. If a session does not exist, one will be created when this tag stores the Locale object. Defaults to false.	No	No
rendered	Accepts true or false to specify whether this JSF component will be rendered. Defaults to true.	No	No
xhtml	Accepts true or false to specify whether nested tags from the Struts HTML Tag Library will generate their output as XHTML instead of HTML. Note that enabling this feature will not cause JSF components to render their output as XHTML. Defaults to false.	No	No

Example Usage

The following snippet shows the basic usage of the html tag:

<f:view> <s:html> <body> ... </body> </s:html> </f:view>

If you want nested tags from the Struts HTML Tag Library to generate XHTML instead of HTML, use the html tag as shown here:

<f:view> <s:html xhtml="true"> <body> ... </body> </s:html> </f:view>

The javascript Tag

The javascript tag is used to generate client-side JavaScript validation code for validations defined in the Jakarta Commons Validator framework's configuration file (e.g., validation.xml). The JavaScript code generated by the javascript tag can be broken down into two pieces: static code and dynamic code. The static piece is composed of all the generic validation routine methods. The dynamic piece is composed of the code that is specific to a particular HTML form and that calls the static validation methods. Because the static piece of code is typically very large and is often repeated across several pages, it is advantageous to break that piece out and store it in its own file. That way, it can simply be referenced by each page that makes use of it. The javascript tag allows you to break up the two pieces of code by specifying which code it generates with the dynamicJavascript and staticJavascript attributes.

Note

Unlike the other tags in the Struts Faces Tag Library, the javascript tag is not tied to a JSF component and is simply a replication of the functionality provided by the Struts HTML Tag Library's javascript tag.

Attributes

Attribute	Description	Accepts JSP Expression	Required
cdata	Accepts true or false to specify whether the generated JavaScript code will be enclosed in XML CDATA tags (i.e., <![CDATA[ ]]>). CDATA tags are necessary to prevent JavaScript code from being parsed when used in conjunction with XHTML. Defaults to true.	Yes	No
dynamicJavascript	Accepts true or false to specify whether dynamic JavaScript will be generated. Defaults to true.	No	No
formName	Specifies the logical name of a form whose validation rules will be used to generate JavaScript validation code. The name specified with this attribute must match the named specified in a <form> definition in the Validator configuration file.	Yes	No
htmlComment	Accepts true or false to specify whether the generated JavaScript code will be enclosed in HTML comment tags (i.e., <!-- -->). Note that this attribute will be ignored when operating in XHTML mode. Defaults to true.	Yes	No
method	Specifies an alternate JavaScript method name to be used by the client-side Validator code instead of the default method name. The default method name is generated based on the form name by prefixing the form name with "validate" (e.g., a form name of "logonForm" would have a validate method of "validateLogonForm").	Yes	No
page	Specifies the logical name of a page to use to filter which validations for the specified form will be generated. This logical name matches the logical name that can be applied to individual fields in the Validator configuration file.	Yes	No
src	Same as the corresponding JavaScript tag's attribute with the same name. Specifies the URL to a static JavaScript file to be included.	Yes	No
staticJavascript	Accepts true or false to specify whether static JavaScript will be generated. Defaults to true.	No	No

Example Usage

The following snippet illustrates the basic usage of the javascript tag:

<s:javascript formName="logonForm"/>

This example will generate JavaScript code for all of the validation rules in the Validator configuration file that are tied to the form specified by the formName attribute.

If you want to separate the dynamic and static pieces of the generated JavaScript code, you can use the javascript tag as shown next:

<s:javascript formName="logonForm"       staticJavascript="false"                    src="/books/1/249/1/html/2/staticJavascript.jsp"/>

This usage only generates the dynamic JavaScript for the specified form. The following example generates the generic static JavaScript code:

<s:javascript formName="logonForm" dynamicJavascript="false"/>

This snippet must be placed into a separate file named staticJavascript.jsp to match the file name specified by the src attribute of the previous example.

The loadMessages Tag

The loadMessages tag is used to expose a Struts application resource bundle as a java.util.Map instance with request scope so that the messages can be referenced in JSF value binding expressions (and JSP 2.0 EL expressions).

Attributes

Attribute	Description	Accepts JSP Expression	Required
messages	Specifies the logical name of a resource bundle that will be exposed. The referenced resource bundle must be defined in the application's Struts configuration file.	No	No
var	Specifies the request scope key that the map will be stored under.	No	Yes

Example Usage

The following example illustrates the basic usage of the loadMessages tag.

<s:loadMessages var="messages"/>

The preceding example exposes the default Struts application resource bundle. The following example exposes an alternate application resource bundle with the "alternateBundle" logical name:

<s:loadMessages messages="alternateBundle" var="messages"/>

Once the resource bundle has been exposed via the loadMessages tag, its messages can be referenced using the variable name defined with the var attribute, as shown here:

<h:outputText value="#{messages['label.search.ssNum']}"/>

The exposed variable containing the messages is a Map instance that has request scope.

The message Tag

The message tag is used to retrieve an internationalized message from the application resource bundle (e.g., MessageResources.properties) and render it to a JSP's output stream. Recall that resource bundle files in Struts applications are based on Java's Resource Bundle functionality for externalizing and internationalizing application strings, messages, and labels. Following is a sample resource bundle properties file:

# Label Resources label.search.name=Name label.search.ssNum=Social Security Number     # Error Resources error.search.criteria.missing=Search Criteria Missing error.search.ssNum.invalid=Invalid Social Security Number errors.header=<font color="red"><cTypeface:Bold>Validation Error(s)</b></font><ul> errors.footer=</ul><hr width="100%" size="1" noshade="true"> errors.prefix=<li> errors.suffix=</li>

As you can see, the file is made up of key/value pairs. The message tag simply looks up a message with a given key and returns its matching value.

Note

The resource bundle file must be configured in your application's Struts configuration file before it can be accessed via the message tag. See Chapter 18 for more information on the Struts configuration file.

The message tag also allows you to insert content into messages at run time before they are rendered using parametric replacement, which is the substitution of an argument for a placeholder parameter at run time. Following is an example message that uses parametric replacement:

missing.field=The {0} field is missing.

Notice the {0} reference in the message. At run time, the {0} parameter will be dynamically replaced with another value. The message tag allows you to specify what the replacement values are by nesting instances of the JSF HTML Tag Library's parameter tag.

Attributes

Attribute	Description	Accepts JSP Expression	Required
binding	Specifies the JSF value binding expression that will bind this component to a backing bean property.	No	No
bundle	Specifies the logical name of a resource bundle that will be used when looking up message keys. The referenced resource bundle must be defined in the application's Struts configuration file.	No	No
filter	Accepts true or false to specify whether this component's output will be filtered for sensitive HTML characters (e.g., > and <). Filtered characters are replaced with their HTML entity equivalent (e.g., ">" replaced with ">" and so on). Defaults to true.	No	No
id	Specifies the JSF component ID for this component.	No	No
key	Specifies the name of the application resource bundle key whose corresponding value will be rendered. This attribute and the value attribute are mutually exclusive-one or the other must be specified.	No	No
rendered	Accepts true or false to specify whether this JSF component will be rendered. Defaults to true.	No	No
style	Specifies the CSS style to be applied to this JSF component.	No	No
styleClass	Specifies the CSS style class to be applied to this JSF component.	No	No
value	Specifies a JSF value binding expression that evaluates to the name of the application resource bundle key whose corresponding value will be rendered. This attribute and the key attribute are mutually exclusive-one or the other must be specified.	No	No

Example Usage

Generally speaking, there are two ways that the message tag can be used. The first way, shown here, uses the key attribute to specify the name of a resource bundle key whose value will be rendered:

<s:message key="label.search.ssNum"/>

The second way to use the message tag is shown here:

<s:message value="#{errors.missingField}">   <f:param value="Social Security Number"/> </s:message>

In this example, the value attribute is used to specify a JSF value binding expression that evaluates to the name of a resource bundle key whose value will be rendered. The nested parameter tags specify the parametric replacement values for the resource bundle message.

The stylesheet Tag

The stylesheet tag is used to render an HTML <link> tag with a reference to a Cascading Style Sheet (CSS) at the specified context-relative path. Following is an example of the output generated by this tag:

<link rel="stylesheet" href="/myWebApp/site.css" type="text/css"/>

The output of this tag is the same as would be coded by hand when referencing a style sheet. The stylesheet tag simplifies the creation of the HTML <link> tag, though, by allowing the path to the style sheet to be specified relative to the Web application. That way, Web application names are not hard-coded into your JSPs, thus allowing seamless application renaming and so on.

To determine the context path to prefix to the style sheet path, the stylesheet tag makes a call to javax.faces.context.FacesContext.getExternalContext( ).getRequestContextPath( ) which ultimately calls javax.servlet.http.HttpServletRequest.getContextPath( ) for servlets or javax.portlet.PortletRequest.getContextPath( ) for portlets.

Attributes

Attribute	Description	Accepts JSP Expression	Required
binding	Specifies the JSF value binding expression that will bind this component to a backing bean property.	No	No
id	Specifies the JSF component ID for this component.	No	No
path	Specifies the context-relative path to the style sheet.	No	Yes
rendered	Accepts true or false to specify whether this JSF component will be rendered. Defaults to true.	No	No

Example Usage

The following example illustrates the basic usage of the stylesheet tag.

<s:stylsheet path="/site.css"/>

Assuming a context path of /sfapp, the output generated from this example usage will be:

<link rel="stylesheet" href="/sfapp/site.css" type="text/css"/>

The path specified with the path attribute is simply appended to the context path to form the complete path to the style sheet.

The write Tag

The write tag is used to render a literal value or the value of a JSF value binding expression to a JSP's output stream.

Attributes

Attribute	Description	Accepts JSP Expression	Required
binding	Specifies the JSF value binding expression that will bind this component to a backing bean property.	No	No
filter	Accepts true or false to specify whether this component's output will be filtered for sensitive HTML characters (e.g., > and <). Filtered characters are replaced with their HTML entity equivalent (e.g., ">" replaced with ">" and so on). Defaults to true.	No	No
id	Specifies the JSF component ID for this component.	No	No
rendered	Accepts true or false to specify whether this JSF component will be rendered. Defaults to true.	No	No
style	Specifies the CSS style to be applied to this JSF component.	No	No
styleClass	Specifies the CSS style class to be applied to this JSF component.	No	No
value	Specifies the literal value to be rendered or a JSF value binding expression that evaluates to the value to be rendered.	No	No

Example Usage

The following example illustrates the basic usage of the write tag.

<s:write value="text to render"/>

The preceding example simply outputs the literal text to the JSP. The real benefit in using the write tag, however, is in using it to render the value of a JSF value binding expression, as shown here:

<s:write value="#{regForm.employee.firstName}"/>

The write tag will evaluate the expression and render its value.