Within the form tags, there are two classes of tags: the form tag itself, and all other tags, which make up the individual form elements. The behavior of the form tag is different than the elements enclosed within it.
Form Tag Themes
As explained in Themes and Templates, the HTML Tags (which includes Form Tags) are all driven by templates. Templates are grouped together to create themes. The framework bundles three themes in the distribution.
simple | Sometimes too simple | |
---|---|---|
xhtml | Extends simple | (default) |
ajax | Extends xhtml |
The predefined themes can be used "as is" or customized.
![]() | xhtml layout The xhtml theme renders out a two-column table. If a different layout is needed, do not write your own HTML. Create a new theme or utilize the simple theme. |
Simple theme caveats
The downside of using the simple theme is that it doesn't support as many of the attributes that the other themes do. For example, the label attribute does nothing in the simple theme, and the automatic display of error messages is not supported.
Common Attributes
All the form tags extend the UIBean class. This base class provides a set of common attributes, that can be grouped in to three categories: templated-related, javascript-related, and general attributes. The individual attributes are documented on each tag's reference page.
In addition to the common attributes, a special attribute exists for all form element tags: form (${parameters.form}). The form property represents the attributes used to render the form tag, such as the form's id. In a template, the form's ID can be found by calling ${parameters.form.id}.
Template-Related Attributes
Attribute | Theme | Data Types | Description |
templateDir | n/a | String | define the template directory |
theme | n/a | String | define the theme name |
template | n/a | String | define the template name |
Javascript-Related Attributes
Attribute | Theme | Data Types | Description |
onclick | simple | String | html javascript onclick attribute |
ondblclick | simple | String | html javascript ondbclick attribute |
onmousedown | simple | String | html javascript onmousedown attribute |
onmouseup | simple | String | html javascript onmouseup attribute |
onmouseover | simple | String | html javascript onmouseover attribute |
onmouseout | simple | String | html javascript onmouseout attribute |
onfocus | simple | String | html javascript onfocus attribute |
onblur | simple | String | html javascript onblur attribute |
onkeypress | simple | String | html javascript onkeypress attribute |
onkeyup | simple | String | html javascript onkeyup attribute |
onkeydown | simple | String | html javascript onkeydown attribute |
onselect | simple | String | html javascript onselect attribute |
onchange | simple | String | html javascript onchange attribute |
Tooltip Related Attributes
Attribute | Data Type | Default | Description |
tooltip | String | none | Set the tooltip of this particular component |
jsTooltipEnabled | String | false | Enable js tooltip rendering |
tooltipIcon | String | /struts/static/tooltip/tooltip.gif | The url to the tooltip icon |
tooltipDelay | String | 500 | Tooltip shows up after the specified timeout (miliseconds). A behavior similar to that of OS based tooltips. |
key | simple | String | The name of the property this input field represents. This will auto populate the name, label, and value |
General Attributes
Attribute | Theme | Data Types | Description |
cssClass | simple | String | define html class attribute |
cssStyle | simple | String | define html style attribute |
cssClass | simple | String | error class attribute |
cssStyle | simple | String | error style attribute |
title | simple | String | define html title attribute |
disabled | simple | String | define html disabled attribute |
label | xhtml | String | define label of form element |
labelPosition | xhtml | String | define label position of form element (top/left), default to left |
requiredposition | xhtml | String | define required label position of form element (left/right), default to right |
name | simple | String | Form Element's field name mapping |
required | xhtml | Boolean | add * to label (true to add false otherwise) |
tabIndex | simple | String | define html tabindex attribute |
value | simple | Object | define value of form element |
![]() | When some attributes don't apply Some tag attributes may not be utilized by all, or any, of the templates. For example, the form tag supports the tabindex attribute, but none of the themes render the tabindex. |
Value/Name Relationship
In many of the tags (except for the form tag) there is a unique relationship between the name and value attributes. The name attribute provides the name for the tag, which in turn is used as the control attribute when the form is submitted. The value submitted is bound to the name. In most cases, the name maps to a simple JavaBean property, such as "postalCode". On a submit, the value would be set to the property by calling the setPostalCode mutator.
Likewise, a form control could be populated by calling a JavaBean accessor, like getPostalCode. In the expression language, we can refer to the JavaBean property by name. An expression like "%{postalCode}" would in turn call getPostalCode.
Using Expressions to populate a form for editing
<@s.form action="updateAddress">
<@s.textfield label="Postal Code" name="postalCode" value="%{postalCode}"/>
...
</@s.form>
However, since the tags imply a relationship between the name and value, the value attribute is optional. If a value is not specified, by default, the JavaBean accessor is used instead.
Populating a form for editing, the easy way
<@s.form action="updateAddress">
<@s.textfield label="Postal Code" name="postalCode"/>
...
</@s.form>
While most attributes are exposed to the underlying templates as the same key as the attribute (${parameters.label}), the value attribute is not. Instead, it can be accessed via the nameValue key (${parameters.nameValue}). The nameValue key indicates that the value may have been generated from the name attribute rather than explicitly defined in the value attribute.
ID Name Assignment
All form tags automatically assign an ID to the control, but the ID can be overridden if needed.
Forms | The default ID is the action name. For example, "updateAddress". |
---|---|
Controls | The default ID is the form's name concatenated with the tag name. For example, "updateAddress_postalCode". |
Required Attribute
The required attribute on many UI tags defaults to true only if you have client-side validation enabled, and a validator is associated with that particular field.
Tooltip
tooltipConfig is deprecated, use individual tooltip configuration attributes instead
Every Form UI component (in xhtml / css_xhtml or any other that extends them) can have tooltips assigned to them. The Form component's tooltip related attribute, once defined, will be applied to all form UI components that are created under it unless explicitly overriden by having the Form UI component itself defined with their own tooltip attribute.
In Example 1, the textfield will inherit the tooltipDelay and tooltipIconPath attribte from its containing form. In other words, although it doesn't define a tooltipIconPath attribute, it will have that attribute inherited from its containing form.
In Example 2, the textfield will inherite both the tooltipDelay and tooltipIconPath attribute from its containing form, but the tooltipDelay attribute is overriden at the textfield itself. Hence, the textfield actually will have its tooltipIcon defined as /myImages/myIcon.gif, inherited from its containing form, and tooltipDelay defined as 5000.
Example 3, 4 and 5 show different ways of setting the tooltip configuration attribute.
Example 3: Set tooltip config through the body of the param tag
Example 4: Set tooltip config through the value attribute of the param tag
Example 5: Set tooltip config through the tooltip attributes of the component tag
<!-- Example 1: -->
<s:form
tooltipDelay="500"
tooltipIconPath="/myImages/myIcon.gif" .... >
....
<s:textfield label="Customer Name" tooltip="Enter the customer name" .... />
....
</s:form>
<!-- Example 2: -->
<s:form
tooltipDelay="500"
tooltipIconPath="/myImages/myIcon.gif" .... >
....
<s:textfield label="Address"
tooltip="Enter your address"
tooltipDelay="5000" />
....
</s:form>
<-- Example 3: -->
<s:textfield
label="Customer Name"
tooltip="One of our customer Details">
<s:param name="tooltipDelay">
500
</s:param>
<s:param name="tooltipIconPath">
/myImages/myIcon.gif
</s:param>
</s:textfield>
<-- Example 4: -->
<s:textfield
label="Customer Address"
tooltip="Enter The Customer Address" >
<s:param
name="tooltipDelay"
value="500" />
</s:textfield>
<-- Example 5: -->
<s:textfield
label="Customer Telephone Number"
tooltip="Enter customer Telephone Number"
tooltipDelay="500"
tooltipIconPath="/myImages/myIcon.gif" />
checkbox
①checkbox checkboxlist【多选】 可以一次创建多个复选框。用于生成多个check boxhtml标签 必须指定list
list 必须 指定要迭代迭代的集合。如果是map 则key成为value value成为内容
listKey 指定集合对象的那个属性作为属性key
listValue 制定集合对象的那一个属性作为选项的内容
JSP: <s:checkbox label="checkbox test" name="checkboxField1" value="aBoolean" fieldValue="true"/> Velocity: #tag( Checkbox "label=checkbox test" "name=checkboxField1" "value=aBoolean" ) Resulting HTML (simple template, aBoolean == true): <input type="checkbox" name="checkboxField1" value="true" checked="checked" />
<s:checkboxlist name="foo" list="bar"/>
combobox
![]() | Please make sure you have read the Tag Syntax document and understand how tag attribute syntax works. |
Description
Struts2的combobox标签用于生成一个文本框和一个下拉框,下拉框出现在文本框的下面,在最终提交的时候只提交文本框的输入值,下拉框用于在其选项改变时,也就是onchange事件被触发时,把自身的被选中项的值赋到文本框上。
combobox的属性分别来自文本框和下拉框:
- 来自文本框的属性:
l maxlength:单行文本框中所能容纳的最大文本长度。
l size:单行文本框自身的长度。
l readonly:单行文本框是否只读。
- 来自下拉框的属性:
l list:用于生成下拉框的集合。
l listKey:生成的选项的value属性。
l listValue:生成的选项显示的文字。
The combo box is basically an HTML INPUT of type text and HTML SELECT grouped together to give you a combo box functionality. You can place text in the INPUT control by using the SELECT control or type it in directly in the text field.
In this example, the SELECT will be populated from id=year attribute. Counter is itself an Iterator. It will span from first to last. The population is done via javascript, and requires that this tag be surrounded by a <form>.
Note that unlike the <s:select/> tag, there is no ability to define the individual <option> tags' id attribute or content separately. Each of these is simply populated from the toString() method of the list item. Presumably this is because the select box isn't intended to actually submit useful data, but to assist the user in filling out the text field.
combobox 生成一个单行文本框和下拉列表框的结合,但两个表单元素只对应一个请求参数,只有单行文本框内的值才包含请求参数,而下拉列表框只是辅助输入
list 必须 生成各个选项
maxlength 大行文本框输入字符的最大长度
readonly size 可视尺寸和只读
JSP:
<-- Example One -->
<s:bean name="struts.util.Counter" var="year">
<s:param name="first" value="text('firstBirthYear')"/>
<s:param name="last" value="2000"/>
<s:combobox label="Birth year" size="6" maxlength="4" name="birthYear" list="#year"/>
</s:bean>
<-- Example Two -->
<s:combobox
label="My Favourite Fruit"
name="myFavouriteFruit"
list="{'apple','banana','grape','pear'}"
headerKey="-1"
headerValue="--- Please Select ---"
emptyOption="true"
value="banana" />
<-- Example Two -->
<s:combobox
label="My Favourite Color"
name="myFavouriteColor"
list="#{'red':'red','green':'green','blue':'blue'}"
headerKey="-1"
headerValue="--- Please Select ---"
emptyOption="true"
value="green" />
Velocity:
#tag( ComboBox "label=Birth year" "size=6" "maxlength=4" "name=birthYear" "list=#year" )
doubleselect
<s:doubleselect label="doubleselect test1" name="menu" list="{'fruit','other'}" doubleName="dishes" doubleList="top == 'fruit' ? {'apple', 'orange'} : {'monkey', 'chicken'}" />
<s:doubleselect label="doubleselect test2" name="menu" list="#{'fruit':'Nice Fruits', 'other':'Other Dishes'}" doubleName="dishes" doubleList="top == 'fruit' ? {'apple', 'orange'} : {'monkey', 'chicken'}" />
doubleselect 比较有用 生成一个级联列表。为两个列表框设定选项
list listkey listvalue headerkeyheadervalue emptyOptionmultiple size
doubleid doublelistdoublelistkey doublelistvaluedoublesize doublenamedoublevalue
head
<head> <title>My page</title> <s:head/> </head>
head用于声称html的head 用于声称对CSS和js的引用
使用 theme="ajax"可以讲Ajax的头信息包含在页面中
file
<s:file name="anUploadFile" accept="text/*" /> <s:file name="anohterUploadFIle" accept="text/html,text/plain" />
form
<p/> <s:form ... /> <p/>
hidden
<-- example one --> <s:hidden name="foo" /> <-- example two --> <s:hidden name="foo" value="%{bar}" /> Example One Resulting HTML (if foo evaluates to bar): <input type="hidden" name="foo" value="bar" /> Example Two Resulting HTML (if getBar method of the action returns 'bar') <input type="hidden" name="foo" value="bar" />
inputtransferselect
<-- minimum configuration --> <s:inputtransferselect label="Favourite Cartoons Characters" name="cartoons" list="{'Popeye', 'He-Man', 'Spiderman'}" />
label
<s:label key="userName" />
In this example, a label is rendered. The label is retrieved from a ResourceBundle via the key attribute giving you an output of 'User Name: Ford.Prefect'. Assuming that i18n message userName corresponds to 'User Name' and the action's getUserName() method returns 'Ford.Prefect'<p/>
optiontransferselect
Description
Create a option transfer select component which is basically two <select ...> tag with buttons in the middle of them allowing options in each of the <select ...> to be moved between themselves. Will auto-select all its elements upon its containing form submision.
NOTE: The id and doubleId need not be supplied as they will generated provided that the optiontransferselect tag is being used in a form tag. The generated id and doubleId will be <form_id>_<optiontransferselect_doubleName> and <form_id>_<optiontransferselect_doubleName> respectively.
<-- minimum configuration -->
<s:optiontransferselect
label="Favourite Cartoons Characters"
name="leftSideCartoonCharacters"
list="{'Popeye', 'He-Man', 'Spiderman'}"
doubleName="rightSideCartoonCharacters"
doubleList="{'Superman', 'Mickey Mouse', 'Donald Duck'}"
/>
<-- possible configuration -->
<s:optiontransferselect
label="Favourite Cartoons Characters"
name="leftSideCartoonCharacters"
leftTitle="Left Title"
rightTitle="Right Title"
list="{'Popeye', 'He-Man', 'Spiderman'}"
multiple="true"
headerKey="headerKey"
headerValue="--- Please Select ---"
emptyOption="true"
doubleList="{'Superman', 'Mickey Mouse', 'Donald Duck'}"
doubleName="rightSideCartoonCharacters"
doubleHeaderKey="doubleHeaderKey"
doubleHeaderValue="--- Please Select ---"
doubleEmptyOption="true"
doubleMultiple="true"
/>
optgroup
经常与Struts2的select标签联用的标签还有optgroup标签,optgroup标签作为select标签的子标签,用来生成一组选项。
optgroup标签的主要属性有:
- list:用于生成下拉框选项的集合。
- listKey:生成的选项的value属性。
- listValue:生成的选项显示的文字。
- label:用于生成选项组的文本。
<s:select label="My Selection"
name="mySelection"
value="%{'POPEYE'}"
list="%{#{'SUPERMAN':'Superman', 'SPIDERMAN':'spiderman'}}">
<s:optgroup label="Adult"
list="%{#{'SOUTH_PARK':'South Park'}}" />
<s:optgroup label="Japanese"
list="%{#{'POKEMON':'pokemon','DIGIMON':'digimon','SAILORMOON':'Sailormoon'}}" />
</s:select>
password
密码框用来输入一段单行文本,但是不会明文显示,而是用掩码代替。password标签对应<input type=”password”>。
除了上面列出的各种常见通用属性,password标签还有几个其它的属性:
- maxlength:单行文本框中所能容纳的最大文本长度。
- size:单行文本框自身的长度。
- readonly:单行文本框是否只读。
- showPassword:是否显示初始值,即使显示也仍为密文显示,用掩码代替。
Struts2的password标签和HTML的<input type=”password”>标签有小小的不同,<input type=”password”>只要设置value属性就可以将value属性的值作为默认值显示;但是Struts2的password标签除了要设置value属性,还要设置showPassword属性为true。
In this example, a password control is displayed. For the label, we are calling ActionSupport's getText() to
retrieve password label from a resource bundle.<p/>
<s:password label="%{text('password')}" name="password" size="10" maxlength="15" />
radio
用来生成一系列单选框,用户只能选择其中的一个。Struts2的radio标签对应于HTML的<input type=”radio”>。
除了上面列出的各种常见通用属性,radio标签还有几个其它的属性:
- list:用于生成单选框的集合,必须配置
- listKey:生成的radio的value属性。
- listValue:生成的radio后面显示的文字。
这三个属性一定要配合使用,由list属性指定从哪个集合中获得元素,由listKey属性指定获得元素之后使用元素的哪个属性作为生成的<input type=”radio”>的value属性,由listValue属性指定生成的<input type=”radio”>后的给用户看的文字
In this example, a radio control is displayed with a list of genders. The gender list is built from attribute id=genders. The framework calls getGenders() which will return a Map. For examples using listKey and listValue attributes, see the section select tag. The default selected one will be determined (in this case) by the getMale() method in the action class which should retun a value similar to the key of the getGenters() map if that particular gender is to be selected.
<s:action name="GenderMap" var="genders"/> <s:radio label="Gender" name="male" list="#genders.genders"/>
reset
<s:reset value="Reset" />
Render an button reset:
<s:reset type="button" key="reset"/>
select
Struts2的select标签用来生成一个下拉框,用户可以选择其中的一个,当然,像HTML的<select>标签一样,通过设置multiple属性,也可以让用户同时选择其中的多个选项。
除了上面列出的各种常见通用属性,select标签还有几个其它的属性:
- list:用于生成下拉框的集合。
- listKey:生成的选项的value属性。
- listValue:生成的选项显示的文字。
- headerKey:在所有的选项前再加额外的一个选项作为其标题的value属性。
- headerValue:在所有的选项前再加额外的一个选项作为其标题的显示文字。
- emptyOption:是否在标题和真实的选项之间加一个空选项。
- multiple:用户是否可以同时选择多项。
- size:下拉框的高度,即最多可以同时显示多少个选项。
在以上的属性中,list、listKey和listValue三个属性与前面的Struts2的radio标签中的属性是一样的,不再赘述。
headerKey属性和headerValue属性同时使用,可以在所有的真实选项(来源于list属性的选项)之前加一项作为标题项。比如,选择用户的时候,可以在所有的具体用户出现之前加一项“请选择”,这个项不作为备选的值。
emptyOption属性可以设置一个布尔值,指定是否在标题和真实的选项之间加一个空选项。
multiple属性和size属性类似于HTML的<select>标签,size属性可以让下拉框同时显示多个值,multiple属性让用户可以同时选择多个值,当然,后面的Action在接收这种下拉框的输入的时候,也不能直接使用String,应该使用String[]或List<String>。
Note: For any of the tags that use lists (select probably being the most ubiquitous), which uses the OGNL listnotation (see the "months" example above), it should be noted that the map key created (in the months example,the '01', '02', etc.) is typed. '1' is a char, '01' is a String, "1" is a String. This is important since ifthe value returned by your "value" attribute is NOT the same type as the key in the "list" attribute, theyWILL NOT MATCH, even though their String values may be equivalent. If they don't match, nothing in your listwill be auto-selected.<p/>
<s:select label="Pets"
name="petIds"
list="petDao.pets"
listKey="id"
listValue="name"
multiple="true"
size="3"
required="true"
value="%{petDao.pets.{id}}"
/>
<s:select label="Months"
name="months"
headerKey="-1" headerValue="Select Month"
list="#{'01':'Jan', '02':'Feb', [...]}"
value="selectedMonth"
required="true"
/>
// The month id (01, 02, ...) returned by the getSelectedMonth() call
// against the stack will be auto-selected
submit
Description
Render a submit button. The submit tag is used together with the form tag to provide asynchronous form submissions. The submit can have three different types of rendering:
- input: renders as html <input type="submit"...>
- image: renders as html <input type="image"...>
- button: renders as html <button type="submit"...>
Please note that the button type has advantages by adding the possibility to seperate the submitted value from the text shown on the button face, but has issues with Microsoft Internet Explorer at least up to 6.0
textarea
多行文本框用来输入一段可能很长的带有回车的文本。textarea标签对应HTML中的<textarea>。
除了上面列出的各种常见通用属性,textarea标签还有几个其它的属性:
- cols:列数。
- rows:行数。
- readonly:多行文本是否只读。
- wrap:指定多行文本框中的内容是否自动换行。
textarea标签和HTML的textarea标签在指定默认值的时候稍稍有一点区别,HTML中的textarea标签指定默认值的时候,必须使用<textarea>标签内的文本,其value属性不起作用
<s:textarea label="Comments" name="comments" cols="30" rows="8"/>
textfield
单行文本框是表单域中最常见的了,textfield标签对应着HTML的<input type=”text”>,用于生成单行文本。
除了上面列出的各种常见通用属性,textfield标签还有几个其它的属性:
- maxlength:单行文本框中所能容纳的最大文本长度。
- size:单行文本框自身的长度。
- readonly:单行文本框是否只读。
<s:textfield key="user" />
token
<s:token />
token 防止多次提交 避免刷新页面多次提交
在struts2配置文件中启用TokenInteceptor或者TokenSessionStoreInterceptor 拦截器
原理在表单添加一个隐藏域,每次加在页面页面的值不同。而拦截器拦截隐藏域的值如果两次值相同则组织表单提交。
<s:from><s:token/></s:from>
updownselect
<!-- Example 1: simple example -->
<s:updownselect
list="#{'england':'England', 'america':'America', 'germany':'Germany'}"
name="prioritisedFavouriteCountries"
headerKey="-1"
headerValue="--- Please Order Them Accordingly ---"
emptyOption="true" />
<!-- Example 2: more complex example -->
<s:updownselect
list="defaultFavouriteCartoonCharacters"
name="prioritisedFavouriteCartoonCharacters"
headerKey="-1"
headerValue="--- Please Order ---"
emptyOption="true"
allowMoveUp="true"
allowMoveDown="true"
allowSelectAll="true"
moveUpLabel="Move Up"
moveDownLabel="Move Down"
selectAllLabel="Select All" />