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. |
|
|
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 id="search" action="/search">
Name: <h:inputText id="name" value="#{searchForm.name}"/><br>
Social Security Number: <h:inputText id="ssNum" value="#{searchForm.ssNum}"/><br>
<h:commandButton id="submit" 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. |
|
|
dynamicJavascript | Accepts true or false to specify whether dynamic JavaScript will be generated. Defaults to true. |
|
|
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. |
|
|
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="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.
No comments:
Post a Comment