A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
Now that you’re aware of the dangers, here’s how you’d declare multiple message resource files in your struts-config.xmlfile:
<!-- the default message resource file: --> <message-resources parameter="Application" />
<!-- another message resource file --> <message-resources parameter="Application2"
key="myOtherResourceFile"/>
In this example, the second message resource file is Application2.properties, and is stored in the same place as the default Application.properties file (that is, in /WEB-INF/ classes/).
To display a prompt from the default file, you’d use
<bean:message key="app.error.prompt.login" />
To display a prompt from the second file, you’d use
This snippet is an equivalent for the last example, with a single replacement parameter. If you’re using JSF, you might find it convenient to use the Struts-Faces library (see
Chapter 20) to expose the default message resource file:
This is the equivalent of the previous JSTL example.
Lastly, there is <s:message> from the Struts-Faces integration library.
page
This handy tag exposes objects from the page context as variables that may be accessed with scriptlets or custom tags.
The PageContext object is the central repository of all state for the current page. This includes the session (HttpSession) and request (HttpServletRequest) that were described in Chapter 2. There is more:
•application: The javax.servlet.ServletContext object, obtained by calling pageContext.getServletContext().
•config: The javax.servlet.ServletConfig object, obtained by calling pageContext.getServletConfig(). Don’t confuse this with Struts’ internal configuration objects.
•response: The HttpServletResponse object associated with the page.
You should consult a recent reference on servlets (or Google the classname to get the JavaDoc) to find out more about these objects.
Usage Restrictions
Both id and property attributes are required.
430
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
Attributes
•id: The name of the exposed variable. Scriptlets and other custom tags will be able to access the new variable using this name. This attribute is required.
•property: The value is application, session, request, config, or response; used to get the associated objects from the page context. This attribute is required.
Examples
The snippet
<bean:page id="myVar" property="session" />
exposes the session object (HttpSession) associated with the enclosing page as a bean named myVar. The other page context objects are similarly exposed.
Equivalents
JSTL’s <c:set> can be used to replace <bean:page>. Let’s look at some examples. To expose the application, use this:
You should note that the JSTL implicit object sessionScope is not the same as pageContext.session. The former is a Map containing key/value pairs, and the latter is the actual HttpSession object, whose properties you can read.
resource
resource allows you to read any file from the current webapp and expose it either as a
String variable or an InputStream. See also <bean:include>.
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
431
Usage Restrictions
The id and name attributes are required.
Attributes
•id: The name of the exposed variable. Scriptlets and other custom tags will be able to access the new variable using this name. This attribute is required.
•name: The module-relative name of the resource to load.
•input: If this attribute is present (the actual value is irrelevant), then the exposed variable is of type InputStream; otherwise it’s a String.
Examples
Frankly, it’s difficult to see how this tag can be useful, unless you’re using some other custom tags that can read and parse the InputStream. Here’s an example using a hypothetical RSS source (/myRss.xml, which contains RSS markup) and a hypothetical <rss> custom tag to parse and display the output:
<!-- display the RSS data as HTML: --> <rss:write name="rssSrc" />
Equivalents
The closest equivalent is JSTL’s <c:import>, which calls a URL and exposes the received data as either a String or a Reader. The previous example can easily be translated using JSTL:
This tag exposes the size of a given Collection or Map or array as a variable (of type Integer) that may be accessed with scriptlets or custom tags.
Usage Restrictions
The id attribute is required, and you must specify the array/Collection/Map whose size you want measured, using either the collection attribute or a name/property/scope combination.
432
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
Attributes
•id: The name of the exposed variable. Scriptlets and other custom tags will be able to access the new variable using this name. This attribute is required.
•name/property/scope: These attributes are used to locate the Collection/Map/array, with the given name and optional property and scope. If scope isn’t specified, all scopes are searched for the named object.
•collection: This is a very handy alternative to the name/property/scope combination. You use a scriptlet to calculate the value of this attribute, for example:
Remember to declare the JSTL function tag library.
struts
This tag exposes a Struts global forward, or form bean or form handler (the ActionMapping for the form handler) as a variable, accessible to scriptlets and other tags. This can be useful if you want JSTL to access Struts’ internal variables.
Usage Restrictions
The id attribute is required. You must also specify the forward, formBean, or mapping attribute.
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
433
Attributes
•id: The name of the exposed variable. Scriptlets and other custom tags will be able to access the new variable using this name. This attribute is required.
•forward: The name of the global forward to expose.
•formBean: The name of the declared form bean to expose.
This tag writes the specified bean property to the response stream. It allows for some formatting of the given bean property.
Usage Restrictions
The name attribute is required.
Attributes
•name/property/scope: These attributes are used to locate the JavaBean with the given name and optional property and scope. If scope isn’t specified, all scopes are searched for the named object.
•ignore: If true, silently fails if the named JavaBean is not found. The default value (false) causes an exception to be thrown.
The remaining attributes are used to format the bean’s property:
•filter: If set to true causes the property’s String value to be HTML encoded. For example, the ampersand (&) would be encoded as & and > would be encoded as >. The default is true.
•format/formatKey: Both specify a format string that is used to format the bean’s property. format uses its value literally as a format string. formatKey uses its value as a key to look up the actual format string stored in the message resources file. Unless the locale/bundle combination is specified, the current user’s locale and the default message resource bundle is used.
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
435
•locale/bundle: These attributes are used to specify a different Locale object or message resource file. locale specifies a key that can be used to look up the Locale object stored on the current session. The bundle attribute is explained in more detail in the entry for <bean:message>.You’d use these in conjunction with formatKey to specify a locale different from the current user’s locale or a message resource file different from the default one.
JSTL’s Formatting tag library has numerous variations on formatting strings, dates, currencies, and numbers. You should consult the latest specification if you’re interested in learning more.
Lastly, the <s:write> tag from the Struts-Faces integration library is yet another equivalent.
436
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
The Logic Tag Library
The Logic tag library provides tags for conditional processing, looping, and flow control.
•Conditional processing: equal/notEqual, empty/notEmpty, greaterEqual/lessEqual/ greaterThan/lessThan, match/notMatch, messagesPresent/messagesNotPresent and present/notPresent.
•Looping: The iterate tag.
•Flow control: The forward and redirect tags.
All of these tags, except the ones that involve flow control, have JSTL equivalents, so you should use the JSTL versions if you can.
Common Attribute Sets
There are two common attribute sets for the Logic tag library. The first, which we’ll call the Base Object attribute set (or base-attrsfor short) is illustrated in Table C-11, and pertains to the JavaBean object that the corresponding tags apply to.
Table C-11.The base-attrs Attribute Set
Attribute Name
Usage
name
The name of the base object. If this is omitted, then the implicit base object
(if any) is used. If the tag is enclosed in an <html:form>, the implicit base
object is the form bean associated with the form.
property
The property on the base object, whose value is used in the functioning of
the tag. For example, if the tag were a comparison tag, then the value of
property on the base object is used in the comparison. This assumes a corre-
sponding getXXX() function on the base object.
scope
The scope on which to search for the object given by the name property.
If scope is undeclared, then all scopes are searched for the object specified
by the name property. The valid scopes are page, request, session, and
application.
Some tags allow you to use values from other sources (that is, other than the property on the base object) in order to do their job. These Extended Property attributes (expropattrs) are listed in Table C-12.
A P P E N D I X C ■ S T R U T S T A G R E F E R E N C E
437
Table C-12.The exprop-attrs Atribute Set
Attribute Name
Usage
cookie
The name of the cookie to use.
header
The name of the HTTP request header variable to use. The name match is
case insensitive.
parameter
The name of the URL request parameter to use. If there are more than one, the
first one that occurs is used.
Selector Attributes
Many tags in the Logic library use selector attributes. These attributes are used to select the object or property with which to perform that tag’s function. The selector attributes are cookie, header, name/property, and parameter.
Struts interrogates these attributes in this sequence. For example, if you specify both cookie and parameter, only the cookie attribute is used to perform the tag’s task.
Note that the name/property attributes are considered a pair in this respect. That is, if you specify the name, you may optionally specify the property as well. You cannot specify just the property alone—you must specify the name as well, if they function as a selector attribute. The reference for each tag will tell you if this is the case or not.
Struts-EL Tags for the Logic Tag Library
Only the following tags in the Logic library have EL-enabled versions: forward, iterate, match/notMatch, messagesPresent/messagesNotPresent, present/notPresent, and redirect. Other tags have simpler JSTL equivalents.
■Note EL-enabled tags are those that allow you to use EL expressions. Refer to Chapter 10 for examples.
empty/notEmpty
empty conditionally executes its body if the specified property (or base object) is null, a zero-length String, or an empty Collection or Map. If the property attribute isn’t specified, then the test is run against the base object given by the name attribute.
notEmpty is the converse of empty.
Usage Restrictions
The name attribute must be specified, even if nested within an <html:form>.
