UI & Form Tags

The Form Tag page gives the order of the decision. With no action attribute the current request decides the URL. With an action that is an alias in the configuration the framework asks the configuration for it (in the given or the current namespace) and builds the URL with the action extension. With an action that is not an alias in that namespace the value is used as a URL, "separating the namespace from it". The results of seven forms, each in a view rendered by the action page-misc on a first request that had no session cookie, make the rule concrete:

Observed (the form start tags, with <sid> standing for the 32-character session id):

Source: Apache Struts — Form Tag, Description

Four lessons come out of the seven lines. The action name is the whole address: there is no /g10uitags/ anywhere to write by hand, and a typo or a wrong namespace (third and fourth forms) does not fail; the tag falls back to the literal text, which becomes a relative URL, and the page works until it is served from a different path. Second, the ;jsessionid=... part exists only on the first response, before the browser has returned the session cookie, because the tag encodes the URL; once the cookie is known the URL is clean. A third consequence of the same fallback is visible in the id of the third and fourth forms: the id and name are derived from the text of the URL, so the session id ended up inside the id (save_misc_jsessionid_<sid>) and the ids of all fields in the form carry it too. Fourth, includeContext="false" drops the context path (/save-misc.action), which is right only for an application deployed as the root context; for any other path it posts to a different web application.

Any attribute that the tag library does not declare is a dynamic attribute and is written to the element. The HTML5 data-* and aria-* attributes, placeholder, required and autofocus therefore work on every tag of the library. The view below also uses focusElement, which takes the id that the tag generated for the field (<formId>_<fieldName> with dots turned into underscores), and s:head for the StrutsUtils script that runs the focus code:

Observed:

Source: Apache Struts — Form Tag, Attributes

The element also shows that required="true" on a tag is a plain HTML attribute (the browser enforces it), not the Struts notion of a required field: the label star of the xhtml theme needs requiredLabel="true", and the Core Developer Guide stresses that the two are unrelated. Lower-case spellings of the layout attributes from Struts 2.0-era documents (labelposition, requiredposition) are not recognised: they too become dynamic attributes and appear on the element (observed on <s:form labelposition="top">, which printed labelposition="top" on the form tag while the fields kept the default left layout); the attributes are labelPosition and requiredPosition.

Source: Apache Struts — Client Side Validation, requiredLabel is unrelated to the required attribute

The Tag Developers Guide explains the central rule: name is both the request parameter that the control submits and the property that fills it. <s:textfield name="book.title"/> therefore calls getBook().getTitle() for the value and, on submit, the params interceptor calls getBook().setTitle(...). The value attribute is optional; a template that needs the value reads attributes.nameValue, because the key value is not what it contains. Writing both is not wrong, but the explicit value="%{...}" hides the property, and after a failed submit the tag still shows the submitted text for a field that has a conversion error (next sections).

The Guide says "all form tags automatically assign an ID to the control": a form’s id is the action name and a control’s id is the form’s name joined to the field name. The Bookshelf views above show it: the form save_edit and the field book.title give save_edit_book_title. Labels point to that id with for, so a label click focuses the field. Two fields with the same name in one form get the same id (the view of the next sections that repeats book.genre has duplicates), which is invalid HTML; pass id explicitly when a name repeats.

Source: Apache Struts — Form Tags, ID Name Assignment

Source: Apache Struts — Form Tags, Value/Name Relationship

labelPosition on the form is propagated to every field in it and a field’s own attribute wins (the Guide marks this "Since 2.3.17"). A form with labelPosition="top" whose first field asks for a star on the left and a different separator, and whose second field overrides the position, rendered these rows in the xhtml theme:

Observed (the table rows):

Source: Apache Struts — Form Tags, Form labelposition propagation

The star came from requiredLabel="true" requiredPosition="left", and labelSeparator=" -" replaced the colon; the first field took the form’s top position (own row for the label) and the second one its own left. Without requiredLabel no star is drawn, even for a field that a validator requires: the Guide’s "Required Attribute" section says the required attribute defaults to true "only if you have client-side validation enabled, and a validator is associated with that particular field"; a form with validate="true" and a requiredstring validator for the field printed Title: without a star in the Bookshelf (the label became errorLabel after a failed submit, and nothing else changed).

Source: Apache Struts — Form Tags, Required Attribute

The Guide documents the tooltip attributes; in the xhtml and css_xhtml themes a field with tooltip="Hint" gets an icon in its label and the page gets two extra includes after the form (the domTT script and stylesheet). The tooltip attributes of the form are inherited by its fields, and a field’s own attribute wins. Observed for <s:textfield name="book.isbn" label="ISBN" tooltip="Hint"/>:

Source: Apache Struts — Form Tags, Tooltip

The static URLs are served by the framework itself from struts.ui.staticContentPath (/static), so no file has to be copied into the web application.

s:textfield accepts maxlength, size, readonly and type. The type attribute (documented as "the html5 type element to display, e.g. text, email, url") turns the tag into any text-like input: type="number", "date", "email", "url". The attributes of the HTML5 type (step, min, max, placeholder, pattern) travel as dynamic attributes. Observed, in the simple theme:

Source: Apache Struts — Textfield Tag, Attributes

A property that is not a string is written with the conversion of the current locale. In the Bookshelf the date 2001-03-15 that a user posted was printed back as 3/15/01 in the text field (observed on the English-locale JVM of the scratch Tomcat), which neither a user who typed ISO dates nor a type="date" control accepts. The fix is to format the value yourself, with s:date and its var, or with a message that holds a MessageFormat pattern; both rendered 2001-03-15 (observed):

with format.date={0,date,yyyy-MM-dd} in CatalogAction.properties. A conversion error is the opposite case: the field keeps the text that was typed (abc in the price field), which the conversion error section below shows.

Source: Apache Struts — Date Tag

s:password never writes the property back unless showPassword="true". With the default the input has no value (the first listing above), and showPassword="true" with value="hunter2" rendered value="hunter2" (observed), a choice that puts the secret into the page source and should stay off. maxlength and size work as for a text field.

Source: Apache Struts — Password Tag, Examples

s:textarea takes rows, cols, wrap, minlength, maxlength and readonly, and escapes the property that it prints as the body. Observed for rows="2" cols="20" wrap="hard" minlength="3" maxlength="200" readonly="true":

Source: Apache Struts — Textarea Tag, Attributes

s:hidden renders input type="hidden" with the property or the value. In the xhtml theme the input sits in a table row with display:none (shown above), so the table stays valid. The value is HTML-escaped like every attribute (a value of <script>alert(1)</script> & "quotes" came out with <, & and ", observed), but a hidden field is still user-editable: never use one to keep a price or a permission.

Source: Apache Struts — Hidden Tag, Examples

s:file renders input type="file" with no value; accept limits the types offered by the browser (not a check on the server) and size the width. The form must be multipart/form-data; the file upload and download page of this section covers the interceptor that reads the part.

Observed (simple theme): <input type="file" name="upload" accept="text/html,text/plain" id="save_misc_upload"/>.

Source: Apache Struts — File Tag, Examples

s:label shows a value, read-only, in the same layout as an input. In the simple theme it prints a label element; in xhtml it fills the two cells of a row with the label attribute on the left and the value on the right. The value comes from value or from the property named by name, and it is escaped:

Source: Apache Struts — Label Tag, Examples

Note that the attribute for of s:label is the HTML for of the rendered label (it ties the label to another field’s id), not a property name.

s:datetextfield is the only form tag that does not work out of the box in 7.4.0. The tag declares a mandatory format attribute (a JSP without it fails to compile with attribute [format] is mandatory for tag [datetextfield]), and its templates in the simple, xhtml and html5 themes print a notice instead of a field (observed):

The Java templates come from struts2-javatemplates-plugin, which the plugin’s page documents as a faster Java implementation of tags in the simple theme, enabled with two constants. The plugin was added to the Bookshelf (the BOM supplies its version) with the first constant, and the form carried theme="simple"; the second constant makes the theme global:

Source: Apache Struts — Javatemplates Plugin, Installation

With the plugin the tag in a theme="simple" form wrote three text inputs for day, month and year, formatted from the Date property by format; the datetime interceptor of the default stack puts the three submitted parts together: a post of __day_book.publishedOn=15, __month_book.publishedOn=03 and __year_book.publishedOn=2001 made the action’s property the date shown by the saved page as 2001-03-15 (observed). Inside an xhtml form the same tag still printed the notice, because the xhtml wrapper includes the ftl template of the simple theme, which the suffix java does not replace for that file. In plain applications the practical answer to a date field is <s:textfield type="date"> with a formatted value (shown above) and a converter on the property.

Source: Apache Struts — Datetextfield Tag

s:checkbox renders one input type="checkbox", checked when the property evaluates to true. fieldValue is the value that is posted when the box is ticked (true by default):

Observed. In the xhtml theme the label sits after the box by default (the left cell of the row is empty); with labelPosition="left" the label moves to the left cell and gets the separator:

Source: Apache Struts — Checkbox Tag, Attributes

A browser sends nothing for an unticked checkbox, so a form cannot say "the user cleared it". The Struts answer is a second, hidden field and an interceptor, and here the 7.4.0 jar differs from every guide. Getting Started shows the checkbox tag with a hidden __checkbox_... field next to the input; the Checkbox Interceptor page says the tag "automatically generates this hidden field"; and the Hidden Field Prefix section of the tag page says the tag generates it by default. In 7.4.0 the hidden field is written only when submitUnchecked="true" is set (or the constant struts.ui.checkbox.submitUnchecked is true); with the default the tag writes the input alone (see the first observed line above). The table shows what the three variants do to an action that starts with inStock set to true:

The second variant wrote <input type="hidden" id="__checkbox_save_choices_book_inStock" name="__checkbox_book.inStock" value="true" /> after the input, and the third wrote the same field as struts_checkbox_book.inStock (observed). The checkbox interceptor followed the constant (the class also has a hiddenPrefix setter) and takes the value it puts in for a missing box from uncheckedValue (false by default); the Guide calls the prefix struts_checkbox_ the "HTML5-compliant alternative" to the backward-compatible default __checkbox_. A project that keeps boolean properties therefore sets submitUnchecked on the tag, or globally:

Source: Apache Struts — Checkbox Tag, Hidden Field Prefix

Source: Apache Struts — Checkbox Interceptor, How it works

Source: Apache Struts — Getting Started, Form Tags, Struts Checkbox Tag

The interceptors page lists checkbox in defaultStack; a stack of your own that omits it never sees the helper field and leaves the property untouched.

s:radio renders one input type="radio" per element of its list, all with the same name, and checks the one whose key equals the property. The tag accepts the list forms described below (a List, a Map, a list of objects with listKey and listValue), plus listCssClass and listTitle, which are property names of the list objects, not literal values. Observed for a list of Genre objects (code and label properties) and a Map:

Source: Apache Struts — Radio Tag, Examples

The id of each button is the field id followed by the key (save_choices_book_genresf). The Getting Started tutorial prints an id with a space in it for the key not sure (gendernot sure); the key is appended without escaping, so keys with spaces give invalid ids; use code-like keys.

s:checkboxlist renders a checkbox per element of the list, all named after the property; the values that are checked are the elements of the collection property. The submitted values arrive as repeated parameters that the params interceptor puts into the List<String> property (the Checkbox Interceptor page insists that @StrutsParameter go on the setter of the collection). The tag also writes a hidden __multiselect_book.tags field, which lets the multiselect interceptor set an empty collection when nothing is ticked. Observed:

A post with book.tags=new&book.tags=rare set the list to [new, rare]; a post with only __multiselect_book.tags= set it to [], and a post with neither left the original [classic] (all observed on the sticky mapping). Two details of the template deserve a warning. The ids are numbered (-1, -2, …​), not derived from the values as for a radio. And cssClass on a checkboxlist is written next to the class that comes from listCssClass, producing a duplicated attribute (observed: class="sf" class="c" and, when listCssClass named a property that does not exist, class="" class="c"), which browsers resolve by ignoring the second; put the class on the form or on a wrapping element.

Source: Apache Struts — Checkboxlist Tag, Examples

Source: Apache Struts — Multiselect Interceptor

Source: Apache Struts — Checkbox Interceptor, Checkbox lists usage with @StrutsParameter

Source: Apache Struts — Select Tag, Examples

Two checks on the list expression came out differently from what an old tutorial suggests. First, the select tag page says that the map keys of an inline map are "typed" ('1' a char, '01' a String, "1" a String) and that a value of another type "WILL NOT MATCH". On 7.4.0 every combination that I tried selected the option: the integer keys of #{1:'One',2:'Two'} with value="1", value="'1'" and value=""1""; the string keys of #{'01':'Jan','02':'Feb'} with value="'01'"; and the keys of #{'1':'Jan','2':'Feb'} with value="'1'" and with the integer value="1" (a #{"1":...} map with "1" too); seven combinations, all with selected="selected" on the first option. The comparison is made on the text of the values, so the warning of the page is stale for select. Second, a method call inside a list expression is blocked by the allowlist that is on by default: list="catalogByGenre.keySet()" on a doubleselect stopped the page with The requested list key 'catalogByGenre.keySet()' could not be resolved as a collection/array/map/enumeration/iterator type, and listValue="value.size()" produced options with empty text (observed). Expose a getter that returns a list instead.

Source: Apache Struts — Select Tag, Examples (note on map key types)

s:select renders select with its options; the option whose value equals the property (or the value) carries selected. The attributes that matter, observed on the Bookshelf genre field:

Source: Apache Struts — Select Tag, Attributes

headerKey and headerValue add a first option; the tag descriptor says the key "must not be empty" (its own example is garbled: it names '' both as correct and as bad), yet headerKey="" rendered a normal option with an empty value, and that is the form most projects want together with a required validator so that "choose" fails validation. emptyOption adds a blank option after the header. multiple="true" adds the hidden __multiselect_... field that the multiselect interceptor uses (nothing selected then means an empty collection instead of an unchanged property).

s:optgroup is nested inside a select and adds a labelled group of options from its own list, listKey and listValue. Observed:

The groups come after the options of the select’s own list, and a group that contains the current value marks it as selected too.

Source: Apache Struts — Optgroup Tag, Examples

s:combobox is a text input with a drop-down that fills it: the user may type a value that is not in the list. The property is bound to the text input, the select has no name, and a small script copies the chosen option into the input. Observed for <s:combobox name="book.genre" list="genres"/>:

The tag takes list, listKey, listValue, headerKey, headerValue, emptyOption, size and maxlength. It writes an inline script and an inline onChange handler, which a strict Content-Security-Policy blocks; an <input list="..."> with a <datalist> written by hand is the modern replacement.

Source: Apache Struts — Combobox Tag, JSP

s:doubleselect renders two selects, the second filled from the choice made in the first, with the data in the page (no request). The first select has name and list; the second has doubleName and doubleList, in which the variable top stands for the key chosen in the first; formName must be the name of the enclosing form, because the generated script reaches the second select as document.<formName>.<id>. Observed in a browser (the Bookshelf’s two levels: genre, then title):

Choosing fantasy in the browser changed the options of the second select from Dune, Neuromancer to The Hobbit, Earthsea. With the same tag but formName="f1" in a form that was named save_combo (the default name), the script failed on load with Uncaught TypeError: Cannot read properties of undefined (reading 'save_combo_book_title'), because document.f1 does not exist: name the form with name, and give the same text to formName. The second select’s id is <formId>_<doubleName> with dots turned into underscores, and doubleValue, doubleEmptyOption, doubleHeaderKey and the double... family of presentation attributes mirror the first select’s.

Source: Apache Struts — Doubleselect Tag, Examples

These three tags build list boxes with buttons for the Bookshelf’s tag editor, all from the static scripts that the framework serves from /static (optiontransferselect.js, inputtransferselect.js, utils.js):

Observed (shortened): the left list <select name="left" size="15" id="ots" multiple="multiple">, the right list <select name="right" size="15" multiple="multiple" id="save_transfer_right">, a hidden __multiselect_left and __multiselect_right for each, the text input <input type="text" name="book.tags_input" id="its_input"/>, and a script that registers selectAllOptionsExceptSome(...) on the form’s submit event for each list. Clicking -> in a browser with sf selected on the left moved sf to the right list (classic, new, signed, rare, sf), and typing extra and clicking -> of the input transfer added extra to its list. The submitted values are plain repeated parameters, so the action receives them like a checkboxlist.

Source: Apache Struts — Optiontransferselect Tag, Examples

Source: Apache Struts — Inputtransferselect Tag, Example

Source: Apache Struts — Updownselect Tag, Examples

s:submit renders one of three elements, chosen by type: input (default, <input type="submit">), button (<button type="submit">, whose face may be HTML) and image (<input type="image"> with src). The value is the text of the button (Submit when omitted), and key takes the text from a bundle and writes the key as the name. Observed:

Source: Apache Struts — Submit Tag, Description

Four observations. The ids are sequential (save_submit_0, _2, …​) unless the button has an action or method in its name. The src of an image button is written as given, without the context path (/img/go.png), and the image button printed alt twice (once from value). A button with both action and method carries only the action: name, so the method is lost. And action and method are the two prefixes of the action mapper: the button posts a parameter named action:other or method:save, which the mapper turns into another action or another method of the same action. With the defaults a post of action:save-submit=x or method:save=x to page-basic was ignored and the form was shown again (observed); with struts.mapper.action.prefix.enabled=true and struts.enable.DynamicMethodInvocation=true (and the method listed in <allowed-methods>) the post to page-basic with action:save-submit ran save-submit and showed the saved page, and method:other ran other() (observed: the action set a marker that the saved page printed). Both constants are off for good reasons (the Submit Tag page warns that dynamic method calls are a security risk, and the wildcard mappings page of this section shows the safer pattern of one mapping per button); the form that needs several buttons maps save-* style actions and gives every button its own action name with action, or branches on the button’s name in a single method.

Source: Apache Struts — Action Mapper, Action prefix

Source: Apache Struts — Action Mapper, Method prefix

The body of a type="button" submit is passed through as written by default and is escaped only with escapeHtmlBody="true"; the escaping section below has the details.

s:reset renders <input type="reset" value="Reset"/> or, with type="button", <button type="reset" value="Clear2">Clear2</button> (observed). It has the same value, key and type handling as submit, and the TLD description of its type mentions a third value, image, which the tag page does not list.

Source: Apache Struts — Reset Tag, Description

s:token writes the hidden fields that the token and tokenSession interceptors compare; the double submit tokens and wait pages page of this section explains the interceptors, the invalid.token result and the session store. The tag itself, inside an xhtml form, produced (observed; the token values are random):

s:token name="x" writes struts.token.name=x and a field called x; the tag declares only the common attributes, and name is the one that sets the token’s name (an attribute tokenName is rejected at translation time with Attribute [tokenName] invalid for tag [token] according to TLD). Inside an xhtml form the two inputs are written directly between the table and its rows, with no tr around them (observed, and the same with theme="simple" on the tag), which is invalid HTML that browsers accept.

Source: Apache Struts — Token Tag, Description

The field tags of the xhtml and css_xhtml themes show their own field errors, keyed by the tag’s name, without any s:fielderror. Three things decide how:

Source: Apache Struts — Form Tags, Form Tag Themes

Source: Apache Struts — Form Tags, Simple theme caveats

An error row appears only when the field error is stored under the same name as the tag. The Bookshelf’s validate() adds the error under book.title, which is also the name of the textfield, so the row shows; an error added under title would show in s:fielderror but beside no field. The same rule is why a model-driven action whose validators are named model.isbn (see the validation page) shows no error beside a field called isbn.

A value that cannot be converted is not a validation message that the action wrote: the conversionError interceptor adds the field error Invalid field value for field "book.price". (from the framework’s message bundle) and remembers the submitted text, and the field tag shows that text, not the property. Observed after a post of book.price=abc and book.publishedOn=notadate in a css_xhtml form:

Source: Apache Struts — Getting Started, Form Validation

The type conversion page of this section explains the message keys (invalid.fieldvalue.<field>) that replace the default text, and the localization page shows how the same keys are translated.

s:form validate="true" in an xhtml or css_xhtml form includes /static/xhtml/validation.js and generates a function validateForm_<id> that is called from onsubmit. The page of the Core Developer Guide on client side validation marks it "deprecated since Struts 7.4.0 (WW-5694), removed in Struts 8.0.0 (WW-5696)" and the templates carry the same comment. It understands only the validators required, requiredstring, stringlength, regex, email, url, int and double. On the Bookshelf, a CatalogAction-clientform-validation.xml file with requiredstring for book.title and stringlength for book.isbn produced, in the page that the action clientform rendered after an invalid post, rules like these:

Source: Apache Struts — Client Side Validation, Pure JavaScript Client Side Validation (deprecated)

In the same experiment a plain page-client view, rendered by an action that has no validation file (the form’s action pointed at save-client, which had one), produced the function with no rules at all, and so did the view client2.jsp whose form pointed at clientform but was rendered by page-client2; the rules appeared only when the page was rendered by the action that owns the validators (here clientform, by a post that failed validation). The Guide says the code is generated "from the same validation configuration used server-side"; in 7.4.0 the validators are those of the current action. Together with the removal announced for 8.0, a new project should not use it.

The replacement is the html5 theme with struts.ui.html5.constraints=true, which derives required, minlength, maxlength, pattern, min and max from the action’s validators. The validation page of this section has the mapping table and the worked example, so only the pointer is repeated here: the browser enforces the attributes, the server validation still runs, and requiredLabel is a different thing (a star on the label; it never makes a field required).

Source: Apache Struts — Client Side Validation, HTML5 Constraint Validation

Source: Apache Struts — HTML5 Theme, Using the HTML5 Theme