Stripes Tag Library


Standard Syntax:
     <%@ taglib prefix="stripes" uri="http://stripes.sourceforge.net/stripes.tld" %>

XML Syntax:
     <anyxmlelement xmlns:stripes="http://stripes.sourceforge.net/stripes.tld" />

        Provides tags for use with the Stripes presentation framework.  There are three main
        groups of tags in this tag library.  First come the HTML form tags.  These include
        the form tag itself as well as tags for most of the input tag variants.  The second
        is a set of tags for output error information, including 'errors', 'individual-error'
        and others.  Last is a set of utility tags.  These include the wizard-fields tag which
        can write out hidden fields for values in the request, the useActionBean tag to use
        ActionBeans as view helpers and the link tags for generating links similar to forms.
    

Tag Library Information
Display NameStripes Tag Library
Version1.0
Short Namestripes
URIhttp://stripes.sourceforge.net/stripes.tld
 

Tag Summary
button

Tag that generates HTML form fields of type <input type="button" ... /> which render buttons for submitting forms. The only capability offered above and beyond a pure html tag is the ability to lookup the value of the button (i.e. the text on the button that the user sees) from a localized resource bundle.

The tag will set its value using the first non-null result from the following list:

  • resource: {actionFQN}.{buttonName}
  • resource: {actionPath}.{buttonName} (deprecated)
  • resource: {buttonName}
  • the body of the tag
  • the value attribute of the tag
checkbox

Implements an HTML tag that generates form fields of type <input type=" checkbox"/>. Since a single checkbox widget on a HTML page can have only a single value, the value tag attribute must always resolve to a scalar value which will be converted to a String using the Stripes Formatting system, or by caling toString() if an appropriate Formatter is not found.

Checkboxes are commonly used in two ways. The first and simplest case uses a single checkbox to set a boolean or Boolean value on the ActionBean. To do this use the following syntax:

<stripes:checkbox name="likesChocolate"/>

When the value attribute is omitted, as above, the checkbox defaults to the simple behaviour of sending "true" to the server when checked and nothing to the server when unchecked. For this reason it is best to use boolean values, or Boolean values initialized to Boolean.FALSE.

The other common usage is to use checkboxes in a manner similar to a multi-select. For example:

<stripes:checkbox name="likes" value="chocolate"/>
<stripes:checkbox name="likes" value="marshmallows"/>
<stripes:checkbox name="likes" value="ice cream"/>

In this case there are multiple checkboxes each with the same name, but different values. A value is submitted to the server for each checked checkbox, and normally bound to an array or List property on the ActionBean.

Checkboxes perform automatic (re-)population of state. They prefer, in order, values in the HttpServletRequest, values in the ActionBean and lastly values set using checked="" on the page. The "checked" attribute is a complex attribute and may be a Collection, an Array or a scalar Java Object. In the first two cases a check is performed to see if the value in the value="foo" attribute is one of the elements in the checked collection or array. In the last case, the value is matched directly against the String form of the checked attribute. If in any case a checkbox's value matches then a checked="checked" attribute will be added to the HTML written.

The tag may include a body and if present the body is converted to a String and overrides the checked tag attribute.

errors

The errors tag has two modes, one where it displays all validation errors in a list and a second mode when there is a single enclosed field-error tag that has no name attribute in which case this tag iterates over the body, displaying each error in turn in place of the field-error tag.

In the first mode, where the default output is used, it is possible to change the output for the entire application using a set of resources in the error messages bundle (StripesResources.properties unless you have configured another). If the properties are undefined, the tag will output the text "Validation Errors" in a div with css class errorHeader, then output an unordered list of error messages. The following four resource strings (shown with their default values) can be modified to create different default ouput:

  • stripes.errors.header=<div class="errorHeader">Validation Errors</div><ul>
  • stripes.errors.footer=</ul>
  • stripes.errors.beforeError=<li>
  • stripes.errors.afterError=</li>

The second mode allows customization of the output for a specific page by nesting the following tag inside the errors tag: <stripes:individual-error>, <stripes:error-header> and <stripes:error-footer>. An example, re-creating the default output using this technique follows:

<stripes:errors>
     <stripes:errors-header><div class="errorHeader">Validation Errors</div><ul></stripes:errors-header>
     <li><stripes:individual-error/></li>
     <stripes:errors-footer></ul></stripes:errors-footer>
</stripes:errors>

The errors tag can be used to display errors for a single field by supplying it with a 'field' attribute which matches the name of a field on the page. In this case the tag will display only if errors exist for the named field. In this mode the tag will first look for resources named:

  • stripes.fieldErrors.header
  • stripes.fieldErrors.footer
  • stripes.fieldErrors.beforeError
  • stripes.fieldErrors.afterError

If the fieldErrors resources cannot be found, the tag will default to using the sames resources and defaults as when displaying for all fields.

Similar to the above, field specific, manner of display the errors tag can also be used to output only errors not associated with a field, i.e. global errors. This is done by setting the globalErrorsOnly attribute to true.

This tag has several ways of being attached to the errors of a specific action request. If the tag is inside a form tag, it will display only errors that are associated with that form. If supplied with an 'action' attribute, it will display errors only errors associated with a request to that URL. Finally, if neither is the case, it will display errors associated with the action bean for the current request.

errors-footer Tag contents are displayed only when showing the last row of an errors tag.
errors-header Tag contents are displayed only when showing the first row of an errors tag.
file

Tag that generates HTML form fields of type <input type="file" ... />. The only functionality provided above and beyond a straight HTML input tag is that the tag will find its enclosing form tag and ensure that the for is set to POST instead of GET, and that the encoding type of the form is properly set to multipart/form-data as both these settings are necessary to correctly perform file uploads.

Does not perform repopulation because default values for <input type="file"/> are not allowed by the HTML specification. One can only imagine this is because a malicous page author could steal a user's files by defaulting the value and using JavaScript to auto-submit forms! As a result the tag does not accept a body because it would have no use for any generated content.

form Stripes' HTML form tag. Provides a standard HTML form tag interface, but allows other stripes input tags to re-populate their values. Also includes a hidden field in the form for the page name that the form is being rendered on (to allow forwarding to the same page in the case of a validation error.
hidden

Generates one or more <input type="hidden" ... /> HTML tags based on the value supplied. The hidden tag assigns the value attribute by scanning in the following order:

  • for one or more values with the same name in the HttpServletRequest
  • for a field on the ActionBean with the same name (if a bean instance is present)
  • by collapsing the body content to a String, if a body is present
  • referring to the result of the EL expression contained in the value attribute of the tag.

The result of this scan can produce either a Collection, an Array or any other Object. In the first two cases the tag will output an HTML hidden form field tag for each value in the Collection or Array. In all other cases the Object is toString()'d (unless it is null) and a single hidden field will be written.

image

Tag that generates an image input button for use in HTML forms, e.g:

<input name="foo" type="image" src="/app/foo.gif" alt="foo"/>

Provides a couple of facilities above and beyond using the plain HTML tag. The main advantage is a localization capability. The tag looks in the Stripes Field Name message bundle for resources to be used as the src URL for the image and the alt text of the image. In order it will look for and use:

  • resource: actionFQN.inputName.[src|alt]
  • resource: actionPath.inputName.[src|alt] (deprecated)
  • resource: inputName.[src|alt]
  • tag attributes: src and alt

If localized values exist these are preferred over the values specified directly on the tag.

Additionally if the 'src' URL (whether acquired from the tag attribute or the resource bundle) starts with a slash, the tag will prepend the context path of the web application.

individual-error Placeholder tag that is to be used only inside of a errors tag. When nested inside an errors tag, causes the errors tag to operate as an iterator, outputting its body for each error present, placing the text of the error where the individual-error tag is found.
label

Label tag that can look up localized field labels and render differently when the labelled field is in error. While the label field is usually used to generated form field labels, it can be used to generate HTML label tags with arbitrary localized or non-localized values.

It is important to understand the relationship between the name and for attributes of the stripes:label tag. The for attribute is used directly to generated the for attribute of the generated HTML label tag, and as such should correspond to the HTML id attribute of the input tag for which it is a label. If the name attribute is omitted then the value of the for attribute will also be used as the name attribute.

The value of the label is set by searching for a non-null value in the following order:

  • resource: {actionFQN}.{name}
  • resource: {actionPath}.{name} (deprecated)
  • resource: {name}
  • The body of the label tag
  • A warning message telling you to supply a label value somewhere!

In the case of indexed or mapped form fields (e.g. foo[3].bar) the indexing and mapping will be removed from the name prior to using it to lookup labels (e.g. foo.bar). This is done to remain consistent with the way field names are looked up for error messages.

It should be noted that in cases where a form field and HTML control are one-to-one (e.g. text, password, select) the name of the label will usually equal the name of the control. However, this need not be the case. You may use any value for the name of the label, but the label will only perform error rendering correctly if the name is equal to the name of the form field being labelled. To illustrate this point consider the following example:

<th>
    <stripes:label for="bug.status"/>:
</th>
<td>
    <c:forEach var="status" items="<%=Status.values()%>">
        <stripes:radio id="bug.status.${stripes:enumName(status)}"
                       name="bug.status"
                       value="${stripes:enumName(status)}"/>
        <stripes:label for="bug.status.${stripes:enumName(status)}">
            ${stripes:enumName(status)}
        </stripes:label>
    </c:forEach>
</td>

The above example uses one label tag at the top (with for="bug.status") that labels a row in the table and will display differently when the bug.status field is in error. It then employs a label tag for each radio button. These are bound to the individual radio buttons (clicking on the label will select the appropriate radio button), and default to the name of the enum value if a localized name isn't found. Since these labels do not match the field name exactly, they will not render differently when the field is in error.

link

Tag that generates HTML links, used for linking to pages and ActionBean events within a Stripes application. Works in concert with zero or more nested param tags in order to allow addition of arbitrary parameters to any URL. The body of the tag, minus any param tags, is trimmed for whitespace at either end, and is then used as the contents of the link body.

There are two attributes which are not a mirrors of attributes on the HTML anchor tag. The first is the 'event' attribute. This allows specification of a specific event to trigger when linking to an ActionBean URL. The second is 'beanclass' which allows the specification of the class name or Class instance for an ActionBean as an alternative to specifying the 'href' attribute.

messages

Displays a list of non-error messages to the user. The list of messages can come from either the request (preferred) or the session (checked 2nd). Lists of messages can be stored under any arbitrary key in request or session and the key can be specified to the messages tag. If no key is specified then the default key (and therefore default set of messages) is used. Note that by default the ActionBeanContext stores messages in a flash scope which causes them to be exposed as request attributes in both the current and subsequent requests (assuming a redirect is used).

While similar in concept to the ErrorsTag, the MessagesTag is significantly simpler. It deals with a List of Message objects, and does not understand any association between messages and form fields, or even between messages and forms. It is designed to be used to show arbitrary messages to the user, the prime example being a confirmation message displayed on the subsequent page following an action.

The messages tag outputs a header before the messages, the messages themselves, and a footer after the messages. Default values are set for each of these four items. Different values can be specified in the error messages resource bundle (StripesResources.properties unless you have configured another). The default configuration would look like this:

  • stripes.messages.header=<ul class="messages">
  • stripes.messages.footer=</ul>
  • stripes.messages.beforeMessage=<li>
  • stripes.messages.afterMessage=</li>

It should also be noted that while the errors tag supports custom headers and footers through the use of nested tags, the messages tag does not support this. In fact the messages tag does not support body content at all - it will simply be ignored.

option

Generates an <option value="foo">Fooey</option> HTML tag. Coordinates with an enclosing select tag to determine its state (i.e. whether or not it is selected.) As a result some of the logic regarding state repopulation is a bit complex.

Since options can have only a single value per option the value attribute of the tag must be a scalar, which will be converted into a String using a Formatter if an appropriate one can be found, otherwise the toString() method will be invoked.The presence of a "selected" attribute is used as an indication that this option believes it should be selected by default - the value (as opposed to the presence) of the selected attribute is never used....

The option tag delegates to its enclosing select tag to determine whether or not it should be selected. See the stripes:select for documentation on how it determines selection status. If the select tag has no opinion on selection state (note that this is not the same as select tag deeming the option should not be selected) then the presence of the selected attribute (or lack thereof) is used to turn selection on or off.

If the option has a body then the String value of that body will be used to generate the body of the generated HTML option. If the body is empty or not present then the label attribute will be written into the body of the tag.

If the label attribute's value is used, it will be HTML-encoded before being written out. However, the tag body, if present, will not be HTML-encoded. This allows the explicit use of HTML character entities within the tag, which would be impossible otherwise. If you choose to set the tag body and you want the output to be HTML-encoded, you must use something like the escapeXml attribute of the <c:out> tag to HTML-encode the value before passing it to <stripes:option>.

options-collection

Writes a set of <option value="foo">bar</option> tags to the page based on the contents of a Collection, Iterable or Array. Each element in the collection is represented by a single option tag on the page. Uses the label and value attributes on the tag to name the properties of the objects in the Collection that should be used to generate the body of the HTML option tag and the value attribute of the HTML option tag respectively. If either (or both) of the label or value properties are ommitted the item itself will be used for the label/value instead - this is done to support collections of simple types like Strings and Numbers.

E.g. a tag declaration that looks like:

<stripes:options-collection collection="${cats}" value="catId" label="name"/>

would cause the container to look for a Collection called "cats" across the various JSP scopes and set it on the tag. The tag would then proceed to iterate through that collection calling getCatId() and getName() on each cat to produce HTML option tags.

The tag will attempt to localize the labels attributes of the option tags that are generated. To do this it will look up labels in the field resource bundle using:

  • {className}.{labelPropertyValue}
  • {packageName}.{className}.{labelPropertyValue}
  • {className}.{valuePropertyValue}
  • {packageName}.{className}.{valuePropertyValue}

For example for a class com.myco.Gender supplied to the options-collection tag with label="description" and value="key", when rendering for an instance Gender[key="M", description="Male"] the following localized properites will be looked for:

  • Gender.Male
  • com.myco.Gender.Male
  • Gender.M
  • com.myco.Gender.M

If no localized label can be found then the value of the label property will be used.

Optionally, the group attribute may be used to generate <optgroup> tags. The value of this attribute is used to retrieve the corresponding property on each object of the collection. A new optgroup will be created each time the value changes.

The rendered group may be localized by specifying one of the following properties:

  • {className}.{groupPropertyValue}
  • {packageName}.{className}.{groupPropertyValue}

All other attributes on the tag (other than collection, value, label and group) are passed directly directly through to the stripes:option tag which is used to generate the individual HTML options tags. As a result the stripes:options-collection will exhibit the same re-population/selection behaviour as the regular options tag.

Since the tag has no use for one it does not allow a body.

options-map

Writes a set of <option value="foo">bar</option> tags to the page based on the contents of a Map. Each Map.Entry in the Map is represented by a single option tag on the page. Uses the label and value attributes on the tag to name the properties of the objects in the Map.Entry that should be used to generate the body of the HTML option tag and the value attribute of the HTML option tag respectively. If either (or both) of the label or value properties are ommitted the Map.Entry value or key will be used respectively.

E.g. a tag declaration that looks like:

<stripes:options-map map="${cats}"/>

would cause the container to look for a Map called "cats" across the various JSP scopes and set it on the tag. The tag would then proceed to iterate through that Map calling getKey() and getValue() on each cat to produce HTML option tags.

The tag will attempt to localize the labels attributes of the option tags that are generated. To do this it will look up labels in the field resource bundle. If no localized label can be found then the value of the label property will be used.

All other attributes on the tag (other than map, label, and sort) are passed directly through to the stripes:option tag which is used to generate the individual HTML options tags. As a result the stripes:options-map will exhibit the same re-population/selection behaviour as the regular options tag.

Since the tag has no use for one it does not allow a body.

options-enumeration

Writes a set of <option value="foo">bar</option> tags to the page based on the values of a enum. Each value in the enum is represented by a single option tag on the page. The options will be generated in ordinal value order (i.e. the order they are declared in the enum).

The label (the value the user sees) is generated in one of three ways: by looking up a localized value, by using the property named by the 'label' tag attribute if it is supplied and lastly by toString()'ing the enumeration value. For example the following tag:

<stripes:options-enumeration enum="net.kitty.EyeColor" label="description"/>
when generating the option for the value EyeColor.BLUE will look for a label in the following order:

  • resource: EyeColor.BLUE
  • resource: net.kitty.EyeColor.BLUE
  • property: EyeColor.BLUE.getDescription() (because of the label="description" above)
  • failsafe: EyeColor.BLUE.toString()

If the class specified does not exist, or does not specify a Java 1.5 enum then a JspException will be raised.

All attributes of the tag, other than enum and label, are passed directly through to the <stripes:option/> which is used to generate the individual HTML options tags. As a result the <stripes:options-enumeration/> will exhibit the same re-population/selection behaviour as the regular options tag.

Since the tag has no use for one it does not allow a body.

param Used to add parameters to the link and url tags. If the value attribute is present it will be used. If the value attribute is not present, then the body of the tag will be used as the parameter value. The value attribute may identify either a scalar value, an Array or a Collection. In the latter two cases a URL parameter will be added per value in the Array or Collection.
password

Tag that generates HTML form fields of type <input type="password" name="foo" value="bar"/>, which can optionally re-populate their value, and provide error display/formatting consistent with the rest of the Stripes input tags. Password tags may have only a single value, whose default may be set using either the body of the tag, or using the value="" attribute of the tag. At runtime the contents of the text field are determined by looking first for a non-null body and if one is not found, then a non-null value attribute.

Repopulation of values for password tags is optional, and by default is not performed. To control this behaviour explicitly use the repopluate tag attribute.

radio

Generates <input type="radio" value="foo"/> HTML tags based on the attribute set on the tag and the state of the form. Since a single radio button widget on a HTML page can have only a single value, the value tag attribute must be a Scalar object. The value will be converted to a String using the Stripes formatting system (with appropriate defaults), or by calling toString if an appropriate Formatter does not exist. Similarly since radio button sets can have only a single selected value at a time the checked attribute of the tag must also be a scalar value.

Radio buttons perform automatic (re-)population of state. They prefer, in order, the value in the HttpServletRequest, the value in the ActionBean and lastly the value set using checked="" on the page. If the value of the current radio button matches the checked value from the preferred source then the attribute checked="checked" will be written in the HTML tag.

The tag may include a body and if present the body is converted to a String and overrides the checked tag attribute.

reset

Tag that generates HTML form fields of type <input type="reset" ... /> which render buttons for resetting forms. The only capability offered above and beyond a pure html tag is the ability to lookup the value of the button (i.e. the text on the button that the user sees) from a localized resource bundle.

The tag will set its value using the first non-null result from the following list:

  • resource: {actionFQN}.{buttonName}
  • resource: {actionPath}.{buttonName} (deprecated)
  • resource: {buttonName}
  • the body of the tag
  • the value attribute of the tag
select

Coordinates with one or more other tags to produce a well formed HTML select tag with state repopulation. The select tag itself really only writes out the basic <select> name="foo"> ... </select> piece of the structure, and provides mechanisms for child options to determine whether or not they should render themselves as selected.

submit

Tag that generates HTML form fields of type <input type="submit" ... /> which render buttons for submitting forms. The only capability offered above and beyond a pure html tag is the ability to lookup the value of the button (i.e. the text on the button that the user sees) from a localized resource bundle.

The tag will set its value using the first non-null result from the following list:

  • resource: {actionFQN}.{buttonName}
  • resource: {actionPath}.{buttonName} (deprecated)
  • resource: {buttonName}
  • the body of the tag
  • the value attribute of the tag
text

Tag that generates HTML form fields of type <input type="text" name="foo" value="bar"/>, which can dynamically re-populate their value. Text tags may have only a single value, whose default may be set using either the body of the tag, or using the value="" attribute of the tag. At runtime the contents of the text field are determined by looking for the first non-null value in the following list:

  • A value with the same name in the HttpServletRequest
  • A value on the ActionBean if an ActionBean instance is present
  • The contents of the body of the tag
  • The value attribute of the tag
textarea

Tag that generates HTML form fields of type <textarea name="foo"> ... </textarea>, which can dynamically re-populate their value. Textareas may have only a single value, whose default may be set using either the body of the textarea, or using the value="" attribute of the tag. At runtime the contents of the textarea are determined by looking for the first non-null value in the following list:

  • A value with the same name in the HttpServletRequest
  • A value on the ActionBean if an ActionBean instance is present
  • The contents of the body of the textarea
  • The value attribute of the tag
url Similar to the link tag except that the behaviour closely approximates the JSTL c:url tag. Generates a URL containing the necessary source-page and event parameters. If a 'var' attribute is specified, the generated URL will be written to that variable, otherwise it will be written into the page. Like c:url the constructed url is not encoded.
useActionBean

Puts the ActionBean with the specified binding into page context under the supplied name. If the ActionBean does not already exist, it will be instantiated and binding will be run to bind values from the HttpServletRequest onto the ActionBean. Validation will not be run, and any error messages produced from the binding/type conversion process will be discarded. The ActionBean will then be placed in request scope, just as done by the DispatcherServlet.

If the ActionBean did not previously exist, and an event is specified, the event handler will be executed on the ActionBean. If the ActionBean already existed, supplying the event attribute has no effect.

Lastly, if the var or id attribute is supplied (they are synonymous and only one should be supplied) the ActionBean is bound in to page context using the name supplied. This is true in all cases, regardless of whether the ActionBean is newly instantiated, or pre-existing. This allows the tag to be used to provide an easier name for the ActionBean than referring to it by binding.

wizard-fields

Examines the request and include hidden fields for all parameters that have do not have form fields in the current form. Will include multiple values for parameters that have them. Excludes 'special' parameters like the source page parameter, and the paramter that conveyed the event name.

Very useful for implementing basic wizard flow without relying on session scoping of ActionBeans, and without having to name all the parameters that should be carried forward in the form.

layout-definition

Defines a reusable layout. This tag is designed to wrap the entire contents of a JSP that is to be re-used to manage the layout of multiple pages. It can contain HTML, JSP content, scriptlets etc. It may also contain stripes:layout-component tags. The stripes:layout-component names a section of the layout that can be supplied during rendering (it may be empty, or have default contents).

Layout definitions will also have access to, through PageContext, any attributes/parameters supplied at rendering time. These can be referenced in the layout definition using EL, for example as ${myCustomParameter}. This allows layouts not only to templatize look and feel, but to potentially render differently based on the values of parameters passed in at rendering time.

layout-component

Used to define or supply a component of a layout. The stripes:layout-component tag can be nested inside both the stripes:layout-definition and stripes:layout-render tags. In the former case it defines a named component in the layout, and the (optional) body provides a default for the component. When nested in a stripes:layout-render tag, the body overrides the named component defined in the layout.

The vanilla case would be to have a layout which defines the header/footer etc. for your site and that has a component named "body" or "contents" or something similar, which wraps the area where page content would normally be displayed. Then, when using that layout through a stripes:layout-render tag, you would use a stripes:layout-component tag to provide a value for the "body" or "contents" component of the layout.

layout-render

Renders the named layout, supplying it with any specified parameters and overridden components. In addition to being able to supply nested stripes:layout-component tags, you may also supply any number of dynamic or arbitrary parameters to this tag. All parameters (except name) will be made available to the layout definition through the page context.

format Formats an object using Stripes' formatting facilities. If no formatter is available for the object, then toString() is called. Null values are formatted as an empty string. If a 'var' attribute is specified, the generated URL will be written to that variable, otherwise it will be written into the page.
field-metadata Creates a script section containing form field metadata.
page-options Sets options that affect how other tags in this tag library behave.
 

Function Summary
java.lang.StringenumName( java.lang.Enum) Returns the name of the supplied Java 5 enumeration value; useful since EL will only access JavaBean style properties, and the name attribute of an enum is always accessed using the function name(), not getName().
booleanhasErrors( net.sourceforge.stripes.action.ActionBean, java.lang.String) Indicates if validation errors exist for the given field of the given ActionBean. This allows for use of JSTL logic tags such as c:if and c:choose.
 


Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-3 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.