Beginning Apache Struts - From Novice To Professional (2006)

button

<html:button> represents an HTML button. By itself, an <html:button> does nothing— it does not submit the form, for example. You have to use one (or more) of the eventhandling atttibutes (see evt-attrs) to activate some JavaScript in order to do anything interesting.

■Note Despite what the current Apache Struts online documents say, the value of the button is not sent as

a URL parameter.

If you want to display a button defined by a graphic, then use <html:image> instead.

Usage Restrictions

This tag must be inside an <html:form> tag. You must specify the property attribute.

Attributes

The first four attribute sets (evt-attrs, acc-attrs, ren-attrs, and struts-attrs) are accepted. The only required attribute is property. If value isn’t specified and if there is no text rendered in the body of the <html:button>, then the button text defaults to “Click”.

Examples

This snippet will render an HTML button with the text label “Click”, which calls the JavaScript function changeMode() when clicked:

<html:button onclick="changeMode(src)" property="button1" />

In this snippet, the imaginary JavaScript function might determine which button was clicked by using the test src.name == "button1".

The next example shows three buttons, all of which have the text “Click Me”. The last button uses an <html:bean> to localize its text:

<html:button property="button1" value="Click Me" /> <html:button property="button2">Click Me</html:button> <html:button property="button3">

<html:bean message="msg.click-me"/> </html:button>

Equivalents

The JSF <h:commandButton> is much more powerful, and allows you to easily link a button to a server-side function, using the action attribute:

<h:commandButton action="#{myManagedBean.myFunction}" ...

Of course, for you to use this with Struts, you need to embed it within the Strut-Faces <s:form> tag. Refer to Chapter 20 for details on <h:commandButton> and <s:form>.

cancel

This tag displays a Cancel button on a form. Clicking this button causes the enclosing form to be submitted but simple validation is bypassed. However, the execute() function of the form’s Action is called in order for the “next” page to be displayed. This means, of course, that the Action subclass must have special logic to determine if the Cancel button was clicked (see “Examples” in this section for details).

When the form data is submitted, the text appearing on the Cancel button is sent as a parameter on the request URL.

Usage Restrictions

This tag must be inside an <html:form> tag. You must not specify the property attribute. Doing so would cause the Cancel button not to be recognized as such by Struts.

Attributes

The first four attribute sets (evt-attrs, acc-attrs, ren-attrs, and struts-attrs) are accepted. However, do not specify the property attribute. If value isn’t specified and if there is no text rendered in the body of the <html:cancel>, then the button text defaults to “Cancel”.

Examples

The following example shows three buttons, all of which have the text “Cancel Me”. The last Cancel button uses an <html:bean> to localize its text:

<html:cancel value="Cancel Me" /> <html:cancel>Cancel Me</html:cancel> <html:cancel>

<html:bean message="msg.cancel-me"/> </html:cancel>

In order for you to detect a Cancel button being clicked, you’d use this code in your

Action’s execute():

public ActionForward execute(... HttpServletRequest request, ...){ if (isCancelled(request)){

//A Cancel button was pressed. Ignore form data return mapping.findForward("cancelled");

}

//normal form processing code here.

...

}

Equivalents

The JSF <h:commandButton id="cancel" type="SUBMIT"> allows you to emulate the functionality of the <html:cancel> button. Of course, to use this with Struts, you need to embed it within the Strut-Faces <s:form> tag. Refer to Chapter 20 for details on <h:commandButton> and <s:form>.

checkbox

This tag renders a single check box input field within a form. See also <html:multibox>.

Usage Restrictions

This tag must be inside an <html:form> tag. The property attribute is required. The corresponding property on the ActionForm must be a boolean.

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.

There are four important things to note:

•The corresponding property on the ActionForm subclass must be a boolean.

•The value attribute specifies the argument to put in setXXX() if the check box is checked. So, if you specify value="true" (or on or yes), then setXXX(true) is called if the check box is checked. If you use any other setting for value, then setXXX(false) is called if the check box is checked.

•The check box is rendered as checked only if value equals the return value of getXXX(). So, if value="true" (or on or yes) and getXXX() also returns true, then the check box is rendered as checked. Similarly, if value is not true (or on or yes) and getXXX() returns false, then the check box is also rendered as checked.

•The corresponding setXXX() function on the ActionForm subclass is only called if the check box is checked. This means that in order for your app to detect an unchecked check box, you need to call setXXX() in your ActionForm’s reset() function. reset() is automatically called by Struts before a form is (re)displayed, and before any setXXX() functions are called.

Examples

The code

<html:checkbox property="pregnant" />

<html:checkbox property="nonsmoker" value="false" />

renders two check box fields. The corresponding ActionForm might be

public SurveyForm extends ActionForm{ protected boolean _isPregnant, _isSmoker;

public boolean getPregnant(){ return _isPregnant; } public void setPregnant(boolean isPregnant){

_isPregnant = isPregnant;

}

public boolean getNonsmoker(){ return _isSmoker; } public void setNonsmoker(boolean isSmoker){

_isSmoker = isSmoker;

}

public boolean isSmoker(){return _isSmoker;}

public void reset(ActionMapping mapping, HttpServletRequest request){

//clear the checkboxes setPregnant(false); setNonsmoker(true);

}

... //rest of SurveyForm

The pregnant property is straightforward: If the user checks the associated check box, then that translates directly to the pregnant property.

The nonsmoker property is less obvious: The underlying property that is stored is actually the opposite of nonsmoker. This just is a convenience, but as you can see, it comes at the price of added confusion.

Attributes

•property: The key with which to retrieve the error messages. Note that there might be more than one error message saved under the same property. If property isn’t specified, then all error messages are displayed. This trick is very useful for debugging.

•locale/bundle: These attributes are used to specify a different locale object or message resource file. The 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.

•name: The name of the object that holds error messages. Do not specify this attribute if you wish to use Struts’ default error-reporting mechanism.

•prefix/suffix: Both are keys to text that will be rendered before and after each individual error message. For example, you might set

myapp.errors.prefix=<font color=red> myapp.errors.suffix=</font>

and you would use these attributes like this:

<html:errors property="email" prefix="myapp.errors.prefix" suffix="myapp.errors.suffix" />

and the error message would be displayed as

<font color=red>Wrong email format</font>

•header/footer: These attributes are similar to prefix/suffix, but they apply to the start and end of a list of error messages. This happens when more than one error message is to be displayed.

Examples

Usually, you’d place an <html:errors> near an input element like so:

<html:text name="contact" property="postcode" /> <html:errors property="postcode"/>

Usage Restrictions

The action attribute is required.

Attributes

Besides the ren-attrs attributes, form accepts the following attributes:

•action: The name of the form handler that handles processing for this form’s data. This attribute is required.

•method: The HTTP submission for this form—either POST or GET, with POST being the default.

•focus/focusIndex: focus specifies the name of the field on the form that should take focus when the form first loads. Struts autogenerates the JavaScript for this to happen. If the focus attribute isn’t specified, then no such JavaScript is autogenerated. focusIndex applies to input elements that are indexed. You can specify the index of the element that takes focus.

•enctype: Specifies the encoding used when submitting this form’s data. You only need to set this when you have an <html:file> input element in the form (see the corresponding entry for more details, or refer to Chapter 11).

•onsubmit/onreset: These are the names of JavaScript event handlers to invoke when the form is submitted or reset.

•acceptCharset: Character encodings that are valid for this form (since Struts 1.2.7). This is a standard HTML attribute.

•readonly: If true, means the form data may not be edited.

•scriptLanguage: If set to false, omits the language attribute in the generated <script> tag. This attribute is ignored if you’ve specified XHTML rendering.

•target: The name of the window to which this form’s data is submitted. This is a standard HTML attribute.

Examples

Most commonly, you’d specify the action and focus attributes:

<html:form action="MyFormHandler.do" focus="email">

Key in your email address: <html:text property="email"/>

...

</html:form>

Equivalents

The Struts-Faces <s:form> is the best replacement for <html:form>. Refer to Chapter 20 for details.

frame

Renders an HTML <frame>. The advantage of using <html:frame> is that you can use global forwards or form handlers to easily put content into your frames.

Usage Restrictions

You must specify either action/module, href, page, or forward.

Attributes

•action/module, href, page, or forward: Used to specify a URL for the frame. 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 either a relative or absolute URL. page is a module-relative URL (and therefore, must begin with a slash). forward is the name of a global forward.

•anchor: An optional HTML anchor for the link.

•paramName,paramProperty,paramScope and paramId: You use these to create a single request parameter. The request parameter is appended to the final URL. 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. Refer to <html:link> for an example.

•name/property/scope: You use these to create multiple request parameters. The request parameters are appended to the final URL. 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. Refer to <html:link> for an example.

•transaction: If true, appends the current transaction token to the URL as a request parameter. Refer to the entry for <logic:present> for details on transaction tokens.

•title/titleKey: Refer to acc-attrs for details on these.

•style/styleClass/styleId: Refer to ren-attrs for details on these.

•scrolling: Specifies if scrollbars are to be created when necessary (scrolling="auto"), or always (yes) or never (no).

•marginheight/marginwidth: Specifies the height of the top and bottom margins (marginheight) or the left and right margins (marginwidth). The units used are pixels.

•frameborder: Specifies if a border needs to be rendered (frameborder="1") or not (frameborder="0").

•frameName: The name of the rendered <frame>.

•noresize: A boolean attribute indicating if this frame can be resized (false) or if its size is fixed (true).

•longdesc: The URL to a longer description for this frame. This attribute is a standard HTML one, and you should consult an HTML reference for details.

•bundle: Allows you to select a message resource file different from the default one. The bundle attribute is explained in more detail in the entry for <bean:message>.

Examples

Here’s a page with two frames:

<%@ page contentType="text/html;charset=UTF-8" %> <%@ taglib uri="/tags/struts-html" prefix="html" %> <frameset rows="10%,*">

<html:frame action="/NavBar.do" scrolling="no" frameName="navbar" /> <html:frame page="/index.jsp" scrolling="yes" frameName="main" />

</frameset>

Equivalents

None.

hidden

This tag represents a hidden form field.

Usage Restrictions

The property attribute is required. It must be a child tag of <html:form>.

Attributes

The first five common attribute sets (evt-attrs, acc-attrs, ren-attrs, struts-attrs, and initattr) are accepted, and have their usual meanings.

Besides these, there is the write attribute, which if set to true causes the value of the hidden field to be displayed. This is useful for debugging.