Beginning Apache Struts - From Novice To Professional (2006)
.pdf398 |
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 |
Examples
The code
<html:hidden property="clientId" />
specifies a hidden field that holds the value for the property called clientId on the current form bean.
You can also specify a value attribute like so:
<html:hidden property="command" value="update" />
Your Action subclass that reads the form data can then dispatch on the hidden value. Look at the entry for <bean:define> for another useful example.
Equivalents
JSF’s <h:inputHidden> is an equivalent for <html:hidden>, but you need to enclose it within the Struts-Faces <s:form> tag so that the associated form bean is populated with the submitted value:
<s:form ...
<!-- equivalent to html:hidden -->
<h:inputHidden id="clientId" binding="#{MyFormBean.clientId}" />
...
</s:form>
html
This tag inserts <html> and </html> tags, with language attributes from the current user’s locale.
Usage Restrictions
None—if you use it, other Struts tags should be nested within it.
Attributes
•xhtml: If set to true, causes nested Struts tags to render themselves as XHTML 1.0. (See also <html:xhtml>.)
•lang: (since Struts 1.2.0) . If set to true, puts in a lang attribute in the final <html> tag. The value is searched for in the following order: (1) The current session’s Locale,
(2) the accept-language HTTP request header, and (3) the server’s default locale. Consult an HTML reference to understand how to use HTML’s lang 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 |
399 |
Examples
Here’s how to render an XHTML 1.0–conformant page:
<html:html xhtml="true">
<!-- your Struts tags here -->
...
</html:html>
Equivalents
The <s:html> tag from the Struts-Faces integration library is an equivalent.
image
This tag renders an HTML image input field. Clicking on the displayed image causes the containing form to be submitted.
Usage Restrictions
This tag must be inside an <html:form> tag. You need to specify src, srcKey, page, or pageKey.
Attributes
The first four common attribute sets (evt-attrs, acc-attrs, ren-attrs, and struts-attrs) are accepted, and have their usual meanings, except for the property attribute (explained in a bit).
There are a few attributes specific to image:
•property: This specifies the function on the base object that returns a JavaBean, which has setX(int x) and setY(int y) functions, to save the (x,y) coordinate of the mouse click for the image input field. If you want to use setX() and setY() on the base object, simply use property="".
•src/srcKey/page/pageKey: You use one of these to specify the image to be used. src is the URL for the image. page is the module-relative URL for the image (and therefore, must begin with a slash). The key versions are message resource keys that point to the actual URL.
•border: The width of the border around the displayed image. The units are pixels.
•locale: Specifies a key that can be used to look up the Locale object stored on the current session. This object is used to determine the value of any keys used. If omitted, the default Struts message resource file is used.
400 |
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 |
Examples
The code that follows shows an image input field in your JSP:
<html:form ...>
<html:image page="/myMapImage.jpg" property="" /> </html:form>
The ActionForm subclass might be
public MapActionForm extends ActionForm{
public final int UNKNOWN = Integer.MAX_VALUE; protected int _x , _y;
public int getX(){ return _x; } public void setX(int x){ _x = x; }
public int getY(){ return _y; } public void setY(int y){ _y = y; }
public void reset(ActionMapping mapping, HttpServletRequest request){
_x = _y = UNKNOWN;
}
}
Equivalents
None.
img
This tag renders an HTML <img>.
Usage Restrictions
You must specify one of these attributes: action, module or src/srcKey, or page/pageKey.
Attributes
The first three common attribute sets are accepted: evt-attrs, acc-attrs, and ren-attrs. Besides these, there are a few attributes specific to img:
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 |
401 |
•action, module or src/srcKey, or page/pageKey: Used to locate the image to display. The first action/module pair specifies a form handler. The action, of course, must begin with a slash, and if you want to specify a module use the module attribute. src is the URL for the image. page is the module-relative URL for the image (and therefore, must begin with a slash). The key versions are message resource keys that point to the actual URL. They are very useful to display localized images.
•border: Specifies the width of the border around the displayed image. The units are pixels.
•locale/bundle: These 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>.
•align: Specifies the alignment of the image relative to surrounding text. This is a standard HTML attribute for the <img> element. Valid values are left, right, top, texttop, bottom, absbottom, middle, and absmiddle. Consult an HTML reference to understand what these settings do.
•height/width: Specifies the height and width of the finally displayed image in pixels. The resizing of the image is done by the browser.
•hspace/vspace: The amount of horizontal space (hspace) and vertical space (vspace) between the image and surrounding elements. The units are pixels.
•imageName: Renders a name attribute in the <img> tag: name=<imageName>. Used for scripting.
•ismap: This boolean attribute is the counterpart of the ismap attribute of HTML’s <img> tag. It’s used to indicate a server-side image map—which is used only for ancient web browsers that don’t understand the HTML <map> element. For this reason, you are extremely unlikely to use ismap.
•usemap: The name of the HTML <map> element to use. This turns the image into a clickable image map. Refer to an HTML reference on how to create a <map>. The browser’s behavior when the user clicks the image is entirely processed on the client. No server-side processing is involved. If you want to pass mouse click positions to server-side code, use <html:image> instead.
402 |
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 |
•paramName,paramProperty,paramScope and paramId: You use these to create a single request parameter. The request parameter is appended to the final URL for the image. The first set of three attributes is used to locate a single object on the current request or session. This object’s toString() is the single parameter value. The name of the parameter is given by paramId.
•name/property/scope: You use these to create multiple request parameters. The request parameters are appended to the final URL for the image. These attributes are used to locate an object of type java.util.Map. The Map’s keys are the parameter names, and the corresponding values are the parameter values. If you specify property, you must also specify name.
•useLocalEncoding: If set to true, tells Struts to use whatever the character encoding is for the current HttpServletResponse.
Examples
Here’s how to render a localized image:
<html:img srcKey="app.images.companylogo" />
To understand how to create single or multiple request parameters on the image’s URL, refer to the entry for <html:link>.
Equivalents
JSF’s <h:graphicImage> is an equivalent.
javascript
This tag causes the generation of JavaScript for client-side validation. This tag is very closely tied to the Validator framework.
Usage Restrictions
Using this tag only makes sense when it’s accompanying an <html:form>, since the generated JavaScript is used for client-side form validations. The JavaScript code is autogenerated by the Validator framework. Therefore, your ActionForm subclasses must be subclasses of ValidatorForm as well in order for this tag to work.
Attributes
The most common use of this tag is without any attributes defined. However, you can customize the generated JavaScript a little by using the following attributes:
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 |
403 |
•bundle: Specifies a message resource bundle (see Table C-8) to use in generating error messages. This attribute was added in Struts 1.2.7. See also the entry for
<bean:message>.
•htmlComment: If set to true, enclose the JavaScript with HTML comment delimiters (<!-- and -->). This is needed to prevent very old browsers from rendering JavaScript on to the page. This setting is ignored if you’ve used <html:xhtml> or <html:html xhtml="true">. The default is true.
•cdata: If cdata="true", and if you’ve used <html:xhtml> or <html:html xhtml="true">, the generated JavaScript is enclosed by XML’s CDATA[...] delimiter.
•method: Specifies a different prefix for the names of the autogenerated JavaScript. Use this attribute to prevent name clashes between your own JavaScript and the Struts-generated JavaScript code.
•scriptLanguage: If set to false, omits the language attribute in the generated
<script> tag.
•staticJavascript/dynamicJavascript: Both of these take boolean values. staticJavascript (default is true) specifies whether the static JavaScript code from the Validator framework needs to be pasted into the page. Similarly, dynamicJavascript (the default is true) specifies if the dynamic JavaScript code generated for the form should be pasted into the page. Ordinarily, you’d leave out both these attributes.
•src: This puts an HTML src attribute into the rendered <script> tag. You’d use this to specify your own JavaScript files you want loaded when the page is displayed by the browser.
•page/formName: The Validator framework allows you to create multipage validations (this topic is not covered in this book). This feature is useful in creating multipage wizards that simplify filling in complex data. Typically, the user is presented with one subform at a time, each with “next” and “back” buttons. The page attribute is the number of the current page, and the formName attribute is the name of the form bean.
Examples
The most common usage is to require that all validations be made. You do this by specifying no attributes:
<html:javascript />
This would work if pasted anywhere on the page.
404 |
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 |
Equivalents
The <s:javascript> tag from the Struts-Faces integration library is an equivalent.
link
This tag renders an HTML link.
Usage Restrictions
You must specify either action/module, href, page, forward, or linkName.
Attributes
The first three common attribute sets are accepted: evt-attrs, acc-attrs, and ren-attrs. Besides these, there are a few attributes specific to link:
•action/module, href, page, forward, linkName: Used to specify a URL for the link. The action/module pair specifies a form handler. The action, of course, must begin with a slash, and if you want to specify a module, use the module attribute. href is the URL for the link. page is the module-relative URL for the link (and therefore must begin with a slash). forward is the name of a global forward. linkName is the name of another link on the same page. The URL for that link is used for this one.
•anchor: An optional HTML anchor for the link.
•bundle: Used to specify a different message resource file. The bundle attribute is explained in more detail in the entry for <bean:message>.
•transaction: If true, appends the current transaction token to the link’s URL as a request parameter. Refer to the entry for <logic:present> for details on transaction tokens.
•paramName,paramProperty,paramScope and paramId: You use these to create a single request parameter. The request parameter is appended to the final URL for the link. The first set of three attributes is used to locate a single object on the current request or session. This object’s toString() is the single parameter value. The name of the parameter is given by paramId.
•name/property/scope: You use these to create multiple request parameters. The request parameters are appended to the final URL for the link. These attributes are used to locate an object of type java.util.Map. The Map’s keys are the parameter names, and the corresponding values are the parameter values. If you specify property, you must also specify name.
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 |
405 |
•useLocalEncoding: If set to true tells Struts to use whatever the character encoding is for the current HttpServletResponse.
Examples
Here’s a simple example using a global forward:
<html:link forward="success" />
The rendered link will have the true location for the success global forward. You can also include request parameters for the link:
<html:link page="/mypage.jsp" paramName="myRequestValue" paramId="action" />
This snippet will render a link with a request parameter named action, whose value is given by the value of toString() called on the bean myRequestValue.
Here’s how you’d create multiple request parameters:
<html:link href="http://www.kenyir.org/index.jsp" name="myMap"/>
Equivalents
The <s:commandLink> tag from the Struts-Faces integration library is an equivalent. You may also use JSF’s <h:commandLink>, but you lose the ability to use global forwards and form handlers.
messages
messages is an iterator for error messages and messages—please refer to the entry for <logic:messagesPresent> for an explanation of these two terms. By default, <html:messages> is an iterator over error messages, but you can iterate over messages by setting the messages attribute to true.
By itself, <html:messages> does not print out either error messages or messages. You have to nest a suitable tag within it (e.g., <bean:write>) to do this.
Usage Restrictions
The id attribute is required.
Attributes
•id: This behaves just like the id attribute of <logic:iterate>—it exposes a variable that refers to a single message.
•message: A boolean attribute that indicates whether to iterate over error messages (false, or omitted) or messages (true).
406 |
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 |
•property: The key with which to retrieve messages. Note that there might be more than one message saved under the same property. If property isn’t specified, then all messages are displayed. This trick is very useful for debugging.
•name: The name of the object that holds messages. Do not specify this attribute if you wish to use Action’s saveErrors() or saveMessages().
•header/footer: Both are message resource keys to text that will be rendered at the start and end of the iteration. This happens only when there is more than one error message to be displayed. Refer to the entry for <html:errors> for details.
•locale/bundle: These 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 attributes to specify a locale different from the current user’s locale or a message resource file different from the default one.
Examples
Here’s a simple example that displays all error messages:
<html:messages id="anError"> <bean:write name="anError" />
</html:messages>
Remember, error messages are present either from simple validation failure (see Chapter 6) or registered using Action’s saveErrors() (see Chapter 7).
Here’s how to display messages:
<html:messages id="aMessage" message="true"> <bean:write name="aMessage" />
</html:messages>
Messages are created in exactly the same way as error messages, but are registered using Action’s saveMessages(), which has the same signature as saveErrors().
Here’s how to display a header and footer (if there are any error messages to display):
<html:messages id="anError" header="err.header" footer="err.footer"> <bean:write name="anError" />
</html:messages>
This assumes that the message resource keys err.footer and err.header have been defined in your Application.properties file:
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 |
407 |
err.header=<b>
err.footer=</b>
So the HTML bold tag (<b>) is printed at the start and end of the iteration.
Equivalents
There are none, but it’s easy to create an ugly hack: Error messages are stored under the key Globals.ERROR_KEY and messages are stored under Globals.MESSAGE_KEY. Both are stored on the request. Globals is a Struts class (org.apache.struts.Globals) that contains various constants. The stored object is either an ActionMessages or ActionErrors instance. You can easily create a reference to this object using JSTL’s <c:set>, and use the defined messages object in the page.
multibox
This tag renders one or more check box input fields, based on an underlying array. See also <html:checkbox>. Note, however, that unlike <html:checkbox>, the corre-
sponding property on the ActionForm need not be a boolean. Any type of array will do.
Usage Restrictions
This tag must be inside an <html:form> tag. The property attribute is required.
Attributes
All common attribute sets (evt-attrs, acc-attrs, ren-attrs, struts-attrs, init-attr, and the new err-attrs) are accepted, and have their usual meanings.
A few important points to note:
•The return value can be specified either by the value attribute or the content nested in the body of the tag.
•To use this tag, you’d usually nest it within a <logic:iterate> (or any other compatible looping construct like JSTL’s <c:forEach>), and use scriptlets or the EL-enabled version of this tag to dynamically set the value attribute (if you need to nest the content instead, then you must use scriptlets).
•The values are submitted only if a check box is checked. This means that in order to detect a cleared check box, you’d need to set the underlying array to a zero-length array. See the following examples for more on this.