The tag will set it's value using the first non-null result from the following list:
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.
]]>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:
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 follow:
<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 fist look for resources named:
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..
]]>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.
]]>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.
]]><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:
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.
]]>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:
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.
]]>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.
]]>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:
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.
]]>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.
]]>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:
For example for a class com.myco.Gender supplied to the options-collection tag with label="key" and value="description", when rendering for an instance Gender[key="M", description="Male"] the following localized properites will be looked for:
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 collection, value and label) 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-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.
]]>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:
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.
]]>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 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.
]]>The tag will set it's value using the first non-null result from the following list:
The tag will set it's value using the first non-null result from the following list:
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.
]]>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 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.
]]>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.
]]>