This is an automated email from the ASF dual-hosted git repository. git-site-role pushed a commit to branch asf-site in repository https://gitbox.apache.org/repos/asf/struts-site.git
The following commit(s) were added to refs/heads/asf-site by this push: new 236b7c4 Automatic Site Publish by Buildbot 236b7c4 is described below commit 236b7c45b094e47cdf0c4163442200e93776cc10 Author: buildbot <us...@infra.apache.org> AuthorDate: Wed Jan 20 08:19:16 2021 +0000 Automatic Site Publish by Buildbot --- .../ajax-client-side-validation.html | 242 +++++++++------------ .../attachments/struts2-ajax-vali-flow.png | Bin 0 -> 54364 bytes output/core-developers/client-side-validation.html | 2 +- .../pure-java-script-client-side-validation.html | 16 +- 4 files changed, 102 insertions(+), 158 deletions(-) diff --git a/output/core-developers/ajax-client-side-validation.html b/output/core-developers/ajax-client-side-validation.html index a5a06c4..26edf33 100644 --- a/output/core-developers/ajax-client-side-validation.html +++ b/output/core-developers/ajax-client-side-validation.html @@ -129,36 +129,53 @@ <section class="col-md-12"> <a href="index.html" title="back to Core Developers Guide"><< back to Core Developers Guide</a> <a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/core-developers/ajax-client-side-validation.md" title="Edit this page on GitHub">Edit on GitHub</a> - <h1 id="ajax-client-side-validation">AJAX Client Side Validation</h1> - -<p>This validation mode only works with the <em>ajax theme</em></p> + <h1 class="no_toc" id="ajax-client-side-validation">AJAX Client Side Validation</h1> + +<ul id="markdown-toc"> + <li><a href="#description" id="markdown-toc-description">Description</a></li> + <li><a href="#ajax-validation" id="markdown-toc-ajax-validation">AJAX Validation</a></li> + <li><a href="#example" id="markdown-toc-example">Example</a> <ul> + <li><a href="#create-the-action-class" id="markdown-toc-create-the-action-class">Create the action class</a></li> + <li><a href="#map-the-action" id="markdown-toc-map-the-action">Map the Action</a></li> + <li><a href="#create-the-jsp" id="markdown-toc-create-the-jsp">Create the JSP</a></li> + <li><a href="#custom-theme" id="markdown-toc-custom-theme">Custom Theme</a></li> + <li><a href="#css" id="markdown-toc-css">CSS</a></li> + <li><a href="#javascript" id="markdown-toc-javascript">JavaScript</a></li> + <li><a href="#how-it-works" id="markdown-toc-how-it-works">How it works</a></li> + <li><a href="#jsonvalidationinterceptor-parameters" id="markdown-toc-jsonvalidationinterceptor-parameters">JSONValidationInterceptor parameters</a></li> + <li><a href="#flow-chart-of-ajax-validation" id="markdown-toc-flow-chart-of-ajax-validation">Flow chart of AJAX validation</a></li> + </ul> + </li> +</ul> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> +<h2 id="description">Description</h2> -<p>AJAX-based client side validation improves upon <a href="#PAGE_14262">Pure JavaScript Client Side Validation</a> by using a combination of JavaScript, DOM manipulation, and remote server communication. Unlike the pure client side implementation, AJAX-based validation communicates with the server. This means all your validation rules that worked when submitting a form will still work within the browser.</p> +<p>AJAX-based client side validation improves upon <a href="pure-java-script-client-side-validation">Pure JavaScript Client Side Validation</a> +by using a combination of JavaScript, DOM manipulation, and remote server communication. Unlike the pure client side +implementation, AJAX-based validation communicates with the server. This means all your validation rules that worked +when submitting a form will still work within the browser.</p> -<p>The validation occurs on each <strong>onblur</strong> event for each form element. As each user types in some values and moves to the next form element, the value (and all other values previously entered) will be sent to the server for validation. The entire validation stack is run, including visitor validators and your action’s validate() method.</p> +<p>The validation occurs on each <strong>onblur</strong> event for each form element. As each user types in some values and moves to +the next form element, the value (and all other values previously entered) will be sent to the server for validation. +The entire validation stack is run, including visitor validators and your action’s <code class="highlighter-rouge">validate()</code> method.</p> <p>If there is an error, like the pure implementation, the HTML and DOM will be updated immediately.</p> -<p>For an example of this, see <em>AJAX Validation</em> .</p> - -<p><strong>AJAX Validation</strong></p> +<h2 id="ajax-validation">AJAX Validation</h2> -<p><strong>Description</strong></p> +<p>Struts provides <a href="client-side-validation">client side validation</a>(using JavaScript) for a few validators. Using AJAX +validation, all <a href="validation#bundled-validators">validators</a> available to the application on the server side can be used +without forcing the page to reload, just to show validation errors. AJAX validation has a server side, which is in included +in <a href="../plugins/json/">JSON Plugin</a> (an interceptor and a result). Client side must be handled by applications themself. +One reason for that is there are too many JavaScript frameworks and libraries. Struts has no preference which of them +you use. Previous versions of Struts included a client side which was relying on the Dojo JS framework and was located +in Struts Dojo plugin. That has been deprecated for a long time and was eventually removed.</p> -<p>Struts provides <a href="client-side-validation.html">client side validation</a>(using JavaScript) for a few validators. Using AJAX validation, all <a href="#PAGE_14292">validators</a> available to the application on the server side can be used without forcing the page to reload, just to show validation errors. AJAX validation has a server side, which is in included in <em>JSON Plugin</em> (an interceptor and a result). Client side must be handled by applictions themself. One reason [...] +<h2 id="example">Example</h2> -<p><strong>Example</strong></p> +<p>This example is taken from the Struts Showcase Application.</p> -<p>This example is taken from the Struts showcase application.</p> - -<p><strong>Create the action class</strong></p> +<h3 id="create-the-action-class">Create the action class</h3> <div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">public</span> <span class="kd">class</span> <span class="nc">AjaxFormSubmitAction</span> <span class="kd">extends</span> <span class="n">ActionSupport</span> <span class="o">{</span> <span class="kd">private</span> <span class="n">String</span> <span class="n">requiredValidatorField</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span> @@ -254,14 +271,12 @@ <span class="o">}</span> </code></pre></div></div> -<p> </p> +<h3 id="map-the-action">Map the Action</h3> -<p><strong>Map the Action</strong></p> +<p>Note that is is not necessary when using <a href="../plugins/convention/">Convention Plugin</a>.</p> -<p>Note that is is not necessary when using <em>Convention Plugin</em> .</p> +<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp"><!DOCTYPE struts PUBLIC "-//Apache Software Foundation//DTD Struts Configuration 2.5//EN" "http://struts.apache.org/dtds/struts-2.5.dtd"></span> -<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp"><!DOCTYPE struts PUBLIC "-//Apache Software Foundation//DTD Struts Configuration 2.0//EN" "http://struts.apache.org/dtds/struts-2.0.dtd"></span> - <span class="nt"><struts></span> <span class="nt"><package></span> <span class="nt"><action</span> <span class="na">name=</span><span class="s">"ajaxFormSubmit"</span> <span class="na">class=</span><span class="s">"org.apache.struts2.showcase.validation.AjaxFormSubmitAction"</span><span class="nt">></span> @@ -270,12 +285,16 @@ <span class="nt"><result</span> <span class="na">type=</span><span class="s">"jsonActionRedirect"</span><span class="nt">></span>ajaxFormSubmitSuccess<span class="nt"></result></span> <span class="nt"></action></span> <span class="nt"></package></span> - </code></pre></div></div> -<p>AJAX validation is performed by the <em>jsonValidation</em> interceptor. This interceptor is included in the <em>jsonValidationWorkflowStack</em> , and is required in order to perform AJAX validation. Normal results(input, success, etc) should be provided for the action in the case that someone tries to access the action directly, in which case normal validation will be triggered. So, how does the <em>jsonValidation</em> know that it must perform AJAX validation vs regular validatio [...] +<p>AJAX validation is performed by the <a href="../plugins/json/">jsonValidation</a> interceptor. This interceptor is included in +the <em>jsonValidationWorkflowStack</em>, and is required in order to perform AJAX validation. Normal results (input, success, etc) +should be provided for the action in the case that someone tries to access the action directly, in which case normal v +alidation will be triggered. So, how does the <em>jsonValidation</em> know that it must perform AJAX validation vs regular validation? +We will see that in a minute, but you don’t need to know that in order to use AJAX validation. Same applies for specialized + Redirect Result Type <em>jsonActionRedirect</em>.</p> -<p><strong>Create the JSP</strong></p> +<h3 id="create-the-jsp">Create the JSP</h3> <pre><code class="language-jsp"><%@taglib prefix="s" uri="/struts-tags" %> <html> @@ -303,53 +322,36 @@ <s:submit label="Submit" cssClass="btn btn-primary"/> </s:form> </body> -</html> +</html> </code></pre> <p>Things to note on this JSP:</p> <ul> - <li> - <p>The <em>form</em> tag <strong>does not</strong> have <em>validate</em> set to <em>true</em> , which would perform client validation before the AJAX validation.</p> - </li> - <li> - <p>It uses a customized theme <em>ajaxErrorContainers</em> . The default Struts themes generate HTML-Elements to show validation errors only if errors are present when page is created on server side. But in order to show validation errors that arrive later via AJAX it is necessary to have error-container elements in DOM always.</p> - </li> + <li>The <em>form</em> tag <strong>does not</strong> have <em>validate</em> set to <em>true</em>, which would perform client validation before the AJAX validation.</li> + <li>It uses a customized theme <em>ajaxErrorContainers</em>. The default Struts themes generate HTML-Elements to show validation +errors only if errors are present when page is created on server side. But in order to show validation errors that +arrive later via AJAX it is necessary to have error-container elements in DOM always.</li> </ul> -<p>What happens if validation succeeds? That depends on your request parameters and action configuration. If you are using <em>jsonActionRedirect</em> result mentioned above the action will be executed while AJAX request is active and respond with JSON providing a new URL to load. Otherwise the AJAX response will be empty and the form must be submitted a 2nd time but as usual request, not AJAX.</p> - -<table> - <tbody> - <tr> - <td>Setting <em>validate</em> to <em>true</em> in the <em>form</em> tag will enable client side, JavaScript validation, which can be used along with AJAX validation (runs before the AJAX validation).</td> - </tr> - </tbody> -</table> +<p>What happens if validation succeeds? That depends on your request parameters and action configuration. If you are using +<em>jsonActionRedirect</em> result mentioned above the action will be executed while AJAX request is active and respond with +JSON providing a new URL to load. Otherwise the AJAX response will be empty and the form must be submitted a 2nd time +but as usual request, not AJAX.</p> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> +<p>| Setting <em>validate</em> to <em>true</em> in the <em>form</em> tag will enable client side, JavaScript validation, which can be used along + with AJAX validation (runs before the AJAX validation).</p> -<p><strong>Custom Theme</strong></p> +<h3 id="custom-theme">Custom Theme</h3> -<p>In this sample the <em>custom theme</em> is based on <em>xhtml</em> theme. It is required to override 3 FTL files.</p> +<p>In this sample the <em>custom theme</em> is based on <em>xhtml</em> theme. It is required to override 3 FTL files.</p> -<blockquote> - <p>theme.properties</p> -</blockquote> +<p><strong>theme.properties</strong></p> <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>parent = xhtml </code></pre></div></div> -<p> </p> - -<blockquote> - <p>actionerror.ftl</p> -</blockquote> +<p><strong>actionerror.ftl</strong></p> <pre><code class="language-ftl"><#-- Make sure element is always present. To be filled later via JS. @@ -377,11 +379,7 @@ </ul> </code></pre> -<p> </p> - -<blockquote> - <p>controlfooter.ftl</p> -</blockquote> +<p><strong>controlfooter.ftl</strong></p> <pre><code class="language-ftl">${parameters.after!}<#t/> </td><#lt/> @@ -402,13 +400,9 @@ </#if> </code></pre> -<p> </p> - -<blockquote> - <p>controlheader-core.ftl</p> -</blockquote> +<p><strong>controlheader-core.ftl</strong></p> -<pre><code class="language-ftl"> <#-- +<pre><code class="language-ftl"><#-- Always include elements to show errors. They may be filled later via AJAX. --> <#assign hasFieldErrors = parameters.name?? && fieldErrors?? && fieldErrors[parameters.name]??/> @@ -468,9 +462,10 @@ ${parameters.labelseparator!":"?html}<#t/> </#if> </code></pre> -<p><strong>CSS</strong></p> +<h3 id="css">CSS</h3> -<p>To show users some nice visual feedback while waiting for AJAX response you can use a little CSS. Remember to include the referenced <em>indicator.gif</em> .</p> +<p>To show users some nice visual feedback while waiting for AJAX response you can use a little CSS. Remember to include +the referenced <em>indicator.gif</em>.</p> <div class="language-css highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nc">.ajaxVisualFeedback</span> <span class="p">{</span> <span class="nl">width</span><span class="p">:</span> <span class="m">16px</span><span class="p">;</span> @@ -481,11 +476,10 @@ ${parameters.labelseparator!":"?html}<#t/> <span class="p">}</span> </code></pre></div></div> -<p> </p> - -<p><strong>JavaScript</strong></p> +<h3 id="javascript">JavaScript</h3> -<p>Now this is where the magic happens. Here <em>jQuery</em> is used to register an eventhandler which intercepts form submits. It takes care of hiding validation errors that might be present, submit the form via AJAX and handle JSON responses.</p> +<p>Now this is where the magic happens. Here <em>jQuery</em> is used to register an eventhandler which intercepts form submits. +It takes care of hiding validation errors that might be present, submit the form via AJAX and handle JSON responses.</p> <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="cm">/** * Validates form per AJAX. To be called as onSubmit handler. @@ -539,7 +533,7 @@ ${parameters.labelseparator!":"?html}<#t/> <span class="c1">// a real error occurred -> show user an error message</span> <span class="nx">_handleValidationResult</span><span class="p">(</span><span class="nx">_form</span><span class="p">,</span> <span class="p">{</span><span class="na">errors</span><span class="p">:</span> <span class="p">[</span><span class="s1">'Network or server error!'</span><span class="p">]})</span> <span class="p">}</span> - <span class="p">}</span> + <span class="p">}</span> <span class="p">}</span> <span class="c1">// send request, after delay to make sure everybody notices the visual feedback :)</span> <span class="nb">window</span><span class="p">.</span><span class="nx">setTimeout</span><span class="p">(</span><span class="kd">function</span><span class="p">()</span> <span class="p">{</span> @@ -592,15 +586,18 @@ ${parameters.labelseparator!":"?html}<#t/> <span class="p">});</span> </code></pre></div></div> -<p> </p> - -<p><strong>How it works</strong></p> +<h3 id="how-it-works">How it works</h3> -<p><em>jsonValidation</em> interceptor must be placed on a stack, following the <em>validation</em> interceptor. The interceptor itself won’t perform any validation, but will check for validation errors on the action being invoked (assuming that the action is ValidationAware).</p> +<p><em>jsonValidation</em> interceptor must be placed on a stack, following the <em>validation</em> interceptor. The interceptor itself +won’t perform any validation, but will check for validation errors on the action being invoked (assuming that the action +is <code class="highlighter-rouge">ValidationAware</code>).</p> <p>If you just want to use AJAX validation, without knowing the implementation details, you can skip this section.</p> -<p>When the <em>jsonValidation</em> interceptor is invoked, it will look for a parameter named <em>struts.enableJSONValidation</em> , this parameter <strong>must</strong> be set to <em>true</em> , otherwise the interceptor won’t do anything. Then the interceptor will look for a parameter named <em>struts.validateOnly</em> , if this parameter exists, is set to <em>true</em> , and there are validation errors (o action errors) they will be serialized into JSON in the form:</p> +<p>When the <em>jsonValidation</em> interceptor is invoked, it will look for a parameter named <em>struts.enableJSONValidation</em>, +this parameter <strong>must</strong> be set to <em>true</em>, otherwise the interceptor won’t do anything. Then the interceptor will look +for a parameter named <em>struts.validateOnly</em>, if this parameter exists, is set to <em>true</em>, and there are validation +errors (action errors) they will be serialized into JSON in the form:</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> </span><span class="s2">"errors"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"Global Error 1"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Global Error 2"</span><span class="p">],</span><span class="w"> @@ -609,97 +606,54 @@ ${parameters.labelseparator!":"?html}<#t/> </span><span class="s2">"field1"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"Field 2 Error 1"</span><span class="p">,</span><span class="w"> </span><span class="s2">"Field 2 Error 2"</span><span class="p">]</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> - </span></code></pre></div></div> -<p>If the action implements the <em>ModelDrive</em> interface, “model.” will be stripped from the field names in the returned JSON. If validation succeeds (and <em>struts.validateOnly</em> is true), an empty JSON string will be returned:</p> +<p>If the action implements the <em>ModelDrive</em> interface, “model.” will be stripped from the field names in the returned JSON. +If validation succeeds (and <em>struts.validateOnly</em> is true), an empty JSON string will be returned:</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{}</span><span class="w"> - </span></code></pre></div></div> -<p>If <em>struts.validateOnly</em> is false the action and result are executed. In this case <em>jsonActionRedirect</em> result is very useful. It creates a JSON response in the form:</p> +<p>If <em>struts.validateOnly</em> is false the action and result are executed. In this case <em>jsonActionRedirect</em> result is very +useful. It creates a JSON response in the form:</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="s2">"location"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<url to be loaded next>"</span><span class="p">}</span><span class="w"> - </span></code></pre></div></div> <blockquote> - -</blockquote> - -<blockquote> - -</blockquote> - -<blockquote> - <p>Remember to set struts.enableJSONValidation=true in the request to enable AJAX validation</p> -</blockquote> - -<blockquote> - + <p>Remember to set <code class="highlighter-rouge">struts.enableJSONValidation=true</code> in the request to enable AJAX validation</p> </blockquote> -<p><strong>JSONValidationInterceptor parameters</strong></p> +<h3 id="jsonvalidationinterceptor-parameters">JSONValidationInterceptor parameters</h3> <p>The following request parameters can be used to enable exposing validation errors:</p> <ul> - <li> - <p><strong>struts.enableJSONValidation</strong> - a request parameter must be set to <strong>true</strong> to use this interceptor</p> - </li> - <li> - <p><strong>struts.validateOnly</strong> - If the request has this parameter, execution will return after validation (action won’t be executed). If <strong>struts.validateOnly</strong> is set to false you may want to use <em>JSONActionRedirectResult</em></p> - </li> - <li> - <p><strong>struts.JSONValidation.no.encoding</strong> - If the request has this parameter set to <strong>true,</strong> the character encoding will <strong>NOT</strong> be set on the response - is needed in portlet environment</p> - </li> + <li><strong>struts.enableJSONValidation</strong> - a request parameter must be set to <strong>true</strong> to use this interceptor</li> + <li><strong>struts.validateOnly</strong> - If the request has this parameter, execution will return after validation (action won’t be executed). +If <strong>struts.validateOnly</strong> is set to false you may want to use <em>JSONActionRedirectResult</em></li> + <li><strong>struts.JSONValidation.no.encoding</strong> - If the request has this parameter set to <strong>true,</strong> the character encoding +will <strong>NOT</strong> be set on the response - is needed in portlet environment</li> </ul> <p>You can override names of these parameters by specifying the following parameters when setting up a stack:</p> <ul> - <li> - <p><strong>validateJsonParam</strong> - to override name of <strong>struts.enableJSONValidation</strong>** -**</p> - </li> - <li> - <p><strong>validateOnlyParam</strong> - to override name of <strong>struts.validateOnly</strong></p> - </li> - <li> - <p><strong>noEncodingSetParam</strong> - to override name of <strong>struts.JSONValidation.no.encoding</strong></p> - </li> - <li> - <p><strong>validationFailedStatus</strong> - status to be set on response when there are validation errors, by default <strong>400</strong></p> - </li> + <li><strong>validateJsonParam</strong> to override name of <strong>struts.enableJSONValidation</strong></li> + <li><strong>validateOnlyParam</strong> to override name of <strong>struts.validateOnly</strong></li> + <li><strong>noEncodingSetParam</strong> to override name of <strong>struts.JSONValidation.no.encoding</strong></li> + <li><strong>validationFailedStatus</strong> status to be set on response when there are validation errors, by default <strong>400</strong></li> </ul> -<p>** -**</p> +<p>Parameters overriding is available since Struts 2.5.9</p> -<p> Parameters overriding is available since Struts 2.5.9</p> - -<p><strong>Flow chart of AJAX validation</strong></p> +<h3 id="flow-chart-of-ajax-validation">Flow chart of AJAX validation</h3> <p>Some details are omitted, like results used.</p> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> - <p>As explained above: there is a case where form is submitted twice, one time as AJAX with validation only and another time as usual submit.</p> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> - -<p><em>struts2-ajax-vali-flow.png</em></p> +<p><img src="attachments/struts2-ajax-vali-flow.png" alt="" /></p> </section> </article> diff --git a/output/core-developers/attachments/struts2-ajax-vali-flow.png b/output/core-developers/attachments/struts2-ajax-vali-flow.png new file mode 100644 index 0000000..8da0331 Binary files /dev/null and b/output/core-developers/attachments/struts2-ajax-vali-flow.png differ diff --git a/output/core-developers/client-side-validation.html b/output/core-developers/client-side-validation.html index 7cfdafc..fbbb8a1 100644 --- a/output/core-developers/client-side-validation.html +++ b/output/core-developers/client-side-validation.html @@ -199,7 +199,7 @@ if the validation system actually “requires” the field or not.</p> <tbody> <tr> <td><a href="ajax-client-side-validation">AJAX Client Side Validation</a></td> - <td>Used by the <em>ajax theme</em></td> + <td>Use to used by the <em>ajax theme</em></td> </tr> </tbody> </table> diff --git a/output/core-developers/pure-java-script-client-side-validation.html b/output/core-developers/pure-java-script-client-side-validation.html index 46d5abc..33522ad 100644 --- a/output/core-developers/pure-java-script-client-side-validation.html +++ b/output/core-developers/pure-java-script-client-side-validation.html @@ -167,19 +167,9 @@ some values will be considered acceptable by the JavaScript code but will be mar for properly manipulating the HTML DOM to display the error message inline. The JavaScript that is responsible for doing this logic is <code class="highlighter-rouge">validation.js</code> and can be found in each theme.</p> -<table> - <tbody> - <tr> - <td>Errors are reported using the default validation message, not the internationalized version that the server-side might</td> - </tr> - <tr> - <td>be aware of. This is a known issue. You may want to try the <a href="ajax-client-side-validation">AJAX Client Side Validation</a></td> - </tr> - <tr> - <td>for messages that are fully internationalized.</td> - </tr> - </tbody> -</table> +<p>| Errors are reported using the default validation message, not the internationalized version that the server-side might + be aware of. This is a known issue. You may want to try the <a href="ajax-client-side-validation">AJAX Client Side Validation</a> + for messages that are fully internationalized.</p> <h2 id="additional-validator-support">Additional Validator Support</h2>