|
|||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
See:
Description
Class Summary | |
BaseFieldTag | Convenience base class for the various input tags for text fields. |
BaseHandlerTag | Base class for tags that render form elements capable of including JavaScript event handlers and/or CSS Style attributes. |
BaseInputTag | Abstract base class for the various input tags. |
BaseTag | Renders an HTML |
ButtonTag | Renders an HTML BUTTON tag within the Struts framework. |
CancelTag | Tag for input fields of type "cancel". |
CheckboxTag | Tag for input fields of type "checkbox". |
Constants | Manifest constants for this package. |
ErrorsTag | Custom tag that renders error messages if an appropriate request attribute has been created. |
FileTag | Custom tag for input fields of type "file". |
FormTag | Custom tag that represents an input form, associated with a bean whose properties correspond to the various fields of the form. |
HiddenTag | Custom tag for input fields of type "text". |
HtmlTag | Renders an HTML element with appropriate language attributes if there is a current Locale available in the user's session. |
ImageTag | Tag for input fields of type "image". |
ImgTag | Generate an IMG tag to the specified image URI. |
LinkTag | Generate a URL-encoded hyperlink to the specified URI. |
MultiboxTag | Tag for input fields of type "checkbox". |
OptionsTag | Tag for creating multiple <select> options from a collection. |
OptionTag | Tag for select options. |
PasswordTag | Custom tag for input fields of type "text". |
RadioTag | Tag for input fields of type "radio". |
ResetTag | Tag for input fields of type "reset". |
RewriteTag | Generate a URL-encoded URI as a string. |
SelectTag | Custom tag that represents an HTML select element, associated with a bean property specified by our attributes. |
SubmitTag | Tag for input fields of type "submit". |
TextareaTag | Custom tag for input fields of type "textarea". |
TextTag | Custom tag for input fields of type "text". |
The "struts-html" tag library contains JSP custom tags useful in creating dynamic HTML user interfaces, including input forms.
The tags in the Struts HTML library form a bridge between a JSP view and the other components of a Web application. Since a dynamic Web application often depends on gathering data from a user, input forms play an important role in the Struts framework. Consequently, the majority of the HTML tags involve HTML forms. Other important issues addressed by the Struts-HTML tags are error messages, hyperlinking and internationalization.
Each of these tags must be nested within a <html:form> tag.
The Struts form
tag outputs a standard HTML form tag, and also
links the input form with a JavaBean subclassed from the Struts ActionForm object
(see Javadoc). Each field in
the form should correspond to a property of the form's bean. When a field and
property correspond, the bean is first used to populate the form, and then to
store the user's input when the form is submitted to the controller servlet.
The name of the bean and its class can be specified as a property to the form tag, but
may also be omitted. If omitted, the ActionMappings
database (loaded from the
struts-config.xml
file) is consulted. If the current page is specified as
the input
property for an action
, the name of the
action
is used. The type
property for the bean is also then taken
from the configuration, via a Form Bean definition.
Here's a clip from the Struts Example configuration:
<action-mappings> <!-- Process a user logon --> <action path="/logon" type="org.apache.struts.example.LogonAction" name="logonForm" scope="request" input="/logon.jsp"> </action> < ... /> </action-mappings> <form-beans> <!-- Logon form bean --> <form-bean name="logonForm" type="org.apache.struts.example.LogonForm"/> < ... /> </form-beans> </pre>
Given this configuration, the HTML form tag for logon.jsp
will default
to using "logonForm
" as its name property and
"org.apache.struts.example.LogonForm
" as the attribute's type. This way you
can manage the namespace for your framework components from the configuration file.
If the form tag does not find the form bean in any of the scopes (page, request, session, application), it creates one using the specified type.
The Struts ActionForm
class is equipped with standard reset()
and validate()
methods, that can be used by the controller to enable
automatic data validation. See the
Users Guide for more about Form Validation. An important aspect of validation
is reporting errors to the user. This can be handled by the Struts errors
tag, which is discussed later in this document.
The form "field" tags in the Struts-HTML tag library share a common set of tag attributes that have the same meaning, no matter what field tag they are used with. These properties also accept Runtime Expressions, meaning you can set them with a scriptlet. The common attributes fall into four categories: Struts Common, HTML Navigation, Javascript, and CSS.
name | The attribute name of the ActionForm bean whose properties
are consulted when rendering the current value of this input field.
If not specified, the bean associated with the form tag we are nested
within is utilized. |
property | Name of the request parameter that will be included with this submission, set to the specified value. |
value | Value of the label to be used with this element. This value will also be submitted as the value of the specified request parameter. [Body of this tag (if any), or "Click"] |
Like Struts-Bean tags, the property attribute for the Struts-HTML tags accept simple, nested, and indexed expressions. For example, this tag:
<html:text property="mailingAddress.street"/>
corresponds to:
getMailingAddress().getStreet()
For more about using simple, nested, and indexed expressions with Struts, see the Struts-Bean Developers Guide.
onblur | Executed when this element loses input focus. |
onchange | Executed when this element loses input focus and its value has changed. |
onclick | Executed when this element receives a mouse click. |
ondblclick | Executed when this element receives a mouse - double click. |
onfocus | Executed when this element receives input focus. |
onkeydown | Executed when this element has focus and a key is depressed. |
onkeypress | Executed when this element has focus and a key is depressed and released |
onkeyup | Executed when this element has focus and a key is released |
onmousedown | Executed when this element is under the mouse pointer and a mouse button is depressed. |
onmousemove | Executed when this element is under the mouse pointer and the pointer is moved. |
onmouseout | Executed when this element was under the mouse pointer but the pointer was moved outside the element. |
onmouseover | Executed when this element was not under the mouse pointer but the pointer is moved inside the element. |
onmouseup | Executed when this element is under the mouse pointer and a mouse button is released. |
"parent" form tag only | |
onreset | Executed if the form is reset. |
onsubmit | Executed if the form is submitted. |
accesskey | The keyboard character used to move focus immediately to this element. |
tabindex | The tab order (ascending positive integers) for this element. |
style | CSS styles to be applied to this HTML element. |
styleClass | CSS stylesheet class to be applied to this HTML element. |
See the HTML Tags Reference for detailed information about the available tags in this tag library, and the complete list of valid attributes for each tag.
Aside from form processing, the Struts-HTML offers several other tags or tag properties to help with displaying error messages, maintaining hyperlinks, and with internationalizing your application.
Error handling is an important part of any application, and curing an error often involves getting the user's help. Struts provides a generalized method for communicating runtime messages to users, based on the same technology used to provide internationalization.
In a Web application, it is common to reuse the input page to display error messages. The Struts error message tag can be placed wherever you would like the messages to display. If no messages are pending, nothing is printed.
By default, the errors tag will print all pending messages. You can also specify a property when queuing a message, and then refer to that property in the errors tag. In that case, only the message for that property will be displayed. This is helpful when you would like to place the message for a field next to the actual field.
Error messages are often queued in the ActionForm validate method. Here's a snippet from the Struts Example application:
ActionErrors errors = new ActionErrors(); if ((username == null) || (username.length() < 1)) errors.add("username", new ActionError("error.username.required")); if ((password == null) || (password.length() < 1)) errors.add("password", new ActionError("error.password.required"));
This queues two error messages, one for the "username" field and another for the "password" field. To print all the messages together, simply place the error tag anywhere in your JSP.
<body bgcolor="white"> <html:errors/>
Or, you can place specific error messages at different locations
<td align="left"> <html:text property="username" size="16" maxlength="16"/> <html:errors property="username"/> </td> </tr><tr> <td align="left"> <html:text property="password" size="16" maxlength="16"/> <html:errors property="password"/> </td>
By default, the actual error message is retrieved from the application's standard message resource. This gives you a master list of the error messages used by your application, and provides for internationalization. In the code snippet, the message corresponding to "error.username.required" would be retrieved and displayed to the user at runtime.
error.username.required=<li>Username is required</li>
Most often, error messages are displayed in a particular way. To make it easy
to format your messages, you can also specific an errors.header
and errors.footer
string in your message resource. Typically, you
might want to render the messages in a different color, or set them up
to appear in an unordered list. Using the errors.header
and errors.footer
strings keeps the setup codes out of your JSP until a message actually prints.
errors.header=<h3><font color="red">Validation Error</font></h3> You must correct the following error(s) before proceeding:<UL> errors.footer=</ul><hr>
When implementing a Web application, it is usually a good idea to use relative references to other files in the same application. But in a dynamic application, the controller servlet often returns a completely different file than the one requested. (Often, the requested "file" doesn't actually exist, but represents an action for the controller to interpret.) Since relative references are resolved by the browser, they often won't work in a dynamic application.
To accommodate this, the Struts-HTML taglib provides a <base>
tag that renders an HTML
As a rule, you should place the Struts-HTML base tag in the <head> section of any JSP that uses relative references to other files.
<head> <html:base/> </head>
The Java Servlet framework has built-in support for tracking a client through a session. Sessions are a useful way to compensate for the stateless nature of HTTP. Tracking a client can be done with either cookies or URL rewriting, cookies being preferred when available. Struts offers three tags that make it easy to write "session-aware" hyperlink references:
Each of these tags will automatically apply URL rewriting, to maintain session state in the absence of cookies. The content displayed for the hyperlink will be taken from the body of the tag. The base URL for the hyperlink is calculated based on properties given with the tag.
Normally, the hyperlink or URI you specify is left unchanged. If you would like to include dynamic parameters to the hyperlink or URI, you can pass those to the tags via a JavaBean. If there may be naming conflicts, you can also specify the scope that the tag searches (request, page, session, application).
To pass a single dynamic parameter, specify the parameter's name using the
paramId
attribute. You can then specify the name of the JavaBean
holding the value using the paramName
attribute, and a particular
property using paramProperty
.
So, a tag like
<html:link paramId="target" paramName="linkParams"
paramProperty="target" paramScope="request"
>detail.html</html:link>
would correspond to something like
<A HREF="detail.html?<%=
request.getParameter("linkParams").getTarget() %>"></A>
To search all scopes (request, page, session, and application), omit paramScope
.
The paramProperty
attribute may also be omitted, so long as the
named bean identifies a value that can be converted to a String.
To pass multiple dynamic parameters, you can store them in a java.util.Map
,
and use the name of the map for the paramName
. The map must then
contain one or more paramIds
and their corresponding values. As
the Map is processed, the keys are assumed to be the names of query parameters
to be appended. The value associated with each key must be either a String or
a String array representing the parameter value(s). If a String array is specified,
more than one value for the same query parameter name will be created.
The HTML session tracking tags use several common attributes, that can be organized
into three groups, as follows. All of these attributes are not used by all three
tags (link
, rewrite
, and img
), and so
the tags using each attribute is given.
forward, href, and page | |
---|---|
forward | [ link rewrite ] - Logical name of a global ActionForward that contains the actual content-relative URI of the destination of this transfer. This hyperlink may be dynamically modified by the inclusion of query parameters, as described in the tag description. You must specify exactly one of the forward attribute, the href attribute, the linkName attribute, or the page attribute |
href | [ link rewrite ] - The URL to which this hyperlink will transfer control if activated. This hyperlink may be dynamically modified by the inclusion of query parameters, as described in the tag description. You must specify exactly one of the forward attribute, the href attribute, the linkName attribute, or the page attribute. |
page | [ link rewrite ] - The context-relative path, starting with a slash, of the image to be displayed by this tag. The rendered URL for this image will automatically prepend the context path of this web application (in the same manner as the page attribute on the link tag works), in addition to any necessary URL rewriting. You must specify either the page attribute or the src attribute. |
linkName, Target , and src | |
---|---|
linkName |
[ link ] - The anchor name to be defined within this page, so that you can reference it with intra-page hyperlinks. In other words, the value specified here will render a "name" element in the generated anchor tag. |
target | [ link img ] - The window target in which the resource requested by this hyperlink will be displayed, for example in a framed presentation. |
src | [ img ] - The URL to which this image will be transferred from This image may be dynamically modified by the inclusion of query parameters, as described in the tag description. This value will be used unmodified (other than potential URL rewriting) as the value of the "src" attribute in the rendered tag. You must specify either the page attribute or the the src attribute. |
paramId, paramName, paramProperty, paramScope | |
---|---|
paramId | [ link img ] - The name of the request parameter that will be dynamically added to the generated src URL. The corresponding value is defined by the paramName and (optional) paramProperty attributes, optionally scoped by the paramScope attribute |
paramName | [ link img ] - The name of a JSP bean that is a String containing the value for the request parameter named by paramId (if paramProperty is not specified), or a JSP bean whose property getter is called to return a String (if paramProperty is specified). The JSP bean is constrained to the bean scope specified by the paramScope property, if it is specified. |
paramProperty | [ link img ] - The name of a property of the bean specified by the paramName attribute, whose return value must be a String containing the value of the request parameter (named by the paramId attribute) that will be dynamically added to this hyperlink or src URL |
paramScope | [ link img ] - The scope within which to search for the bean specified by the paramName attribute. If not specified, all scopes are searched. |
name, property, scope |
|
---|---|
name | [ link rewrite img ] - The name of a JSP bean that contains a Map
representing the query parameters (if property is not specified),
or a JSP bean whose property getter is called to return a Map
(if property is specified). |
property | [ link rewrite img ] - The name of a property of the bean specified by
the name attribute, whose return value must be a Map
containing the query parameters to be added to the src URL. You must
specify the name attribute if you specify this attribute |
scope | [ link rewrite img ] - The scope within which to search for the bean specified by the name attribute. If not specified, all scopes are searched. |
See the HTML Tags Reference for the complete list of valid attributes for each tag..
Internationalization is automatically supported by the HTML tags where appropriate.
Errors - By default,
the text for your messages will be returned by the default message resource,
which will select the appropriate language for the user. You may also specify
another message resource using the bundle
attribute.
HTML - Renders an HTML element with language attributes extracted from the user's current Locale object, if there is one.
image and img
- Can optionally retrieve the value for its binary source and alt text from
the message resource, so that different images and/or text can be provided for
different locales. See the tag's altKey
, srcKey
, and
bundle
attributes in the HTML
Tags Reference.
See the Users Guide for more on how Struts helps you internationalize your applications.
|
|||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |