http://git-wip-us.apache.org/repos/asf/struts-site/blob/124e36c4/content/docs/form-tags.html ---------------------------------------------------------------------- diff --git a/content/docs/form-tags.html b/content/docs/form-tags.html new file mode 100644 index 0000000..19a0525 --- /dev/null +++ b/content/docs/form-tags.html @@ -0,0 +1,261 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> +<html> +<head> + <link type="text/css" rel="stylesheet" href="https://struts.apache.org/css/default.css";> + <style type="text/css"> + .dp-highlighter { + width:95% !important; + } + </style> + <style type="text/css"> + .footer { + background-image: url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif'); + background-repeat: repeat-x; + background-position: left top; + padding-top: 4px; + color: #666; + } + </style> + <link href='https://struts.apache.org/highlighter/style/shCoreStruts.css' rel='stylesheet' type='text/css' /> + <link href='https://struts.apache.org/highlighter/style/shThemeStruts.css' rel='stylesheet' type='text/css' /> + <script src='https://struts.apache.org/highlighter/js/shCore.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushPlain.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushXml.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushJava.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushJScript.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushGroovy.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushBash.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushCss.js' type='text/javascript'></script> + <script type="text/javascript"> + SyntaxHighlighter.defaults['toolbar'] = false; + SyntaxHighlighter.all(); + </script> + <script type="text/javascript" language="javascript"> + var hide = null; + var show = null; + var children = null; + + function init() { + /* Search form initialization */ + var form = document.forms['search']; + if (form != null) { + form.elements['domains'].value = location.hostname; + form.elements['sitesearch'].value = location.hostname; + } + + /* Children initialization */ + hide = document.getElementById('hide'); + show = document.getElementById('show'); + children = document.all != null ? + document.all['children'] : + document.getElementById('children'); + if (children != null) { + children.style.display = 'none'; + show.style.display = 'inline'; + hide.style.display = 'none'; + } + } + + function showChildren() { + children.style.display = 'block'; + show.style.display = 'none'; + hide.style.display = 'inline'; + } + + function hideChildren() { + children.style.display = 'none'; + show.style.display = 'inline'; + hide.style.display = 'none'; + } + </script> + <title>Form Tags</title> +</head> +<body onload="init()"> +<table border="0" cellpadding="2" cellspacing="0" width="100%"> + <tr class="topBar"> + <td align="left" valign="middle" class="topBarDiv" align="left" nowrap> + <a href="home.html">Home</a> > <a href="guides.html">Guides</a> > <a href="tag-developers-guide.html">Tag Developers Guide</a> > <a href="struts-tags.html">Struts Tags</a> > <a href="ui-tags.html">UI Tags</a> > <a href="form-tags.html">Form Tags</a> + </td> + <td align="right" valign="middle" nowrap> + <form name="search" action="https://www.google.com/search"; method="get"> + <input type="hidden" name="ie" value="UTF-8" /> + <input type="hidden" name="oe" value="UTF-8" /> + <input type="hidden" name="domains" value="" /> + <input type="hidden" name="sitesearch" value="" /> + <input type="text" name="q" maxlength="255" value="" /> + <input type="submit" name="btnG" value="Google Search" /> + </form> + </td> + </tr> +</table> + +<div id="PageContent"> + <div class="pageheader" style="padding: 6px 0px 0px 0px;"> + <!-- We'll enable this once we figure out how to access (and save) the logo resource --> + <!--img src="/wiki/images/confluence_logo.gif" style="float: left; margin: 4px 4px 4px 10px;" border="0"--> + <div style="margin: 0px 10px 0px 10px" class="smalltext">Apache Struts 2 Documentation</div> + <div style="margin: 0px 10px 8px 10px" class="pagetitle">Form Tags</div> + + <div class="greynavbar" align="right" style="padding: 2px 10px; margin: 0px;"> + <a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14230";> + <img src="https://cwiki.apache.org/confluence/images/icons/notep_16.gif"; + height="16" width="16" border="0" align="absmiddle" title="Edit Page"></a> + <a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14230";>Edit Page</a> + + <a href="https://cwiki.apache.org/confluence/pages/listpages.action?key=WW";> + <img src="https://cwiki.apache.org/confluence/images/icons/browse_space.gif"; + height="16" width="16" border="0" align="absmiddle" title="Browse Space"></a> + <a href="https://cwiki.apache.org/confluence/pages/listpages.action?key=WW";>Browse Space</a> + + <a href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=WW&fromPageId=14230";> + <img src="https://cwiki.apache.org/confluence/images/icons/add_page_16.gif"; + height="16" width="16" border="0" align="absmiddle" title="Add Page"></a> + <a href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=WW&fromPageId=14230";>Add Page</a> + + <a href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=WW&fromPageId=14230";> + <img src="https://cwiki.apache.org/confluence/images/icons/add_blogentry_16.gif"; + height="16" width="16" border="0" align="absmiddle" title="Add News"></a> + <a href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=WW&fromPageId=14230";>Add News</a> + </div> + </div> + + <div class="pagecontent"> + <div class="wiki-content"> + <div id="ConfluenceContent"><div class="confluence-information-macro confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Please make sure you have read the <a shape="rect" href="tag-syntax.html">Tag Syntax</a> document and understand how tag attribute syntax works.</p></div></div><p>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.</p><h2 id="FormTags-FormTagThemes">Form Tag Themes</h2><p>As explained in <a shape="rect" href="themes-and-templates.html">Themes and Templates</a>, 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.</p><div class="table-wrap" ><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" >class="confluenceTh"><p>simple</p></th><td colspan="1" rowspan="1" >class="confluenceTd"><p>Sometimes <em>too</em> simple</p></td></tr><tr><th >colspan="1" rowspan="1" class="confluenceTh"><p>xhtml</p></th><td colspan="1" >rowspan="1" class="confluenceTd"><p>Extends simple</p></td><td colspan="1" >rowspan="1" class="confluenceTd"><p>(default)</p></td></tr><tr><th >colspan="1" rowspan="1" class="confluenceTh"><p>ajax</p></th><td colspan="1" >rowspan="1" class="confluenceTd"><p>Extends >xhtml</p></td></tr></tbody></table></div><p>The predefined themes can be used >"as is" or customized.</p><div class="confluence-information-macro >confluence-information-macro-tip"><p class="title">xhtml layout</p><span >class="aui-icon aui-icon-small aui-iconfont-approve >confluence-information-macro-icon"></span><div >class="confluence-information-macro-body"><p>The xhtml theme renders out a >two-column table. If a different layout is needed, do <em>not</em> write your own HTML. Create a new theme or utilize the simple theme.</p></div></div><h3 id="FormTags-Simplethemecaveats">Simple theme caveats</h3><p>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 <code>label</code> attribute does nothing in the simple theme, and the automatic display of error messages is not supported.</p><h2 id="FormTags-CommonAttributes">Common Attributes</h2><p>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: <code>templated-related</code>, javascript-related, and general attributes. The individual attributes are documented on each tag's reference page.</p><p>In addition to the common attributes, a special attribute exists for all form element tags: <code>form</code> (${parameters.form}). The <code>form</code> 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}.</p><h2 id="FormTags-Template-RelatedAttributes">Template-Related Attributes</h2> +<p><table border="1" summary=""><thead><tr><td colspan="1" rowspan="1">Attribute</td><td colspan="1" rowspan="1">Theme</td><td colspan="1" rowspan="1">Data Types</td><td colspan="1" rowspan="1">Description</td></tr></thead><tbody><tr><td colspan="1" rowspan="1">templateDir</td><td colspan="1" rowspan="1">n/a</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">define the template directory</td></tr><tr><td colspan="1" rowspan="1">theme</td><td colspan="1" rowspan="1">n/a</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">define the theme name</td></tr><tr><td colspan="1" rowspan="1">template</td><td colspan="1" rowspan="1">n/a</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">define the template name</td></tr><tr><td colspan="1" rowspan="1">themeExpansionToken</td><td colspan="1" rowspan="1">n/a</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">special token (defined with struts.ui.theme.expansion.token) used to search for template in parent theme + (don't use it separately!)</td></tr><tr><td colspan="1" rowspan="1">expandTheme</td><td colspan="1" rowspan="1">n/a</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">concatenation of themeExpansionToken and theme which tells internal template loader mechanism + to try load template from current theme and then from parent theme (and parent theme, and so on) + when used with <#include/> directive</td></tr></tbody></table></p> +<h2 id="FormTags-Javascript-RelatedAttributes">Javascript-Related Attributes</h2> +<p><table border="1" summary=""><thead><tr><td colspan="1" rowspan="1">Attribute</td><td colspan="1" rowspan="1">Theme</td><td colspan="1" rowspan="1">Data Types</td><td colspan="1" rowspan="1">Description</td></tr></thead><tbody><tr><td colspan="1" rowspan="1">onclick</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript onclick attribute</td></tr><tr><td colspan="1" rowspan="1">ondblclick</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript ondbclick attribute</td></tr><tr><td colspan="1" rowspan="1">onmousedown</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript onmousedown attribute</td></tr><tr><td colspan="1" rowspan="1">onmouseup</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript onmouse up attribute</td></tr><tr><td colspan="1" rowspan="1">onmouseover</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript onmouseover attribute</td></tr><tr><td colspan="1" rowspan="1">onmouseout</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript onmouseout attribute</td></tr><tr><td colspan="1" rowspan="1">onfocus</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript onfocus attribute</td></tr><tr><td colspan="1" rowspan="1">onblur</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript onblur attribute</td></tr><tr><td colspan="1" rowspan="1">onkeypress</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript onkeypress attribute</ td></tr><tr><td colspan="1" rowspan="1">onkeyup</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript onkeyup attribute</td></tr><tr><td colspan="1" rowspan="1">onkeydown</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript onkeydown attribute</td></tr><tr><td colspan="1" rowspan="1">onselect</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript onselect attribute</td></tr><tr><td colspan="1" rowspan="1">onchange</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">html javascript onchange attribute</td></tr></tbody></table></p> +<h2 id="FormTags-TooltipRelatedAttributes">Tooltip Related Attributes</h2> +<p><table border="1" summary=""><tr><td colspan="1" rowspan="1">Attribute</td><td colspan="1" rowspan="1">Data Type</td><td colspan="1" rowspan="1">Default</td><td colspan="1" rowspan="1">Description</td></tr><tr><td colspan="1" rowspan="1">tooltip</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">none</td><td colspan="1" rowspan="1">Set the tooltip of this particular component</td></tr><tr><td colspan="1" rowspan="1">jsTooltipEnabled</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">false</td><td colspan="1" rowspan="1">Enable js tooltip rendering</td></tr><tr><td colspan="1" rowspan="1">tooltipIcon</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">/struts/static/tooltip/tooltip.gif</td><td colspan="1" rowspan="1">The url to the tooltip icon</td></tr><tr><td colspan="1" rowspan="1">tooltipDelay</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">500</td><td colspan="1" rowspan="1">Tooltip shows up aft er the specified timeout (miliseconds). A behavior similar to that of OS based tooltips.</td></tr><tr><td colspan="1" rowspan="1">key</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">The name of the property this input field represents. This will auto populate the name, label, and value</td></tr></table></p> +<h2 id="FormTags-GeneralAttributes">General Attributes</h2> +<p><table border="1" summary=""><thead><tr><td colspan="1" rowspan="1">Attribute</td><td colspan="1" rowspan="1">Theme</td><td colspan="1" rowspan="1">Data Types</td><td colspan="1" rowspan="1">Description</td></tr></thead><tbody><tr><td colspan="1" rowspan="1">cssClass</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">define html class attribute</td></tr><tr><td colspan="1" rowspan="1">cssStyle</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">define html style attribute</td></tr><tr><td colspan="1" rowspan="1">cssErrorClass</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">error class attribute</td></tr><tr><td colspan="1" rowspan="1">cssErrorStyle</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">error style attribute</td></tr><tr><td colspan=" 1" rowspan="1">title</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">define html title attribute</td></tr><tr><td colspan="1" rowspan="1">disabled</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">define html disabled attribute</td></tr><tr><td colspan="1" rowspan="1">label</td><td colspan="1" rowspan="1">xhtml</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">define label of form element</td></tr><tr><td colspan="1" rowspan="1">labelPosition</td><td colspan="1" rowspan="1">xhtml</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">define label position of form element (top/left), default to left</td></tr><tr><td colspan="1" rowspan="1">requiredPosition</td><td colspan="1" rowspan="1">xhtml</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">define required label position of form element (left/right), defa ult to right</td></tr><tr><td colspan="1" rowspan="1">errorPosition</td><td colspan="1" rowspan="1">xhtml</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">define error position of form element (top|bottom), default to top</td></tr><tr><td colspan="1" rowspan="1">name</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">Form Element's field name mapping</td></tr><tr><td colspan="1" rowspan="1">requiredLabel</td><td colspan="1" rowspan="1">xhtml</td><td colspan="1" rowspan="1">Boolean</td><td colspan="1" rowspan="1">add * to label (true to add false otherwise)</td></tr><tr><td colspan="1" rowspan="1">tabIndex</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">String</td><td colspan="1" rowspan="1">define html tabindex attribute</td></tr><tr><td colspan="1" rowspan="1">value</td><td colspan="1" rowspan="1">simple</td><td colspan="1" rowspan="1">Object</td><td colspan="1" rowspan="1">defin e value of form element</td></tr></tbody></table></p> +<div class="confluence-information-macro confluence-information-macro-note"><p class="title">When some attributes don't apply</p><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Some tag attributes may not be utilized by all, or any, of the templates. For example, the form tag supports the <code>tabindex</code> attribute, but none of the themes render the <code>tabindex</code>.</p></div></div><h2 id="FormTags-Value/NameRelationship">Value/Name Relationship</h2><p>In many of the tags (except for the form tag) there is a unique relationship between the <code>name</code> and <code>value</code> attributes. The <code>name</code> 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 <code>name</code>. In most cases, the <code>name</code> maps to a simple JavaBean property, such as "postalCode" . On a submit, the value would be set to the property by calling the <code>setPostalCode</code> mutator.</p><p>Likewise, a form control could be populated by calling a JavaBean accessor, like <code>getPostalCode</code>. In the expression language, we can refer to the JavaBean property by name. An expression like "%{postalCode}" would in turn call <code>getPostalCode</code>.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Using Expressions to populate a form for editing</b></div><div class="codeContent panelContent pdl"> +<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><@s.form action="updateAddress"> + <@s.textfield label="Postal Code" name="postalCode" value="%{postalCode}"/> + ... +</@s.form> +</pre> +</div></div><p>However, since the tags imply a relationship between the <code>name</code> and <code>value</code>, the <code>value</code> attribute is optional. If a <code>value</code> is not specified, by default, the JavaBean accessor is used instead.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Populating a form for editing, the easy way</b></div><div class="codeContent panelContent pdl"> +<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><@s.form action="updateAddress"> + <@s.textfield label="Postal Code" name="postalCode"/> + ... +</@s.form> +</pre> +</div></div><p>While most attributes are exposed to the underlying templates as the same key as the attribute (${parameters.label}), the <code>value</code> attribute is not. Instead, it can be accessed via the <code>nameValue</code> key (${parameters.nameValue}). The <code>nameValue</code> key indicates that the value may have been generated from the <code>name</code> attribute rather than explicitly defined in the <code>value</code> attribute.</p><h2 id="FormTags-IDNameAssignment">ID Name Assignment</h2><p>All form tags automatically assign an ID to the control, but the ID can be overridden if needed.</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Forms</p></th><td colspan="1" rowspan="1" class="confluenceTd"><p>The default ID is the action name. For example, "updateAddress".</p></td></tr><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Controls</p></th><td colspan="1" rowspan="1" class="confluenceTd"> <p>The default ID is the form's name concatenated with the tag name. For example, "updateAddress_postalCode".</p></td></tr></tbody></table></div><h2 id="FormTags-Formlabelpositionpropagation">Form labelposition propagation</h2><p>When <code>labelposition</code> attribute was defined for <code><s:form></code> tag it will be propagated to all form elements, but if form element defines its own <code>labelposition</code> it will take precedence over <code><s:form></code>'s attribute. Since 2.3.17.</p><h2 id="FormTags-RequiredAttribute">Required Attribute</h2><p>The <code>required</code> 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.</p><h2 id="FormTags-Tooltip">Tooltip</h2><p></p><p> +<b>tooltipConfig is deprecated, use individual tooltip configuration attributes instead </b> +</p> + +<p></p><p> +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 overridden by having the Form UI component itself defined with their own tooltip attribute. +</p> + +<p></p><p> +In Example 1, the textfield will inherit the tooltipDelay and tooltipIconPath attribute 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. +</p> + +<p></p><p> +In Example 2, the textfield will inherit both the tooltipDelay and +tooltipIconPath attribute from its containing form, but the tooltipDelay +attribute is overridden 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. +</p> + +<p></p><p> +Example 3, 4 and 5 show different ways of setting the tooltip configuration attribute.<br clear="none"> +<b>Example 3:</b> Set tooltip config through the body of the param tag<br clear="none"> +<b>Example 4:</b> Set tooltip config through the value attribute of the param tag<br clear="none"> +<b>Example 5:</b> Set tooltip config through the tooltip attributes of the component tag<br clear="none"> +</p> +<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +<script class="brush: xml; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ + +<!-- 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" /> + +]]></script> +</div></div><h2 id="FormTags-Next:">Next: <a shape="rect" href="ui-tag-reference.html">UI Tag Reference</a></h2></div> + </div> + + + </div> +</div> +<div class="footer"> + Generated by CXF SiteExporter +</div> +</body> +</html>
http://git-wip-us.apache.org/repos/asf/struts-site/blob/124e36c4/content/docs/form-validation-using-xml.data/form-validation-1.png ---------------------------------------------------------------------- diff --git a/content/docs/form-validation-using-xml.data/form-validation-1.png b/content/docs/form-validation-using-xml.data/form-validation-1.png new file mode 100644 index 0000000..226cc1c Binary files /dev/null and b/content/docs/form-validation-using-xml.data/form-validation-1.png differ http://git-wip-us.apache.org/repos/asf/struts-site/blob/124e36c4/content/docs/form-validation-using-xml.data/form-validation-2.png ---------------------------------------------------------------------- diff --git a/content/docs/form-validation-using-xml.data/form-validation-2.png b/content/docs/form-validation-using-xml.data/form-validation-2.png new file mode 100644 index 0000000..16afdaa Binary files /dev/null and b/content/docs/form-validation-using-xml.data/form-validation-2.png differ http://git-wip-us.apache.org/repos/asf/struts-site/blob/124e36c4/content/docs/form-validation-using-xml.data/form-validation-3.png ---------------------------------------------------------------------- diff --git a/content/docs/form-validation-using-xml.data/form-validation-3.png b/content/docs/form-validation-using-xml.data/form-validation-3.png new file mode 100644 index 0000000..ecb5912 Binary files /dev/null and b/content/docs/form-validation-using-xml.data/form-validation-3.png differ http://git-wip-us.apache.org/repos/asf/struts-site/blob/124e36c4/content/docs/form-validation-using-xml.html ---------------------------------------------------------------------- diff --git a/content/docs/form-validation-using-xml.html b/content/docs/form-validation-using-xml.html new file mode 100644 index 0000000..566f6dc --- /dev/null +++ b/content/docs/form-validation-using-xml.html @@ -0,0 +1,195 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> +<html> +<head> + <link type="text/css" rel="stylesheet" href="https://struts.apache.org/css/default.css";> + <style type="text/css"> + .dp-highlighter { + width:95% !important; + } + </style> + <style type="text/css"> + .footer { + background-image: url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif'); + background-repeat: repeat-x; + background-position: left top; + padding-top: 4px; + color: #666; + } + </style> + <link href='https://struts.apache.org/highlighter/style/shCoreStruts.css' rel='stylesheet' type='text/css' /> + <link href='https://struts.apache.org/highlighter/style/shThemeStruts.css' rel='stylesheet' type='text/css' /> + <script src='https://struts.apache.org/highlighter/js/shCore.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushPlain.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushXml.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushJava.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushJScript.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushGroovy.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushBash.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushCss.js' type='text/javascript'></script> + <script type="text/javascript"> + SyntaxHighlighter.defaults['toolbar'] = false; + SyntaxHighlighter.all(); + </script> + <script type="text/javascript" language="javascript"> + var hide = null; + var show = null; + var children = null; + + function init() { + /* Search form initialization */ + var form = document.forms['search']; + if (form != null) { + form.elements['domains'].value = location.hostname; + form.elements['sitesearch'].value = location.hostname; + } + + /* Children initialization */ + hide = document.getElementById('hide'); + show = document.getElementById('show'); + children = document.all != null ? + document.all['children'] : + document.getElementById('children'); + if (children != null) { + children.style.display = 'none'; + show.style.display = 'inline'; + hide.style.display = 'none'; + } + } + + function showChildren() { + children.style.display = 'block'; + show.style.display = 'none'; + hide.style.display = 'inline'; + } + + function hideChildren() { + children.style.display = 'none'; + show.style.display = 'inline'; + hide.style.display = 'none'; + } + </script> + <title>Form Validation Using XML</title> +</head> +<body onload="init()"> +<table border="0" cellpadding="2" cellspacing="0" width="100%"> + <tr class="topBar"> + <td align="left" valign="middle" class="topBarDiv" align="left" nowrap> + <a href="home.html">Home</a> > <a href="tutorials.html">Tutorials</a> > <a href="getting-started.html">Getting Started</a> > <a href="form-validation-using-xml.html">Form Validation Using XML</a> + </td> + <td align="right" valign="middle" nowrap> + <form name="search" action="https://www.google.com/search"; method="get"> + <input type="hidden" name="ie" value="UTF-8" /> + <input type="hidden" name="oe" value="UTF-8" /> + <input type="hidden" name="domains" value="" /> + <input type="hidden" name="sitesearch" value="" /> + <input type="text" name="q" maxlength="255" value="" /> + <input type="submit" name="btnG" value="Google Search" /> + </form> + </td> + </tr> +</table> + +<div id="PageContent"> + <div class="pageheader" style="padding: 6px 0px 0px 0px;"> + <!-- We'll enable this once we figure out how to access (and save) the logo resource --> + <!--img src="/wiki/images/confluence_logo.gif" style="float: left; margin: 4px 4px 4px 10px;" border="0"--> + <div style="margin: 0px 10px 0px 10px" class="smalltext">Apache Struts 2 Documentation</div> + <div style="margin: 0px 10px 8px 10px" class="pagetitle">Form Validation Using XML</div> + + <div class="greynavbar" align="right" style="padding: 2px 10px; margin: 0px;"> + <a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=20644608";> + <img src="https://cwiki.apache.org/confluence/images/icons/notep_16.gif"; + height="16" width="16" border="0" align="absmiddle" title="Edit Page"></a> + <a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=20644608";>Edit Page</a> + + <a href="https://cwiki.apache.org/confluence/pages/listpages.action?key=WW";> + <img src="https://cwiki.apache.org/confluence/images/icons/browse_space.gif"; + height="16" width="16" border="0" align="absmiddle" title="Browse Space"></a> + <a href="https://cwiki.apache.org/confluence/pages/listpages.action?key=WW";>Browse Space</a> + + <a href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=WW&fromPageId=20644608";> + <img src="https://cwiki.apache.org/confluence/images/icons/add_page_16.gif"; + height="16" width="16" border="0" align="absmiddle" title="Add Page"></a> + <a href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=WW&fromPageId=20644608";>Add Page</a> + + <a href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=WW&fromPageId=20644608";> + <img src="https://cwiki.apache.org/confluence/images/icons/add_blogentry_16.gif"; + height="16" width="16" border="0" align="absmiddle" title="Add News"></a> + <a href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=WW&fromPageId=20644608";>Add News</a> + </div> + </div> + + <div class="pagecontent"> + <div class="wiki-content"> + <div id="ConfluenceContent"><div class="confluence-information-macro confluence-information-macro-information"><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>The example code for this tutorial, form_xml_validation, is available for checkout at <a shape="rect" class="external-link" href="https://github.com/apache/struts-examples"; rel="nofollow">https://github.com/apache/struts-examples</a></p></div></div><h3 id="FormValidationUsingXML-Introduction">Introduction</h3><p>In this tutorial we'll cover how to validate a user's input in form fields using Struts 2's XML validation methodology. In the <a shape="rect" href="form-validation.html">Form Validation</a> tutorial we discussed validating a user's input using the validate method in the Action class. Using a separate XML validation file gives you the ability to use validators built-in to the Struts 2 framework.</p><div class= "confluence-information-macro confluence-information-macro-tip"><span class="aui-icon aui-icon-small aui-iconfont-approve confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>The <a shape="rect" class="external-link" href="http://struts.apache.org/mail.html";>Struts 2 user mailing list</a> is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.</p></div></div><h3 id="FormValidationUsingXML-ExampleApplication">Example Application</h3><p>The example application that supports this tutorial shows how to use Struts 2's XML validation methodology. The information that can be edited is encapsulated in an object of class Person.</p><p>To enable the user to edit his information that is stored in the Person object, we have this form:</p><p><span class="confluence-embedded-file-wrapper" ><img class="confluence-embedded-image confluence-content-image-border" >src="form-validation-using-xml.data/form-validation-1.png"></span></p><p>When >the user submits the form, we want to validate his entries into the form >fields.</p><h3 id="FormValidationUsingXML-ValidationUsingXML">Validation >Using XML</h3><p>To validate a user's form field entries you can use a >separate XML file that contains your validation rules. The XML file that >contains the validation rules must be named as >ActionClassName-validation.xml. In the example application, the XML >validation file is named EditAction-validation.xml (see >src/main/resources/org/apache/struts/edit/action).</p><p>Struts 2 provides >several different validators that you can use in the XML validation file. See ><a shape="rect" href="validation.html">Validation</a> for a list of >validators you can employ.</p><p>In the above form, we want to ensure the >user enters a first name. To have the Struts 2 framework enforce that rule we >can used the Struts 2 <a shape="rect" href="requiredstring-validator.html">requiredstring validator</a>. This validator checks that the user has entered a string value in the form field.</p><h3 id="FormValidationUsingXML-XMLValidatorFormat">XML Validator Format</h3><p>In the XML validation file (for this example that is EditAction-validation.xml), is this XML:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>XML Validator Required String</b></div><div class="codeContent panelContent pdl"> +<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><!DOCTYPE validators PUBLIC "-//Apache Struts//XWork Validator 1.0.3//EN" + "http://struts.apache.org/dtds/xwork-validator-1.0.3.dtd"> + +<validators> + <validator type="requiredstring"> + <param name="fieldname">personBean.firstName</param> + <message>First name is required.</message> + </validator> +</validators> + +</pre> +</div></div><p>Within the validators node you can have 1 or more validator nodes. The type attribute specifies which validator you want the Struts 2 framework to use (see <a shape="rect" href="validation.html">Validation</a>). The param name="fieldname" node is used to tell the framework which form field entry to apply the rule to. See edit.jsp for the form fields and their name value (review <a shape="rect" href="struts-2-form-tags.html">Struts 2 Form Tags</a> if you're not familiar with how to use Struts 2 form tags). The message node is used to tell the framework what message to display if the validation fails.</p><div class="confluence-information-macro confluence-information-macro-tip"><span class="aui-icon aui-icon-small aui-iconfont-approve confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>There are alternate ways to write the XML that goes in the validation XML file. See <a shape="rect" href="validation.html">Validation</a> in the St ruts 2 documentation for a full discussion.</p></div></div><p>For example if the user doesn't enter a value in the first name form field and clicks on the Save Changes button, he will see the following.</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-content-image-border" src="form-validation-using-xml.data/form-validation-2.png"></span></p><h3 id="FormValidationUsingXML-ValidatingAnEmailAddress">Validating An Email Address</h3><p>You can use the Struts 2 <a shape="rect" href="email-validator.html">email validator</a> to validate the user's input in the email field. Here is the validator node that is in the EditAction-validation.xml file.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Email Validator</b></div><div class="codeContent panelContent pdl"> +<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"> <validator type="requiredstring"> + <param name="fieldname">personBean.email</param> + <message>Email address is required.</message> + </validator> + <validator type="email"> + <param name="fieldname">personBean.email</param> + <message>Email address not valid.</message> + </validator> + +</pre> +</div></div><p>Note that in the example, we are requiring the user to enter an email address and then validating the email address the user entered.</p><h3 id="FormValidationUsingXML-ValidatingAUser'sInputUsingARegularExpression">Validating A User's Input Using A Regular Expression</h3><p>The Struts 2 framework provides a powerful way to validate a user's form field input by using the <a shape="rect" href="regex-validator.html">regex validator</a>. In the example application, we want to ensure the user enters the phone number in the format 999-999-9999. We can use a regular expression and the <a shape="rect" href="regex-validator.html">regex validator</a> to enforce this rule.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>REGEX Validator</b></div><div class="codeContent panelContent pdl"> +<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><validator type="requiredstring"> + <param name="fieldname">personBean.phoneNumber</param> + <message>Phone number is required.</message> + </validator> +<validator type="regex"> + <param name="fieldname">personBean.phoneNumber</param> + <param name="regex"><![CDATA[\d{3}-\d{3}-\d{4}]]></param> + <message>Phone number must be entered as 999-999-9999.</message> +</validator> + +</pre> +</div></div><p>The param name="expression" node is used to specify the regular expression that will be applied to the user's input. Note how the regular expression is contained within a CDATA section.</p><h3 id="FormValidationUsingXML-ValidatingAUser'sInputUsingAnOGNLExpression">Validating A User's Input Using An OGNL Expression</h3><p>In the example application, we want to ensure the user checks at least one of the car model check boxes. To enforce this rule we can use the <a shape="rect" href="fieldexpression-validator.html">fieldexpression validator</a>. Here's the XML for that validator node.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>FieldExpression Validator</b></div><div class="codeContent panelContent pdl"> +<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><validator type="fieldexpression"> + <param name="fieldname">personBean.carModels</param> + <param name="expression"><![CDATA[personBean.carModels.length > 0]]></param> + <message>You must select at least one car model.</message> +</validator> + +</pre> +</div></div><p>The param name="expression" node contains an OGNL expression that evaluates to true or false. We haven't previously discussed OGNL, which stands for Object-Graph Navigation Language (see <a shape="rect" class="external-link" href="http://www.opensymphony.com/ognl/"; rel="nofollow">http://www.opensymphony.com/ognl/</a> and <a shape="rect" href="ognl.html">OGNL</a>). OGNL expressions can be evaluated by the Struts 2 framework as Java statements.</p><p>In the above XML the value of the param name="expression" node, personBean.carModels.length > 0, will be evaluated by the framework as a Java statement. The part personBean.carModels tells the framework to call the getCarModels method of class Person. That method returns an Array. Since class Array has a length attribute, the framework will get the value of the length attribute of the Array returned by the getCarModels method.</p><p>If the user did not check any of the check boxes, the Array returned by the getCarModels method will have a length value of 0. Since the complete OGNL expression will only evaluate to true if the length value is greater than 0, the validation fails. The user will see this.</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-content-image-border" src="form-validation-using-xml.data/form-validation-3.png"></span></p><p>The fieldexpression validator is useful when doing conditional validation of a user's input. If the OGNL expression doesn't evaluate to true then the user's input won't be allowed.</p><h3 id="FormValidationUsingXML-Summary">Summary</h3><p>The Struts 2 framework provides easy-to-use validation methodologies. You can add a validate method to the Action class or have a separate XML file with validation rules or you can use a combination of both methodologies.</p><h3 id="FormValidationUsingXML-UpNext">Up Next</h3><p>In our next tutorial we'll cover how to enable one action node in struts.xml to respond to severa l different action URLs.</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Next</p></th><td colspan="1" rowspan="1" class="confluenceTd"><p>Onward to <a shape="rect" href="wildcard-method-selection.html">Wildcard Method Selection</a></p></td></tr></tbody></table></div></div> + </div> + + + </div> +</div> +<div class="footer"> + Generated by CXF SiteExporter +</div> +</body> +</html> http://git-wip-us.apache.org/repos/asf/struts-site/blob/124e36c4/content/docs/form-validation.data/form_errors.png ---------------------------------------------------------------------- diff --git a/content/docs/form-validation.data/form_errors.png b/content/docs/form-validation.data/form_errors.png new file mode 100644 index 0000000..c135558 Binary files /dev/null and b/content/docs/form-validation.data/form_errors.png differ http://git-wip-us.apache.org/repos/asf/struts-site/blob/124e36c4/content/docs/form-validation.data/form_errors_styled.png ---------------------------------------------------------------------- diff --git a/content/docs/form-validation.data/form_errors_styled.png b/content/docs/form-validation.data/form_errors_styled.png new file mode 100644 index 0000000..c7be09a Binary files /dev/null and b/content/docs/form-validation.data/form_errors_styled.png differ http://git-wip-us.apache.org/repos/asf/struts-site/blob/124e36c4/content/docs/form-validation.data/form_errors_sytled.png ---------------------------------------------------------------------- diff --git a/content/docs/form-validation.data/form_errors_sytled.png b/content/docs/form-validation.data/form_errors_sytled.png new file mode 100644 index 0000000..20c2ee7 Binary files /dev/null and b/content/docs/form-validation.data/form_errors_sytled.png differ http://git-wip-us.apache.org/repos/asf/struts-site/blob/124e36c4/content/docs/form-validation.html ---------------------------------------------------------------------- diff --git a/content/docs/form-validation.html b/content/docs/form-validation.html new file mode 100644 index 0000000..a96a9e0 --- /dev/null +++ b/content/docs/form-validation.html @@ -0,0 +1,195 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> +<html> +<head> + <link type="text/css" rel="stylesheet" href="https://struts.apache.org/css/default.css";> + <style type="text/css"> + .dp-highlighter { + width:95% !important; + } + </style> + <style type="text/css"> + .footer { + background-image: url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif'); + background-repeat: repeat-x; + background-position: left top; + padding-top: 4px; + color: #666; + } + </style> + <link href='https://struts.apache.org/highlighter/style/shCoreStruts.css' rel='stylesheet' type='text/css' /> + <link href='https://struts.apache.org/highlighter/style/shThemeStruts.css' rel='stylesheet' type='text/css' /> + <script src='https://struts.apache.org/highlighter/js/shCore.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushPlain.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushXml.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushJava.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushJScript.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushGroovy.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushBash.js' type='text/javascript'></script> + <script src='https://struts.apache.org/highlighter/js/shBrushCss.js' type='text/javascript'></script> + <script type="text/javascript"> + SyntaxHighlighter.defaults['toolbar'] = false; + SyntaxHighlighter.all(); + </script> + <script type="text/javascript" language="javascript"> + var hide = null; + var show = null; + var children = null; + + function init() { + /* Search form initialization */ + var form = document.forms['search']; + if (form != null) { + form.elements['domains'].value = location.hostname; + form.elements['sitesearch'].value = location.hostname; + } + + /* Children initialization */ + hide = document.getElementById('hide'); + show = document.getElementById('show'); + children = document.all != null ? + document.all['children'] : + document.getElementById('children'); + if (children != null) { + children.style.display = 'none'; + show.style.display = 'inline'; + hide.style.display = 'none'; + } + } + + function showChildren() { + children.style.display = 'block'; + show.style.display = 'none'; + hide.style.display = 'inline'; + } + + function hideChildren() { + children.style.display = 'none'; + show.style.display = 'inline'; + hide.style.display = 'none'; + } + </script> + <title>Form Validation</title> +</head> +<body onload="init()"> +<table border="0" cellpadding="2" cellspacing="0" width="100%"> + <tr class="topBar"> + <td align="left" valign="middle" class="topBarDiv" align="left" nowrap> + <a href="home.html">Home</a> > <a href="tutorials.html">Tutorials</a> > <a href="getting-started.html">Getting Started</a> > <a href="how-to-create-a-struts-2-web-application.html">How To Create A Struts 2 Web Application</a> > <a href="create-struts-2-web-application-with-artifacts-in-web-inf-lib-and-use-ant-to-build-the-application.html">Create Struts 2 Web Application With Artifacts In WEB-INF lib and Use Ant To Build The Application</a> > <a href="hello-world-using-struts-2.html">Hello World Using Struts 2</a> > <a href="using-struts-2-tags.html">Using Struts 2 Tags</a> > <a href="coding-struts-2-actions.html">Coding Struts 2 Actions</a> > <a href="processing-forms.html">Processing Forms</a> > <a href="form-validation.html">Form Validation</a> + </td> + <td align="right" valign="middle" nowrap> + <form name="search" action="https://www.google.com/search"; method="get"> + <input type="hidden" name="ie" value="UTF-8" /> + <input type="hidden" name="oe" value="UTF-8" /> + <input type="hidden" name="domains" value="" /> + <input type="hidden" name="sitesearch" value="" /> + <input type="text" name="q" maxlength="255" value="" /> + <input type="submit" name="btnG" value="Google Search" /> + </form> + </td> + </tr> +</table> + +<div id="PageContent"> + <div class="pageheader" style="padding: 6px 0px 0px 0px;"> + <!-- We'll enable this once we figure out how to access (and save) the logo resource --> + <!--img src="/wiki/images/confluence_logo.gif" style="float: left; margin: 4px 4px 4px 10px;" border="0"--> + <div style="margin: 0px 10px 0px 10px" class="smalltext">Apache Struts 2 Documentation</div> + <div style="margin: 0px 10px 8px 10px" class="pagetitle">Form Validation</div> + + <div class="greynavbar" align="right" style="padding: 2px 10px; margin: 0px;"> + <a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14811892";> + <img src="https://cwiki.apache.org/confluence/images/icons/notep_16.gif"; + height="16" width="16" border="0" align="absmiddle" title="Edit Page"></a> + <a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14811892";>Edit Page</a> + + <a href="https://cwiki.apache.org/confluence/pages/listpages.action?key=WW";> + <img src="https://cwiki.apache.org/confluence/images/icons/browse_space.gif"; + height="16" width="16" border="0" align="absmiddle" title="Browse Space"></a> + <a href="https://cwiki.apache.org/confluence/pages/listpages.action?key=WW";>Browse Space</a> + + <a href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=WW&fromPageId=14811892";> + <img src="https://cwiki.apache.org/confluence/images/icons/add_page_16.gif"; + height="16" width="16" border="0" align="absmiddle" title="Add Page"></a> + <a href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=WW&fromPageId=14811892";>Add Page</a> + + <a href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=WW&fromPageId=14811892";> + <img src="https://cwiki.apache.org/confluence/images/icons/add_blogentry_16.gif"; + height="16" width="16" border="0" align="absmiddle" title="Add News"></a> + <a href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=WW&fromPageId=14811892";>Add News</a> + </div> + </div> + + <div class="pagecontent"> + <div class="wiki-content"> + <div id="ConfluenceContent"><div class="confluence-information-macro confluence-information-macro-information"><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>This tutorial assumes you've completed the <a shape="rect" href="processing-forms.html">Processing Forms</a> tutorial and have a working form_processing project. The example code for this tutorial, form_validation, is available for checkout from the Struts 2 GitHub repository: <a shape="rect" class="external-link" href="https://github.com/apache/struts-examples"; rel="nofollow">https://github.com/apache/struts-examples</a>.</p></div></div><h3 id="FormValidation-Introduction">Introduction</h3><p>In this tutorial we'll explore using Struts 2 to validate the user's input on a form. There are two ways you can use Struts 2 to do form validation. This tutorial will cover the more basic method, where the validation is include d in the Struts 2 Action class.</p><div class="confluence-information-macro confluence-information-macro-tip"><span class="aui-icon aui-icon-small aui-iconfont-approve confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>The <a shape="rect" class="external-link" href="http://struts.apache.org/mail.html";>Struts 2 user mailing list</a> is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.</p></div></div><h3 id="FormValidation-AddvalidateMethod">Add validate Method</h3><p>To enable the Struts 2 Action class to validate a user's input on a Struts 2 form, you must define a validate method in your Action class. Using the example from <a shape="rect" href="processing-forms.html">Processing Forms</a> tutorial, let's say that we have these business rules:</p><p>1. User must provide a first name<br clear="none"> 2. User must provide an email address<br clear="none"> 3. User younger then 18 cannot register</p><p>If you recall from the <a shape="rect" href="processing-forms.html">Processing Forms</a> tutorial the user's input into the form fields is placed by Struts 2 into the Java model class personBean. So a user's input into the firstName field would end up as the value for personBean's firstName instance field (via the personBean.setFirstName method).</p><p>In the validate method we can refer to get the values of personBean's instance fields by using the appropriate get methods. Once we have the values we can employ logic to enforce our business rules.</p><p>Add the following validate method to Register.java (the Action class).</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>validate method</b></div><div class="codeContent panelContent pdl"> +<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> public void validate(){ + + if ( personBean.getFirstName().length() == 0 ){ + + addFieldError( "personBean.firstName", "First name is required." ); + + } + + + if ( personBean.getEmail().length() == 0 ){ + + addFieldError( "personBean.email", "Email is required." ); + + } + + if ( personBean.getAge() < 18 ){ + + addFieldError( "personBean.age", "Age is required and must be 18 or older" ); + + } + + + } +</pre> +</div></div><p>When the user presses the submit button on the register form, Struts 2 will transfer the user's input to the personBean's instance fields. Then Struts 2 will automatically execute the validate method. If any of the if statements are true, Struts 2 will call its addFieldError method (which our Action class inherited by extending ActionSupport).</p><p>If any errors have been added then Struts 2 will not proceed to call the execute method. Rather the Struts 2 framework will return "input" as the result of calling the action.</p><h3 id="FormValidation-HandleInputBeingReturned">Handle Input Being Returned</h3><p>So what should we do if Struts 2 returns "input" indicating that the user's input in the form is not valid? In most cases we will want to redisplay the web page that has the form and include in the form error messages to inform the user what is wrong.</p><p>To handle the return value of "input" we need to add the following result to our action node in struts.xml.</ p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><result name="input">/register.jsp</result> +</pre> +</div></div><p>The above result node goes just after the success result node for the register action and before the closing of the action node.</p><h3 id="FormValidation-ErrorMessages">Error Messages</h3><p>So when validation fails and Struts 2 returns input, the Struts 2 framework will redisplay the register.jsp. Since we used Struts 2 form tags, automatically Struts 2 will add the error messages. These error messages are the ones we specified in the addFieldError method call. The addFieldError method takes two arguments. The first is the form field name to which the error applies and the second is the error message to display above that form field.</p><p>So the following addFieldError method call:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">addFieldError( "personBean.firstName", "First name is required.") +</pre> +</div></div><p>will cause the message "First name is required" to be displayed above the firstName field on the form.</p><p>If you have made the above changes to the <a shape="rect" href="processing-forms.html">Processing Forms</a> tutorial or you have downloaded from <a shape="rect" class="external-link" href="http://code.google.com/p/struts2-examples/downloads/list"; rel="nofollow">Google Code</a> either the Form_Validation_Struts2_Ant or Form_Validation_Struts2_Mvn projects run the application (see the README.txt in the project root folder). Click on the Please register link. On the registration form, just click the submit button and you should see:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="form-validation.data/form_errors.png"></span></p><p>Struts 2 called the validate method, validation failed, the register.jsp was displayed with the error messages.</p><h3 id="FormValidation-StylingTheErrorMessages">Styling The Error Message s</h3><p>The Struts 2 s:head tag can be used to provide CSS that includes a style for the error message. Add <code><s:head /></code> to register.jsp before the closing HTML <code></head></code> tag. Go through the same steps as above and you should see:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="form-validation.data/form_errors_styled.png"></span></p><h3 id="FormValidation-Summary">Summary</h3><p>This tutorial covered validating a user's form input by adding a validate method to an Action class. There is another more sophisticated way to validate user input using XML. If you want to learn more about using XML for validation in Struts 2 see <a shape="rect" href="validation.html">Validation</a>.</p><h3 id="FormValidation-UpNext">Up Next</h3><p>In our next tutorial we'll cover how to use message resource files to separate out the text from the view page.</p><div class="table-wrap"><table class="confluenceTable"><tbody><t r><th colspan="1" rowspan="1" class="confluenceTh"><p>Next</p></th><td colspan="1" rowspan="1" class="confluenceTd"><p>Onward to <a shape="rect" href="message-resource-files.html">Message Resource Files</a></p></td></tr><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Prev</p></th><td colspan="1" rowspan="1" class="confluenceTd"><p>Return to <a shape="rect" href="processing-forms.html">Processing Forms</a></p></td></tr></tbody></table></div></div> + </div> + + <div class="tabletitle"> + Children + <span class="smalltext" id="show" style="display: inline;"> + <a href="javascript:showChildren()">Show Children</a></span> + <span class="smalltext" id="hide" style="display: none;"> + <a href="javascript:hideChildren()">Hide Children</a></span> + </div> + <div class="greybox" id="children" style="display: none;"> + $page.link($child) + <span class="smalltext">(Apache Struts 2 Documentation)</span> + <br> + </div> + + </div> +</div> +<div class="footer"> + Generated by CXF SiteExporter +</div> +</body> +</html>
![https://cwiki.apache.org/confluence/images/icons/notep_16.gif"](https://cwiki.apache.org/confluence/images/icons/notep_16.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/browse_space.gif"](https://cwiki.apache.org/confluence/images/icons/browse_space.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/add_page_16.gif"](https://cwiki.apache.org/confluence/images/icons/add_page_16.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/add_blogentry_16.gif"](https://cwiki.apache.org/confluence/images/icons/add_blogentry_16.gif"){kind=link}
