You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by ad...@apache.org on 2014/04/24 21:41:18 UTC
svn commit: r1589849 [5/6] - in /wicket/common/site/trunk/_site/guide/guide:
./ pages/ src/docs/guide/ src/docs/guide/forms2/ src/docs/guide/helloWorld/
src/docs/img/
Modified: wicket/common/site/trunk/_site/guide/guide/repeaters.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/repeaters.html?rev=1589849&r1=1589848&r2=1589849&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/repeaters.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/repeaters.html Thu Apr 24 19:41:13 2014
@@ -348,7 +348,7 @@ Wicket provides also component PageableL
<div id="footer">
Copyright © 2013-2014 â <a href="http://www.apache.org/" target="_blank">The Apache Software Foundation</a>
- â <b style="color:#E8590A !important;">(Generated on: 2014-04-10)</b>
+ â <b style="color:#E8590A !important;">(Generated on: 2014-04-24)</b>
</div>
Modified: wicket/common/site/trunk/_site/guide/guide/requestProcessing.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/requestProcessing.html?rev=1589849&r1=1589848&r2=1589849&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/requestProcessing.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/requestProcessing.html Thu Apr 24 19:41:13 2014
@@ -309,7 +309,7 @@ Remember that invalidateNow() will immed
<div id="footer">
Copyright © 2013-2014 â <a href="http://www.apache.org/" target="_blank">The Apache Software Foundation</a>
- â <b style="color:#E8590A !important;">(Generated on: 2014-04-10)</b>
+ â <b style="color:#E8590A !important;">(Generated on: 2014-04-24)</b>
</div>
Modified: wicket/common/site/trunk/_site/guide/guide/resources.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/resources.html?rev=1589849&r1=1589848&r2=1589849&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/resources.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/resources.html Thu Apr 24 19:41:13 2014
@@ -452,7 +452,7 @@ In this chapter we have learnt how to ma
<div id="footer">
Copyright © 2013-2014 â <a href="http://www.apache.org/" target="_blank">The Apache Software Foundation</a>
- â <b style="color:#E8590A !important;">(Generated on: 2014-04-10)</b>
+ â <b style="color:#E8590A !important;">(Generated on: 2014-04-24)</b>
</div>
Modified: wicket/common/site/trunk/_site/guide/guide/security.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/security.html?rev=1589849&r1=1589848&r2=1589849&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/security.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/security.html Thu Apr 24 19:41:13 2014
@@ -457,7 +457,7 @@ Application class <code>AuthenticatedWeb
<div id="footer">
Copyright © 2013-2014 â <a href="http://www.apache.org/" target="_blank">The Apache Software Foundation</a>
- â <b style="color:#E8590A !important;">(Generated on: 2014-04-10)</b>
+ â <b style="color:#E8590A !important;">(Generated on: 2014-04-24)</b>
</div>
Modified: wicket/common/site/trunk/_site/guide/guide/single.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/single.html?rev=1589849&r1=1589848&r2=1589849&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/single.html (original)
+++ wicket/common/site/trunk/_site/guide/guide/single.html Thu Apr 24 19:41:13 2014
@@ -260,23 +260,25 @@ function addJsClass(el) {
<div class="toc-item" style="margin-left:10px"><a href="#forms2_3"><strong>12.3</strong><span>Input value conversion</span></a></div>
- <div class="toc-item" style="margin-left:10px"><a href="#forms2_4"><strong>12.4</strong><span>Submit form with an IFormSubmittingComponent</span></a></div>
+ <div class="toc-item" style="margin-left:10px"><a href="#forms2_4"><strong>12.4</strong><span>Validation with JSR 303</span></a></div>
- <div class="toc-item" style="margin-left:10px"><a href="#forms2_5"><strong>12.5</strong><span>Nested forms</span></a></div>
+ <div class="toc-item" style="margin-left:10px"><a href="#forms2_5"><strong>12.5</strong><span>Submit form with an IFormSubmittingComponent</span></a></div>
- <div class="toc-item" style="margin-left:10px"><a href="#forms2_6"><strong>12.6</strong><span>Multi-line text input</span></a></div>
+ <div class="toc-item" style="margin-left:10px"><a href="#forms2_6"><strong>12.6</strong><span>Nested forms</span></a></div>
- <div class="toc-item" style="margin-left:10px"><a href="#forms2_7"><strong>12.7</strong><span>File upload</span></a></div>
+ <div class="toc-item" style="margin-left:10px"><a href="#forms2_7"><strong>12.7</strong><span>Multi-line text input</span></a></div>
- <div class="toc-item" style="margin-left:10px"><a href="#forms2_8"><strong>12.8</strong><span>Creating complex form components with FormComponentPanel</span></a></div>
+ <div class="toc-item" style="margin-left:10px"><a href="#forms2_8"><strong>12.8</strong><span>File upload</span></a></div>
- <div class="toc-item" style="margin-left:10px"><a href="#forms2_9"><strong>12.9</strong><span>Stateless form</span></a></div>
+ <div class="toc-item" style="margin-left:10px"><a href="#forms2_9"><strong>12.9</strong><span>Creating complex form components with FormComponentPanel</span></a></div>
- <div class="toc-item" style="margin-left:10px"><a href="#forms2_10"><strong>12.10</strong><span>Working with radio buttons and checkboxes</span></a></div>
+ <div class="toc-item" style="margin-left:10px"><a href="#forms2_10"><strong>12.10</strong><span>Stateless form</span></a></div>
- <div class="toc-item" style="margin-left:10px"><a href="#forms2_11"><strong>12.11</strong><span>Selecting multiple values with ListMultipleChoices and Palette</span></a></div>
+ <div class="toc-item" style="margin-left:10px"><a href="#forms2_11"><strong>12.11</strong><span>Working with radio buttons and checkboxes</span></a></div>
- <div class="toc-item" style="margin-left:10px"><a href="#forms2_12"><strong>12.12</strong><span>Summary</span></a></div>
+ <div class="toc-item" style="margin-left:10px"><a href="#forms2_12"><strong>12.12</strong><span>Selecting multiple values with ListMultipleChoices and Palette</span></a></div>
+
+ <div class="toc-item" style="margin-left:10px"><a href="#forms2_13"><strong>12.13</strong><span>Summary</span></a></div>
<div class="toc-item" style="margin-left:0px"><a href="#repeaters"><strong>13</strong><span>Displaying multiple items with repeaters</span></a></div>
@@ -548,7 +550,8 @@ Both frameworks share the same component
<h2 id="helloWorld_1">4.1 Wicket distribution and modules</h2>
-Wicket is available as a binary package on the main site <a href="http://wicket.apache.org" target="blank">http://wicket.apache.org</a> . Inside this archive we can find the distribution jars of the framework. Each jar corresponds to a sub-module of the framework. The following table reports these modules along with a short description of their purpose and with the related dependencies:<p class="paragraph"/><table class="wiki-table" cellpadding="0" cellspacing="0" border="0"><tr><th><strong class="bold">Module'sname</strong></th><th><strong class="bold">Description</strong></th><th><strong class="bold">Dependencies</strong></th></tr><tr class="table-odd"><td>wicket-core</td><td>Contains the main classes of the framework, like class <code>Component</code> and <code>Application</code>.</td><td>wicket-request, wicket-util</td></tr><tr class="table-even"><td>wicket-request</td><td>This module contains the classes involved into web request processing.</td><td>wicket-util</td></tr><tr cla
ss="table-odd"><td>wicket-util</td><td>Contains general-purpose utility classes for functional areas such as I/O, lang, string manipulation, security, etc...</td><td>None</td></tr><tr class="table-even"><td>wicket-datetime</td><td>Contains special purpose components designed to work with date and time.</td><td>wicket-core</td></tr><tr class="table-odd"><td>wicket-devutils</td><td>Contains utility classes and components to help developers with tasks such as debugging, class inspection and so on.</td><td>wicket-core, wicket-extensions</td></tr><tr class="table-even"><td>wicket-extensions</td><td>Contains a vast set of built-in components to build a rich UI for our web application (Ajax support is part of this module).</td><td>wicket-core</td></tr><tr class="table-odd"><td>wicket-auth-roles</td><td>Provides support for role-based authorization.</td><td>wicket-core</td></tr><tr class="table-even"><td>wicket-ioc</td><td>This module provides common classes to support Inversion Of Control.
It's used by both Spring and Guice integration module.</td><td>wicket-core</td></tr><tr class="table-odd"><td>wicket-guice</td><td>This module provides integration with the dependency injection framework developed by Google.</td><td>wicket-core, wicket-ioc</td></tr><tr class="table-even"><td>wicket-spring</td><td>This module provides integration with Spring framework.</td><td>wicket-core, wicket-ioc</td></tr><tr class="table-odd"><td>wicket-velocity</td><td>This module provides panels and utility class to integrate Wicket with Velocity template engine.</td><td>wicket-core</td></tr><tr class="table-even"><td>wicket-jmx</td><td>This module provides panels and utility class to integrate Wicket with Java Management Extensions.</td><td>wicket-core</td></tr><tr class="table-odd"><td>wicket-objectsizeof-agent</td><td>Provides integration with Java agent libraries and instrumentation tools.</td><td>wicket-core</td></tr></table><p class="paragraph"/>Please note that the core module depends
on the utility and request modules, hence it cannot be used without them.
+Wicket is available as a binary package on the main site <a href="http://wicket.apache.org" target="blank">http://wicket.apache.org</a> . Inside this archive we can find the distribution jars of the framework. Each jar corresponds to a sub-module of the framework. The following table reports these modules along with a short description of their purpose and with the related dependencies:<p class="paragraph"/><table class="wiki-table" cellpadding="0" cellspacing="0" border="0"><tr><th><strong class="bold">Module'sname</strong></th><th><strong class="bold">Description</strong></th><th><strong class="bold">Dependencies</strong></th></tr><tr class="table-odd"><td>wicket-core</td><td>Contains the main classes of the framework, like class <code>Component</code> and <code>Application</code>.</td><td>wicket-request, wicket-util</td></tr><tr class="table-even"><td>wicket-request</td><td>This module contains the classes involved into web request processing.</td><td>wicket-util</td></tr><tr cla
ss="table-odd"><td>wicket-util</td><td>Contains general-purpose utility classes for functional areas such as I/O, lang, string manipulation, security, etc...</td><td>None</td></tr><tr class="table-even"><td>wicket-datetime</td><td>Contains special purpose components designed to work with date and time.</td><td>wicket-core</td></tr><tr class="table-odd"><td>wicket-bean-validation</td><td>Provides support for JSR 303 standard validation.</td><td>wicket-core</td></tr><tr class="table-even"><td>wicket-devutils</td><td>Contains utility classes and components to help developers with tasks such as debugging, class inspection and so on.</td><td>wicket-core, wicket-extensions</td></tr><tr class="table-odd"><td>wicket-extensions</td><td>Contains a vast set of built-in components to build a rich UI for our web application (Ajax support is part of this module).</td><td>wicket-core</td></tr><tr class="table-even"><td>wicket-auth-roles</td><td>Provides support for role-based authorization.</td><t
d>wicket-core</td></tr><tr class="table-odd"><td>wicket-ioc</td><td>This module provides common classes to support Inversion Of Control. It's used by both Spring and Guice integration module.</td><td>wicket-core</td></tr><tr class="table-even"><td>wicket-guice</td><td>This module provides integration with the dependency injection framework developed by Google.</td><td>wicket-core, wicket-ioc</td></tr><tr class="table-odd"><td>wicket-spring</td><td>This module provides integration with Spring framework.</td><td>wicket-core, wicket-ioc</td></tr><tr class="table-even"><td>wicket-velocity</td><td>This module provides panels and utility class to integrate Wicket with Velocity template engine.</td><td>wicket-core</td></tr><tr class="table-odd"><td>wicket-jmx</td><td>This module provides panels and utility class to integrate Wicket with Java Management Extensions.</td><td>wicket-core</td></tr><tr class="table-even"><td>wicket-objectsizeof-agent</td><td>Provides integration with Java agent
libraries and instrumentation tools.</td><td>wicket-core</td></tr></table><p class="paragraph"/>Please note that the core module depends on the utility and request modules, hence it cannot be used without them.
+
<h2 id="helloWorld_2">4.2 Configuration of Wicket applications</h2>
@@ -1904,7 +1907,33 @@ If the user input can not be converted t
</blockquote>
-<h2 id="forms2_4">12.4 Submit form with an IFormSubmittingComponent</h2>
+<h2 id="forms2_4">12.4 Validation with JSR 303</h2>
+Standard JSR 303 defines a set of annotations and APIs to validate our domain objects at field-level. Wicket has introduced an experimental support for this standard since version 6.4.0 and with version 6.14.0 it has became an official Wicket model (named <code>wicket-bean-validation</code>).
+In this paragraph we will see the basic steps needed to use JSR 303 validation in our Wicket application. Code snippets are from example project <code>JSR303validation</code>.<p class="paragraph"/>In the example application we have a form to insert the data for a new <code>Person</code> bean and its relative <code>Address</code>. The code for class <code>Person</code> is the following<p class="paragraph"/><div class="code"><pre><span class="java-keyword">public</span> class Person <span class="java-keyword">implements</span> Serializable{<p class="paragraph"/> @NotNull
+ <span class="java-keyword">private</span> <span class="java-object">String</span> name;<p class="paragraph"/> //regular expression to validate an email address
+ @Pattern(regexp = <span class="java-quote">"^[_A-Za-z0-9-]+(.[_A-Za-z0-9-]+)*[A-Za-z0-9-]+(.[A-Za-z0-9-]+)*((.[A-Za-z]{2,}){1}$)"</span>)
+ <span class="java-keyword">private</span> <span class="java-object">String</span> email;<p class="paragraph"/> @Range(min = 18, max = 150)
+ <span class="java-keyword">private</span> <span class="java-object">int</span> age;<p class="paragraph"/> <code>Past </code>NotNull
+ <span class="java-keyword">private</span> Date birthDay;<p class="paragraph"/> @NotNull
+ <span class="java-keyword">private</span> Address address;
+}</pre></div><p class="paragraph"/>You can note the JSR 303 annotations used in the code above to declare validation constraints on class fields. Class <code>Address</code> has the following code:<p class="paragraph"/><div class="code"><pre><span class="java-keyword">public</span> class Address <span class="java-keyword">implements</span> Serializable {<p class="paragraph"/> @NotNull
+ <span class="java-keyword">private</span> <span class="java-object">String</span> city;<p class="paragraph"/> @NotNull
+ <span class="java-keyword">private</span> <span class="java-object">String</span> street;<p class="paragraph"/> @Pattern(regexp = "\\d+<span class="java-quote">", message = "</span>{address.invalidZipCode}")
+ <span class="java-keyword">private</span> <span class="java-object">String</span> zipCode;
+}</pre></div><p class="paragraph"/>You might have noted that in class <code>Address</code> we have used annotation <code>Pattern using also attribute </code>message<code> which contains the key of the bundle to use for validation message. Our custom bundle is contained inside </code>HomePage.properties@:<p class="paragraph"/><div class="code"><pre>address.invalidZipCode=The inserted zip code is not valid.</pre></div><p class="paragraph"/>To tell Wicket to use JSR 303, we must register bean validator on Application's startup:<p class="paragraph"/><div class="code"><pre><span class="java-keyword">public</span> class WicketApplication <span class="java-keyword">extends</span> WebApplication {
+ @Override
+ <span class="java-keyword">public</span> void init(){
+ <span class="java-keyword">super</span>.init();<p class="paragraph"/> <span class="java-keyword">new</span> BeanValidationConfiguration().configure(<span class="java-keyword">this</span>);
+ }
+}</pre></div><p class="paragraph"/>The last step to harness JSR 303 annotations is to add validator <code>org.apache.wicket.bean.validation.PropertyValidator</code> to our corresponding form components:<p class="paragraph"/><div class="code"><pre><span class="java-keyword">public</span> HomePage(<span class="java-keyword">final</span> PageParameters parameters) {
+ <span class="java-keyword">super</span>(parameters);<p class="paragraph"/> setDefaultModel(<span class="java-keyword">new</span> CompoundPropertyModel<Person>(<span class="java-keyword">new</span> Person()));<p class="paragraph"/> Form<<span class="java-object">Void</span>> form = <span class="java-keyword">new</span> Form<<span class="java-object">Void</span>>(<span class="java-quote">"form"</span>);<p class="paragraph"/> form.add(<span class="java-keyword">new</span> TextField(<span class="java-quote">"name"</span>).add(<span class="java-keyword">new</span> PropertyValidator()));
+ form.add(<span class="java-keyword">new</span> TextField(<span class="java-quote">"email"</span>).add(<span class="java-keyword">new</span> PropertyValidator()));
+ form.add(<span class="java-keyword">new</span> TextField(<span class="java-quote">"age"</span>).add(<span class="java-keyword">new</span> PropertyValidator()));
+ //…
+}</pre></div><p class="paragraph"/>Now we can run our application an see that JSR 303 annotations are fully effective:<p class="paragraph"/><img border="0" class="center" src="../img/jsr303-form-validation.png"></img><p class="paragraph"/>
+
+
+<h2 id="forms2_5">12.5 Submit form with an IFormSubmittingComponent</h2>
<p class="paragraph"/>Besides submitting forms with a standard HTML submit button, Wicket allows us to use special components which implement interface IFormSubmittingComponent. This entity is a subinterface of IFormSubmitter:<p class="paragraph"/><img border="0" class="center" src="../img/class-diag-IFormSubmittingComponent.png"></img><p class="paragraph"/>At the beginning of this chapter we have seen that form processing is started by process method which takes as input an instance of IFormSubmitter. This parameter corresponds to the IFormSubmittingComponent clicked by a user to submit the form and it is null if we have used a standard HTML submit button (like we have done so far).<p class="paragraph"/>A submitting component is added to a form just like any other child component using method add(Component...).<p class="paragraph"/>A form can have any number of submitting components and we can specify which one among them is the default one by calling the Form's method setDefaultB
utton(IFormSubmittingComponent  component). The default submitter is the one that will be used when user presses 'Enter' key in a field of the form. In order to make the default button work, Wicket will add to our form a hidden <div> tag containing a text field and a submit button with some JavaScript code to trigger it:<p class="paragraph"/><div class="code"><pre><div style=<span class="java-quote">"width:0px;height:0px;position:absolute;left:-100px;top:-100px;overflow:hidden"</span>>
<input type=<span class="java-quote">"text"</span> autocomplete=<span class="java-quote">"off"</span>/>
<input type=<span class="java-quote">"submit"</span> name=<span class="java-quote">"submit2"</span> onclick=<span class="java-quote">" <span class="java-keyword">var</span> b=document...."</span>/>
@@ -1955,7 +1984,7 @@ Starting with Wicket version 6.0 interfa
}</pre></div><p class="paragraph"/><h3>Disabling default form processing</h3><p class="paragraph"/>With an IFormSubmittingComponent we can choose to skip the default form submission process by setting the appropriate flag to false with the setDefaultFormProcessing method. When the default form processing is disabled only the submitter's onSubmit is called while form's validation and models updating are skipped.<p class="paragraph"/>This can be useful if we want to implement a âCancelâ button on our form which redirects user to another page without validating his/her input.<p class="paragraph"/>When we set this flag to false we can decide to manually invoke the form processing by calling the process(IFormSubmittingComponent) method.
-<h2 id="forms2_5">12.5 Nested forms</h2>
+<h2 id="forms2_6">12.6 Nested forms</h2>
<p class="paragraph"/>As you might already known, HTLM doesn't allow to have nested forms. However with Wicket we can overcome this limitation by adding one or more form components to a parent form.<p class="paragraph"/>This can be useful if we want to split a big form into smaller ones in order to reuse them and to better distribute responsibilities among different components.
Forms can be nested to an arbitrary level:<p class="paragraph"/><div class="code"><pre><form wicket:id=<span class="java-quote">"outerForm"</span>>
…
@@ -1968,11 +1997,11 @@ Forms can be nested to an arbitrary leve
</form></pre></div><p class="paragraph"/>When a form is submitted also its nested forms are submitted and they participate in the validation step. This means that if a nested form contains invalid input values, the outer form won't be submitted. On the contrary, nested forms can be singularly submitted without depending on the status of their outer form.<p class="paragraph"/>To submit a parent form when one of its children forms is submitted, we must override its method wantSubmitOnNestedFormSubmit and make it return true.
-<h2 id="forms2_6">12.6 Multi-line text input</h2>
+<h2 id="forms2_7">12.7 Multi-line text input</h2>
<p class="paragraph"/>HTML provides a multi-line text input control with <textarea> tag. The Wicket counterpart for this kind of control is <code>org.apache.wicket.markup.html.form.TextArea</code> component:<p class="paragraph"/><strong class="bold">HTML:</strong><p class="paragraph"/><div class="code"><pre><textarea wicket:id=<span class="java-quote">"description"</span> rows=<span class="java-quote">"5"</span> cols=<span class="java-quote">"40"</span>></textarea></pre></div><p class="paragraph"/><strong class="bold">Java code:</strong><p class="paragraph"/><div class="code"><pre>form.add(<span class="java-keyword">new</span> TextArea(<span class="java-quote">"description"</span>, Model.of(<span class="java-quote">""</span>)));</pre></div><p class="paragraph"/>Component TextArea is used just like any other single-line text field. To specify the size of the text area we can write attributes rows and cols directly in the markup file or
we can create new attribute modifiers and add them to our TextArea component.
-<h2 id="forms2_7">12.7 File upload</h2>
+<h2 id="forms2_8">12.8 File upload</h2>
<p class="paragraph"/>Wicket supports file uploading with the FileUploadField component which must be used with the <input> tag whose type attribute must be set to "file". In order to send a file on form submission we must enable multipart mode calling MultiPart(true)on our form.<p class="paragraph"/>In the next example (project UploadSingleFile) we will see a form which allows users to upload a file into the temporary directory of the server (path /tmp on Unix/Linux systems):<p class="paragraph"/><strong class="bold">HTML:</strong><p class="paragraph"/><div class="code"><pre><html>
<head>
</head>
@@ -2013,7 +2042,7 @@ The maximum size for uploaded files can
</blockquote><p class="paragraph"/><h3>Upload multiple files</h3><p class="paragraph"/>If we need to upload multiple files at once, we can use the MultiFileUploadField component which allows the user to select an arbitrary number of files to send on form submission.<p class="paragraph"/>An example showing how to use this component can be found in Wicket module wicket-examples in file MultiUploadPage.java. The live example is hosted at <a href="http://www.wicket-library.com/wicket-examples-6.0.x/upload/multi" target="blank">http://www.wicket-library.com/wicket-examples-6.0.x/upload/multi</a> .
-<h2 id="forms2_8">12.8 Creating complex form components with FormComponentPanel</h2>
+<h2 id="forms2_9">12.9 Creating complex form components with FormComponentPanel</h2>
<p class="paragraph"/>In chapter 3.2.2 we have seen how to use class Panel to create custom components with their own markup and with an arbitrary number of children components.<p class="paragraph"/>While it's perfectly legal to use Panel also to group form components, the resulting component won't be itself a form component and it won't participate in the form's submission workflow.<p class="paragraph"/>This could be a strong limitation if the custom component needs to coordinate its children during sub-tasks like input conversion or model updating. That's why in Wicket we have the <code>org.apache.wicket.markup.html.form.FormComponentPanel</code> component which combines the features of a Panel (it has its own markup file) and a FormComponent (it is a subclass of FormComponent).<p class="paragraph"/>A typical scenario in which we may need to implement a custom FormComponentPanel is when our web application and its users work with different units of measurement for the same data.<p
class="paragraph"/>To illustrate this possible scenario, let's consider a form where a user can insert a temperature that will be recorded after being converted to Kelvin degrees (see the example project CustomForm ComponentPanel).<p class="paragraph"/>The Kelvin scale is wildly adopted among the scientific community and it is one of the seven base units of the <a href="http://en.wikipedia.org/wiki/International_System_of_Units" target="blank">International System of Units</a> , so it makes perfect sense to store temperatures expressed with this unit of measurement.<p class="paragraph"/>However, in our everyday life we still use other temperature scales like Celsius or Fahrenheit, so it would be nice to have a component which internally works with Kelvin degrees and automatically applies conversion between Kelvin temperature scale and the one adopted by the user.<p class="paragraph"/>In order to implement such a component, we can make a subclass of FormComponentPanel and leverage
the convertInput and onBeforeRender methods: in the implementation of the convertInput method we will convert input value to Kelvin degrees while in the implementation of onBeforeRender method we will take care of converting the Kelvin value to the temperature scale adopted by the user.<p class="paragraph"/>Our custom component will contain two children components: a text field to let user insert and edit a temperature value and a label to display the letter corresponding to user's temperature scale (F for Fahrenheit and C for Celsius). The resulting markup file is the following:<p class="paragraph"/><div class="code"><pre><html>
<head>
</head>
@@ -2066,7 +2095,7 @@ The maximum size for uploaded files can
}</pre></div><p class="paragraph"/>Since our component does not directly receive the user input, convertInput() must read this value from the inner text field using FormComponent's getConvertedInput() method which returns the input value already converted to the type specified for the component (Double in our case). Once we have the user input we convert it to kelvin degrees and we use the resulting value to set the converted input for our custom component (using method setConvertedInput(T convertedInput)).<p class="paragraph"/>Method onBeforeRender() is responsible for synchronizing the model of the inner textfield with the model of our custom component. To do this we retrieve the model object of the custom component with the getDefaultModelObject() method, then we convert it to the temperature scale adopted by the user and finally we use this value to set the model object of the text field.
-<h2 id="forms2_9">12.9 Stateless form</h2>
+<h2 id="forms2_10">12.10 Stateless form</h2>
<p class="paragraph"/>In chapter 6 we have seen how Wicket pages can be divided into two categories: stateful and stateless. Pages that are stateless don't need to be stored in the user session and they should be used when we don't need to save any user data in the user session (for example in the public area of a site).<p class="paragraph"/>Besides saving resources on server-side, stateless pages can be adopted to improve user experience and to avoid security weaknesses. A typical situation where a stateless page can bring these benefits is when we have to implement a login page.<p class="paragraph"/>For this kind of page we might encounter two potential problems if we chose to use a stateful page. The first problem occurs when the user tries to login without a valid session assigned to him. This could happen if the user leaves the login page opened for a period of time bigger than the session's timeout and then he decides to log in. Under these conditions the user will be redirec
ted to a 'Page expired' error page, which is not exactly a nice thing for user experience.<p class="paragraph"/>The second problem occurs when a malicious user or a web crawler program attempts to login into our web application, generating a huge number of page versions and consequently increasing the size of the user session.<p class="paragraph"/>To avoid these kinds of problems we should build a stateless login page which does not depend on a user session. Wicket provides a special version of the Form component called StatelessForm which is stateless by default (i.e its method getStatelessHint() returns true), hence it's an ideal solution when we want to build a stateless page with a form. A possible implementation of our login form is the following (example project StatelessLoginForm):<p class="paragraph"/><strong class="bold">HTML:</strong><p class="paragraph"/><div class="code"><pre><html>
<head>
<meta charset=<span class="java-quote">"utf-8"</span> />
@@ -2111,7 +2140,7 @@ The maximum size for uploaded files can
}</pre></div><p class="paragraph"/>Label sessionType shows if current session is temporary or not and is set inside onBeforeRender(): if our page is really stateless the session will be always temporary. We have also inserted a feedback panel in the home page that shows if the credentials are correct. This was done to make the example form more interactive.
-<h2 id="forms2_10">12.10 Working with radio buttons and checkboxes</h2>
+<h2 id="forms2_11">12.11 Working with radio buttons and checkboxes</h2>
<p class="paragraph"/>In this paragraph we will see which components can be used to handle HTML radio buttons and checkboxes. Both these input elements are usually grouped together to display a list of possible choices:<p class="paragraph"/><img border="0" class="center" src="../img/choice-form-screenshot.png"></img><p class="paragraph"/>A check box can be used as single component to set a boolean property. For this purpose Wicket provides the <code>org.apache.wicket.markup.html.form.CheckBox</code> component which must be attached to <input type="checkbox".../> tag. In the next example (project SingleCheckBox) we will consider a form similar to the one used in paragraph 9.5 to edit a Person object, but with an additional checkbox to let the user decide if she wants to subscribe to our mailing list or not. The form uses the following bean as backing object:<p class="paragraph"/><div class="code"><pre><span class="java-keyword">public</span> class RegistrationInfo <span c
lass="java-keyword">implements</span> Serializable {<p class="paragraph"/> <span class="java-keyword">private</span> <span class="java-object">String</span> name;
<span class="java-keyword">private</span> <span class="java-object">String</span> surname;
<span class="java-keyword">private</span> <span class="java-object">String</span> address;
@@ -2181,7 +2210,7 @@ CheckBoxSelector cbmcs = <span class="ja
form.add(<span class="java-keyword">new</span> RadioChoice(<span class="java-quote">"radioGroup"</span>, Model.of(<span class="java-quote">""</span>), fruits));</pre></div><p class="paragraph"/><strong class="bold">Screenshot:</strong><p class="paragraph"/><img border="0" class="center" src="../img/grouped-radiobutton.png"></img><p class="paragraph"/>Just like CheckBoxMultipleChoice, this component provides the setPrefix and setSuffix methods to configure the prefix and suffix for our options and it supports IChoiceRender as well. In addition, RadioChoice provides the wantOnSelectionChangedNotifications() method to notify the web server when the selected option changes (this is the same method seen for DropDownChoice in paragraph 9.4).
-<h2 id="forms2_11">12.11 Selecting multiple values with ListMultipleChoices and Palette</h2>
+<h2 id="forms2_12">12.12 Selecting multiple values with ListMultipleChoices and Palette</h2>
<p class="paragraph"/>Checkboxes work well when we have a small amount of options to display, but they quickly become chaotic as the number of options increases. To overcome this limit we can use the <select> tag switching it to multiple-choice mode with attribute multiple="multiple":<p class="paragraph"/><img border="0" class="center" src="../img/list-multiple-choices.png"></img><p class="paragraph"/>Now the user can select multiple options by holding down Ctrl key (or Command key for Mac) and selecting them.<p class="paragraph"/>To work with multiple choice list Wicket provides the <code>org.apache.wicket.markup.html.form.ListMultipleChoice</code> component:<p class="paragraph"/><strong class="bold">HTML:</strong><p class="paragraph"/><div class="code"><pre><select wicket:id=<span class="java-quote">"fruits"</span>>
<option>choice 1</option>
<option>choice 2</option>
@@ -2224,7 +2253,7 @@ ChoiceRenderer render = <span class="jav
</table></pre></div>
-<h2 id="forms2_12">12.12 Summary</h2>
+<h2 id="forms2_13">12.13 Summary</h2>
Forms are the standard solution to let users interact with our web applications. In this chapter we have seen the three steps involved with the form processing workflow in Wicket. We have started looking at form validation and feedback messages generation, then we have seen how Wicket converts input values into Java objects and vice versa.<p class="paragraph"/>In the second part of the chapter we learnt how to build reusable form components and how to implement a stateless form. We have ended the chapter with an overview of the built-in form components needed to handle standard input form elements like checkboxes, radio buttons and multiple selections lists.<p class="paragraph"/>
@@ -4689,7 +4718,7 @@ and attach it to a ticket in Apache Wick
<div id="footer">
Copyright © 2013-2014 â <a href="http://www.apache.org/" target="_blank">The Apache Software Foundation</a>
- â <b style="color:#E8590A !important;">(Generated on: 2014-04-10)</b>
+ â <b style="color:#E8590A !important;">(Generated on: 2014-04-24)</b>
</div>
Modified: wicket/common/site/trunk/_site/guide/guide/single.pdf
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/single.pdf?rev=1589849&r1=1589848&r2=1589849&view=diff
==============================================================================
Binary files - no diff available.
Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_10.gdoc
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_10.gdoc?rev=1589849&r1=1589848&r2=1589849&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_10.gdoc (original)
+++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_10.gdoc Thu Apr 24 19:41:13 2014
@@ -1,187 +1,78 @@
-In this paragraph we will see which components can be used to handle HTML radio buttons and checkboxes. Both these input elements are usually grouped together to display a list of possible choices:
+In chapter 6 we have seen how Wicket pages can be divided into two categories: stateful and stateless. Pages that are stateless don't need to be stored in the user session and they should be used when we don't need to save any user data in the user session (for example in the public area of a site).
-!choice-form-screenshot.png!
+Besides saving resources on server-side, stateless pages can be adopted to improve user experience and to avoid security weaknesses. A typical situation where a stateless page can bring these benefits is when we have to implement a login page.
-A check box can be used as single component to set a boolean property. For this purpose Wicket provides the @org.apache.wicket.markup.html.form.CheckBox@ component which must be attached to <input type="checkbox".../> tag. In the next example (project SingleCheckBox) we will consider a form similar to the one used in paragraph 9.5 to edit a Person object, but with an additional checkbox to let the user decide if she wants to subscribe to our mailing list or not. The form uses the following bean as backing object:
+For this kind of page we might encounter two potential problems if we chose to use a stateful page. The first problem occurs when the user tries to login without a valid session assigned to him. This could happen if the user leaves the login page opened for a period of time bigger than the session's timeout and then he decides to log in. Under these conditions the user will be redirected to a 'Page expired' error page, which is not exactly a nice thing for user experience.
-{code}
-public class RegistrationInfo implements Serializable {
-
- private String name;
- private String surname;
- private String address;
- private String email;
- private boolean subscribeList;
-
- /*Getters and setters*/
-}
-{code}
+The second problem occurs when a malicious user or a web crawler program attempts to login into our web application, generating a huge number of page versions and consequently increasing the size of the user session.
-The markup and the code for this example are the following:
+To avoid these kinds of problems we should build a stateless login page which does not depend on a user session. Wicket provides a special version of the Form component called StatelessForm which is stateless by default (i.e its method getStatelessHint() returns true), hence it's an ideal solution when we want to build a stateless page with a form. A possible implementation of our login form is the following (example project StatelessLoginForm):
*HTML:*
{code:html}
-<form wicket:id="form">
- <div style="display: table;">
- <div style="display: table-row;">
- <div style="display: table-cell;">Name: </div>
- <div style="display: table-cell;">
- <input type="text" wicket:id="name"/>
- </div>
- </div>
- <div style="display: table-row;">
- <div style="display: table-cell;">Surname: </div>
- <div style="display: table-cell;">
- <input type="text" wicket:id="surname"/>
- </div>
- </div>
- <div style="display: table-row;">
- <div style="display: table-cell;">Address: </div>
- <div style="display: table-cell;">
- <input type="text" wicket:id="address"/>
- </div>
- </div>
- <div style="display: table-row;">
- <div style="display: table-cell;">Email: </div>
- <div style="display: table-cell;">
- <input type="text" wicket:id="email"/>
- </div>
- </div>
- <div style="display: table-row;">
- <div style="display: table-cell;">Subscribe list:</div>
- <div style="display: table-cell;">
- <input type="checkbox" wicket:id="subscribeList"/>
- </div>
- </div>
- </div>
- <input type="submit" value="Save"/>
-</form>
+<html>
+ <head>
+ <meta charset="utf-8" />
+ </head>
+ <body>
+ <div>Session is <b wicket:id="sessionType"></b></div>
+ <br/>
+ <div>Type 'user' as correct credentials</div>
+ <form wicket:id="form">
+ <fieldset>
+ Username: <input type="text" wicket:id="username"/> <br/>
+ Password: <input type="password" wicket:id="password"/><br/>
+ <input type="submit"/>
+ </fieldset>
+ </form>
+ <br/>
+ <div wicket:id="feedbackPanel"></div>
+ </body>
+</html>
{code}
*Java code:*
{code}
-public HomePage(final PageParameters parameters) {
- RegistrationInfo registrtionInfo = new RegistrationInfo();
- registrtionInfo.setSubscribeList(true);
-
- Form form = new Form("form",
- new CompoundPropertyModel<RegistrationInfo>(registrtionInfo));
-
- form.add(new TextField("name"));
- form.add(new TextField("surname"));
- form.add(new TextField("address"));
- form.add(new TextField("email"));
- form.add(new CheckBox("subscribeList"));
-
- add(form);
+public class HomePage extends WebPage {
+ private Label sessionType;
+ private String password;
+ private String username;
+
+ public HomePage(final PageParameters parameters) {
+ StatelessForm form = new StatelessForm("form"){
+ @Override
+ protected void onSubmit() {
+ //sign in if username and password are âuserâ
+ if("user".equals(username) && username.equals(password))
+ info("Username and password are correct!");
+ else
+ error("Wrong username or password");
+ }
+ };
+
+ form.add(new PasswordTextField("password"));
+ form.add(new TextField("username"));
+
+ add(form.setDefaultModel(new CompoundPropertyModel(this)));
+
+ add(sessionType = new Label("sessionType", Model.of("")));
+ add(new FeedbackPanel("feedbackPanel"));
+ }
+
+ @Override
+ protected void onBeforeRender() {
+ super.onBeforeRender();
+
+ if(getSession().isTemporary())
+ sessionType.setDefaultModelObject("temporary");
+ else
+ sessionType.setDefaultModelObject("permanent");
+ }
}
{code}
-Please note that the checkbox will be initially selected because we have set to true the subscribe flag during the model object creation (with instruction registrtionInfo.setSubscribeList(true)):
-
-!subscribe-checkbox-set.png!
-
-h3. Working with grouped checkboxes
-
-When we need to display a given number of options with checkboxes, we can use the @org.apache.wicket.markup.html.form.CheckBoxMultipleChoice@ component. For example, If our options are a list of strings, we can display them in this way:
-
-*HTML:*
-
-{code:html}
-<div wicket:id="checkGroup">
- <input type="checkbox"/>It will be replaced by the actual checkboxes...
-</div>
-{code}
-
-*Java code:*
-
-{code}
-List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon");
-form.add(new CheckBoxMultipleChoice("checkGroup", new ListModel<String>(new
- ArrayList<String>()), fruits));
-{code}
-
-*Screenshot:*
-
-!grouped-checkbox.png!
-
-This component can be attached to a <div> tag or to a <span> tag. No specific content is required for this tag as it will be populated with the actual checkboxes. Since this component allows multiple selection, its model object is a list. In the example above we have used model class @org.apache.wicket.model.util.ListModel@ which is specifically designed to wrap a List object.
-
-By default CheckBoxMultipleChoice inserts a <br/> tag as suffix after each option. We can configure both the suffix and the prefix used by the component with the setPrefix and setSuffix methods.
-
-When our options are more complex objects than simple strings, we can render them using an IChoiceRender, as we did for DropDownChoice in paragraph 9.4:
-
-*HTML:*
-
-{code:html}
-<div wicket:id="checkGroup">
- <input type="checkbox"/>It will be replaced by actual checkboxes...
-</div>
-{code}
-
-*Java code:*
-
-{code}
-Person john = new Person("John", "Smith");
-Person bob = new Person("Bob", "Smith");
-Person jill = new Person("Jill", "Smith");
-List<Person> theSmiths = Arrays.asList(john, bob, jill);
-ChoiceRenderer render = new ChoiceRenderer("name");
- form.add(new CheckBoxMultipleChoice("checkGroup", new ListModel<String>(new ArrayList<String>()),
- theSmiths, render));
-{code}
-
-*Screenshot:*
-
-!grouped-checkbox2.png!
-
-h3. How to implement a "Select all" checkbox
-
-A nice feature we can offer to users when we have a group of checkboxes is a âspecialâ checkbox which selects/unselects all the other options of the group:
-
-!select-all-checkbox.png!
-
-Wicket comes with a couple of utility components that make it easy to implement such a feature. They are CheckboxMultipleChoiceSelector and CheckBoxSelector classes, both inside package @org.apache.wicket.markup.html.form@. The difference between these two components is that the first works with an instance of CheckBoxMultipleChoice while the second takes in input a list of CheckBox objects:
-
-{code}
-/* CheckboxMultipleChoiceSelector usage: */
-
-CheckBoxMultipleChoice checkGroup;
-//checkGroup initialization...
-CheckboxMultipleChoiceSelector cbmcs = new CheckboxMultipleChoiceSelector("id", checkGroup);
-
-/* CheckBoxSelector usage: */
-
-CheckBox checkBox1, checkBox2, checkBox3;
-//checks initialization...
-CheckBoxSelector cbmcs = new CheckBoxSelector("id", checkBox1, checkBox2, checkBox3);
-{code}
-
-h3. Working with grouped radio buttons
-
-For groups of radio buttons we can use the @org.apache.wicket.markup.html.form.RadioChoice@ component which works in much the same way as CheckBoxMultipleChoice:
-
-*HTML:*
-
-{code:html}
-<div wicket:id="radioGroup">
- <input type="radio"/>It will be replaced by actual radio buttons...
-</div>
-{code}
-
-*Java code:*
-
-{code}
-List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon");
-form.add(new RadioChoice("radioGroup", Model.of(""), fruits));
-{code}
-
-*Screenshot:*
-
-!grouped-radiobutton.png!
-
-Just like CheckBoxMultipleChoice, this component provides the setPrefix and setSuffix methods to configure the prefix and suffix for our options and it supports IChoiceRender as well. In addition, RadioChoice provides the wantOnSelectionChangedNotifications() method to notify the web server when the selected option changes (this is the same method seen for DropDownChoice in paragraph 9.4).
\ No newline at end of file
+Label sessionType shows if current session is temporary or not and is set inside onBeforeRender(): if our page is really stateless the session will be always temporary. We have also inserted a feedback panel in the home page that shows if the credentials are correct. This was done to make the example form more interactive.
\ No newline at end of file
Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_11.gdoc
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_11.gdoc?rev=1589849&r1=1589848&r2=1589849&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_11.gdoc (original)
+++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_11.gdoc Thu Apr 24 19:41:13 2014
@@ -1,56 +1,125 @@
-Checkboxes work well when we have a small amount of options to display, but they quickly become chaotic as the number of options increases. To overcome this limit we can use the <select> tag switching it to multiple-choice mode with attribute multiple="multiple":
+In this paragraph we will see which components can be used to handle HTML radio buttons and checkboxes. Both these input elements are usually grouped together to display a list of possible choices:
-!list-multiple-choices.png!
+!choice-form-screenshot.png!
-Now the user can select multiple options by holding down Ctrl key (or Command key for Mac) and selecting them.
+A check box can be used as single component to set a boolean property. For this purpose Wicket provides the @org.apache.wicket.markup.html.form.CheckBox@ component which must be attached to <input type="checkbox".../> tag. In the next example (project SingleCheckBox) we will consider a form similar to the one used in paragraph 9.5 to edit a Person object, but with an additional checkbox to let the user decide if she wants to subscribe to our mailing list or not. The form uses the following bean as backing object:
-To work with multiple choice list Wicket provides the @org.apache.wicket.markup.html.form.ListMultipleChoice@ component:
+{code}
+public class RegistrationInfo implements Serializable {
+
+ private String name;
+ private String surname;
+ private String address;
+ private String email;
+ private boolean subscribeList;
+
+ /*Getters and setters*/
+}
+{code}
+
+The markup and the code for this example are the following:
*HTML:*
{code:html}
-<select wicket:id="fruits">
- <option>choice 1</option>
- <option>choice 2</option>
-</select>
+<form wicket:id="form">
+ <div style="display: table;">
+ <div style="display: table-row;">
+ <div style="display: table-cell;">Name: </div>
+ <div style="display: table-cell;">
+ <input type="text" wicket:id="name"/>
+ </div>
+ </div>
+ <div style="display: table-row;">
+ <div style="display: table-cell;">Surname: </div>
+ <div style="display: table-cell;">
+ <input type="text" wicket:id="surname"/>
+ </div>
+ </div>
+ <div style="display: table-row;">
+ <div style="display: table-cell;">Address: </div>
+ <div style="display: table-cell;">
+ <input type="text" wicket:id="address"/>
+ </div>
+ </div>
+ <div style="display: table-row;">
+ <div style="display: table-cell;">Email: </div>
+ <div style="display: table-cell;">
+ <input type="text" wicket:id="email"/>
+ </div>
+ </div>
+ <div style="display: table-row;">
+ <div style="display: table-cell;">Subscribe list:</div>
+ <div style="display: table-cell;">
+ <input type="checkbox" wicket:id="subscribeList"/>
+ </div>
+ </div>
+ </div>
+ <input type="submit" value="Save"/>
+</form>
{code}
*Java code:*
{code}
-List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon");
-form.add(new ListMultipleChoice("fruits", new ListModel<String>(new ArrayList<String>()), fruits));
+public HomePage(final PageParameters parameters) {
+ RegistrationInfo registrtionInfo = new RegistrationInfo();
+ registrtionInfo.setSubscribeList(true);
+
+ Form form = new Form("form",
+ new CompoundPropertyModel<RegistrationInfo>(registrtionInfo));
+
+ form.add(new TextField("name"));
+ form.add(new TextField("surname"));
+ form.add(new TextField("address"));
+ form.add(new TextField("email"));
+ form.add(new CheckBox("subscribeList"));
+
+ add(form);
+}
{code}
-*Screenshot:*
+Please note that the checkbox will be initially selected because we have set to true the subscribe flag during the model object creation (with instruction registrtionInfo.setSubscribeList(true)):
-!list-multiple-choices2.png!
+!subscribe-checkbox-set.png!
-This component must be bound to a <select> tag but the attribute multiple="multiple" is not required as it will automatically be added by the component.
+h3. Working with grouped checkboxes
-The number of visible rows can be set with the setMaxRows(int maxRows) method.
+When we need to display a given number of options with checkboxes, we can use the @org.apache.wicket.markup.html.form.CheckBoxMultipleChoice@ component. For example, If our options are a list of strings, we can display them in this way:
-h3. Component Palette
+*HTML:*
-While multiple choice list solves the problem of handling a big number of multiple choices, it is not much intuitive for end users. That's why desktop GUIs have introduced a more complex component which can be generally referred to as multi select transfer component (it doesn't have an actual official name):
+{code:html}
+<div wicket:id="checkGroup">
+ <input type="checkbox"/>It will be replaced by the actual checkboxes...
+</div>
+{code}
-!multi-select-transfer-component.png!
+*Java code:*
-This kind of component is composed by two multiple-choice lists, one on the left displaying the available options and the other one on the right displaying the selected options. User can move options from a list to another by double clicking on them or using the buttons placed between the two list.
+{code}
+List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon");
+form.add(new CheckBoxMultipleChoice("checkGroup", new ListModel<String>(new
+ ArrayList<String>()), fruits));
+{code}
+
+*Screenshot:*
+
+!grouped-checkbox.png!
-Built-in @org.apache.wicket.extensions.markup.html.form.palette.Palette@ component provides an out-of-the-box implementation of a multi select transfer component. It works in a similar way to ListMultipleChoice:
+This component can be attached to a <div> tag or to a <span> tag. No specific content is required for this tag as it will be populated with the actual checkboxes. Since this component allows multiple selection, its model object is a list. In the example above we have used model class @org.apache.wicket.model.util.ListModel@ which is specifically designed to wrap a List object.
+
+By default CheckBoxMultipleChoice inserts a <br/> tag as suffix after each option. We can configure both the suffix and the prefix used by the component with the setPrefix and setSuffix methods.
+
+When our options are more complex objects than simple strings, we can render them using an IChoiceRender, as we did for DropDownChoice in paragraph 9.4:
*HTML:*
{code:html}
-<div wicket:id="palette">
- Select will be replaced by the actual content...
- <select multiple="multiple">
- <option>option1</option>
- <option>option2</option>
- <option>option3</option>
+<div wicket:id="checkGroup">
+ <input type="checkbox"/>It will be replaced by actual checkboxes...
</div>
{code}
@@ -60,47 +129,59 @@ Built-in @org.apache.wicket.extensions.m
Person john = new Person("John", "Smith");
Person bob = new Person("Bob", "Smith");
Person jill = new Person("Jill", "Smith");
-Person andrea = new Person("Andrea", "Smith");
+List<Person> theSmiths = Arrays.asList(john, bob, jill);
+ChoiceRenderer render = new ChoiceRenderer("name");
+ form.add(new CheckBoxMultipleChoice("checkGroup", new ListModel<String>(new ArrayList<String>()),
+ theSmiths, render));
+{code}
+
+*Screenshot:*
-List<Person> theSmiths = Arrays.asList(john, bob, jill, andrea);
-ChoiceRenderer render = new ChoiceRenderer("name");
+!grouped-checkbox2.png!
+
+h3. How to implement a "Select all" checkbox
+
+A nice feature we can offer to users when we have a group of checkboxes is a âspecialâ checkbox which selects/unselects all the other options of the group:
+
+!select-all-checkbox.png!
+
+Wicket comes with a couple of utility components that make it easy to implement such a feature. They are CheckboxMultipleChoiceSelector and CheckBoxSelector classes, both inside package @org.apache.wicket.markup.html.form@. The difference between these two components is that the first works with an instance of CheckBoxMultipleChoice while the second takes in input a list of CheckBox objects:
-form.add(new Palette("palette", Model.of(new ArrayList<String>()), new ListModel<String> (theSmiths), render, 5, true));
{code}
+/* CheckboxMultipleChoiceSelector usage: */
-*Screenshot:*
+CheckBoxMultipleChoice checkGroup;
+//checkGroup initialization...
+CheckboxMultipleChoiceSelector cbmcs = new CheckboxMultipleChoiceSelector("id", checkGroup);
-!multi-select-transfer-component-wicket.png!
+/* CheckBoxSelector usage: */
-The last two parameters of the Palette's constructor (an integer value and a boolean value) are, respectively, the number of visible rows for the two lists and a flag to choose if we want to display the two optional buttons which move selected options up and down. The descriptions of the two lists (âAvailableâ and âSelectedâ) can be customized providing two resources with keys palette.available and palette.selected.
+CheckBox checkBox1, checkBox2, checkBox3;
+//checks initialization...
+CheckBoxSelector cbmcs = new CheckBoxSelector("id", checkBox1, checkBox2, checkBox3);
+{code}
-The markup of this component uses a number of CSS classes which can be extended/overriden to customize the style of the component. We can find these classes and see which tags they decorate in the default markup file of the component:
+h3. Working with grouped radio buttons
+
+For groups of radio buttons we can use the @org.apache.wicket.markup.html.form.RadioChoice@ component which works in much the same way as CheckBoxMultipleChoice:
+
+*HTML:*
{code:html}
-<table cellspacing="0" cellpadding="2" class="palette">
-<tr>
- <td class="header headerAvailable"><span wicket:id="availableHeader">[available header]</span></td>
- <td> </td>
- <td class="header headerSelected"><span wicket:id="selectedHeader">[selected header]</span>
- </td>
-</tr>
-<tr>
- <td class="pane choices">
- <select wicket:id="choices" class="choicesSelect">[choices]</select>
- </td>
- <td class="buttons">
- <button type="button" wicket:id="addButton" class="button add"><div/>
- </button><br/>
- <button type="button" wicket:id="removeButton" class="button remove"><div/>
- </button><br/>
- <button type="button" wicket:id="moveUpButton" class="button up"><div/>
- </button><br/>
- <button type="button" wicket:id="moveDownButton" class="button down"><div/>
- </button><br/>
- </td>
- <td class="pane selection">
- <select class="selectionSelect" wicket:id="selection">[selection]</select>
- </td>
-</tr>
-</table>
-{code}
\ No newline at end of file
+<div wicket:id="radioGroup">
+ <input type="radio"/>It will be replaced by actual radio buttons...
+</div>
+{code}
+
+*Java code:*
+
+{code}
+List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon");
+form.add(new RadioChoice("radioGroup", Model.of(""), fruits));
+{code}
+
+*Screenshot:*
+
+!grouped-radiobutton.png!
+
+Just like CheckBoxMultipleChoice, this component provides the setPrefix and setSuffix methods to configure the prefix and suffix for our options and it supports IChoiceRender as well. In addition, RadioChoice provides the wantOnSelectionChangedNotifications() method to notify the web server when the selected option changes (this is the same method seen for DropDownChoice in paragraph 9.4).
\ No newline at end of file
Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_12.gdoc
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_12.gdoc?rev=1589849&r1=1589848&r2=1589849&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_12.gdoc (original)
+++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_12.gdoc Thu Apr 24 19:41:13 2014
@@ -1,6 +1,106 @@
-Forms are the standard solution to let users interact with our web applications. In this chapter we have seen the three steps involved with the form processing workflow in Wicket. We have started looking at form validation and feedback messages generation, then we have seen how Wicket converts input values into Java objects and vice versa.
-In the second part of the chapter we learnt how to build reusable form components and how to implement a stateless form. We have ended the chapter with an overview of the built-in form components needed to handle standard input form elements like checkboxes, radio buttons and multiple selections lists.
+Checkboxes work well when we have a small amount of options to display, but they quickly become chaotic as the number of options increases. To overcome this limit we can use the <select> tag switching it to multiple-choice mode with attribute multiple="multiple":
+!list-multiple-choices.png!
+Now the user can select multiple options by holding down Ctrl key (or Command key for Mac) and selecting them.
+
+To work with multiple choice list Wicket provides the @org.apache.wicket.markup.html.form.ListMultipleChoice@ component:
+
+*HTML:*
+
+{code:html}
+<select wicket:id="fruits">
+ <option>choice 1</option>
+ <option>choice 2</option>
+</select>
+{code}
+
+*Java code:*
+
+{code}
+List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon");
+form.add(new ListMultipleChoice("fruits", new ListModel<String>(new ArrayList<String>()), fruits));
+{code}
+
+*Screenshot:*
+
+!list-multiple-choices2.png!
+
+This component must be bound to a <select> tag but the attribute multiple="multiple" is not required as it will automatically be added by the component.
+
+The number of visible rows can be set with the setMaxRows(int maxRows) method.
+
+h3. Component Palette
+
+While multiple choice list solves the problem of handling a big number of multiple choices, it is not much intuitive for end users. That's why desktop GUIs have introduced a more complex component which can be generally referred to as multi select transfer component (it doesn't have an actual official name):
+
+!multi-select-transfer-component.png!
+
+This kind of component is composed by two multiple-choice lists, one on the left displaying the available options and the other one on the right displaying the selected options. User can move options from a list to another by double clicking on them or using the buttons placed between the two list.
+
+Built-in @org.apache.wicket.extensions.markup.html.form.palette.Palette@ component provides an out-of-the-box implementation of a multi select transfer component. It works in a similar way to ListMultipleChoice:
+
+*HTML:*
+
+{code:html}
+<div wicket:id="palette">
+ Select will be replaced by the actual content...
+ <select multiple="multiple">
+ <option>option1</option>
+ <option>option2</option>
+ <option>option3</option>
+</div>
+{code}
+
+*Java code:*
+
+{code}
+Person john = new Person("John", "Smith");
+Person bob = new Person("Bob", "Smith");
+Person jill = new Person("Jill", "Smith");
+Person andrea = new Person("Andrea", "Smith");
+
+List<Person> theSmiths = Arrays.asList(john, bob, jill, andrea);
+ChoiceRenderer render = new ChoiceRenderer("name");
+
+form.add(new Palette("palette", Model.of(new ArrayList<String>()), new ListModel<String> (theSmiths), render, 5, true));
+{code}
+
+*Screenshot:*
+
+!multi-select-transfer-component-wicket.png!
+
+The last two parameters of the Palette's constructor (an integer value and a boolean value) are, respectively, the number of visible rows for the two lists and a flag to choose if we want to display the two optional buttons which move selected options up and down. The descriptions of the two lists (âAvailableâ and âSelectedâ) can be customized providing two resources with keys palette.available and palette.selected.
+
+The markup of this component uses a number of CSS classes which can be extended/overriden to customize the style of the component. We can find these classes and see which tags they decorate in the default markup file of the component:
+
+{code:html}
+<table cellspacing="0" cellpadding="2" class="palette">
+<tr>
+ <td class="header headerAvailable"><span wicket:id="availableHeader">[available header]</span></td>
+ <td> </td>
+ <td class="header headerSelected"><span wicket:id="selectedHeader">[selected header]</span>
+ </td>
+</tr>
+<tr>
+ <td class="pane choices">
+ <select wicket:id="choices" class="choicesSelect">[choices]</select>
+ </td>
+ <td class="buttons">
+ <button type="button" wicket:id="addButton" class="button add"><div/>
+ </button><br/>
+ <button type="button" wicket:id="removeButton" class="button remove"><div/>
+ </button><br/>
+ <button type="button" wicket:id="moveUpButton" class="button up"><div/>
+ </button><br/>
+ <button type="button" wicket:id="moveDownButton" class="button down"><div/>
+ </button><br/>
+ </td>
+ <td class="pane selection">
+ <select class="selectionSelect" wicket:id="selection">[selection]</select>
+ </td>
+</tr>
+</table>
+{code}
\ No newline at end of file
Added: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_13.gdoc
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_13.gdoc?rev=1589849&view=auto
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_13.gdoc (added)
+++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_13.gdoc Thu Apr 24 19:41:13 2014
@@ -0,0 +1,6 @@
+
+Forms are the standard solution to let users interact with our web applications. In this chapter we have seen the three steps involved with the form processing workflow in Wicket. We have started looking at form validation and feedback messages generation, then we have seen how Wicket converts input values into Java objects and vice versa.
+
+In the second part of the chapter we learnt how to build reusable form components and how to implement a stateless form. We have ended the chapter with an overview of the built-in form components needed to handle standard input form elements like checkboxes, radio buttons and multiple selections lists.
+
+
Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_4.gdoc
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_4.gdoc?rev=1589849&r1=1589848&r2=1589849&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_4.gdoc (original)
+++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_4.gdoc Thu Apr 24 19:41:13 2014
@@ -1,124 +1,82 @@
+Standard JSR 303 defines a set of annotations and APIs to validate our domain objects at field-level. Wicket has introduced an experimental support for this standard since version 6.4.0 and with version 6.14.0 it has became an official Wicket model (named @wicket-bean-validation@).
+In this paragraph we will see the basic steps needed to use JSR 303 validation in our Wicket application. Code snippets are from example project @JSR303validation@.
+In the example application we have a form to insert the data for a new @Person@ bean and its relative @Address@. The code for class @Person@ is the following
-Besides submitting forms with a standard HTML submit button, Wicket allows us to use special components which implement interface IFormSubmittingComponent. This entity is a subinterface of IFormSubmitter:
-
-!class-diag-IFormSubmittingComponent.png!
-
-At the beginning of this chapter we have seen that form processing is started by process method which takes as input an instance of IFormSubmitter. This parameter corresponds to the IFormSubmittingComponent clicked by a user to submit the form and it is null if we have used a standard HTML submit button (like we have done so far).
-
-A submitting component is added to a form just like any other child component using method add(Component...).
-
-A form can have any number of submitting components and we can specify which one among them is the default one by calling the Form's method setDefaultButton(IFormSubmittingComponent  component). The default submitter is the one that will be used when user presses 'Enter' key in a field of the form. In order to make the default button work, Wicket will add to our form a hidden <div> tag containing a text field and a submit button with some JavaScript code to trigger it:
-
-{code:html}
-<div style="width:0px;height:0px;position:absolute;left:-100px;top:-100px;overflow:hidden">
- <input type="text" autocomplete="off"/>
- <input type="submit" name="submit2" onclick=" var b=document...."/>
-</div>
+{code}
+public class Person implements Serializable{
+
+ @NotNull
+ private String name;
+
+ //regular expression to validate an email address
+ @Pattern(regexp = "^[_A-Za-z0-9-]+(.[_A-Za-z0-9-]+)*[A-Za-z0-9-]+(.[A-Za-z0-9-]+)*((.[A-Za-z]{2,}){1}$)")
+ private String email;
+
+ @Range(min = 18, max = 150)
+ private int age;
+
+ @Past @NotNull
+ private Date birthDay;
+
+ @NotNull
+ private Address address;
+}
{code}
-Just like Wicket forms, interface IFormSubmitter defines methods onSubmit and onError. These two methods have the priority over the namesake methods of the form, meaning that when a form is submitted with an IFormSubmitter, the onSubmit of the submitter is called before the one of the form. Similarly, if validation errors occurs during the first step of form processing, submitter's method onError is called before the form's one.
-
-{note}
-Starting with Wicket version 6.0 interface IFormSubmitter defines a further callback method called onAfterSubmit(). This method is called after form's method onSubmit() has been executed.
-{note}
-
-h3. Components Button and SubmitLink
-
-Component @org.apache.wicket.markup.html.form.Button@ is a basic implementation of a form submitter. It can be used with either the <input> or <button> tags. The string model received as input by its constructor is used as button label and it will be the value of the markup attribute value.
+You can note the JSR 303 annotations used in the code above to declare validation constraints on class fields. Class @Address@ has the following code:
-In the following snippet we have a form with two submit buttons bound to an <input> tag. One of them is set as default button and both have a string model for the label:
+{code}
+public class Address implements Serializable {
+
+ @NotNull
+ private String city;
+
+ @NotNull
+ private String street;
+
+ @Pattern(regexp = "\\d+", message = "{address.invalidZipCode}")
+ private String zipCode;
+}
+{code}
-*HTML:*
+You might have noted that in class @Address@ we have used annotation @Pattern using also attribute @message@ which contains the key of the bundle to use for validation message. Our custom bundle is contained inside @HomePage.properties@:
-{code:html}
-<body>
- <form wicket:id="form">
- Username: <input type="text" wicket:id="username"/>
- <br/>
- <input type="submit" wicket:id="submit1"/>
- <input type="submit" wicket:id="submit2"/>
- </form>
-</body>
+{code}
+address.invalidZipCode=The inserted zip code is not valid.
{code}
-*Java code:*
+To tell Wicket to use JSR 303, we must register bean validator on Application's startup:
{code}
-public class HomePage extends WebPage {
-
- public HomePage(final PageParameters parameters) {
- Form form = new Form("form");
+public class WicketApplication extends WebApplication {
+ @Override
+ public void init(){
+ super.init();
- form.add(new TextField("username", Model.of("")));
- form.add(new Button("submit1", Model.of("First submitter")));
- Button secondSubmitter;
- form.add(secondSubmitter = new Button("submit2", Model.of("Second submitter")));
-
- form.setDefaultButton(secondSubmitter);
- add(form);
- }
+ new BeanValidationConfiguration().configure(this);
+ }
}
{code}
-*Generated markup:*
+The last step to harness JSR 303 annotations is to add validator @org.apache.wicket.bean.validation.PropertyValidator@ to our corresponding form components:
-{code:html}
-<form wicket:id="form" id="form1" method="post" action="?0-1.IFormSubmitListener-form">
- <div>
- ...
- <!-- Code generated by Wicket to handle the default button -->
- ...
- </div>
- Username: <input type="text" wicket:id="username" value="" name="username"/>
- <br/>
- <input type="submit" wicket:id="submit1" name="submit1" id="submit13" value="First submitter"/>
- <input type="submit" wicket:id="submit2" name="submit2" id="submit22" value="Second submitter"/>
-</form>
-{code}
-
-Another component that can be used to submit a form is @org.apache.wicket.markup.html.form.SubmitLink@. This component uses JavaScript to submit the form. Like the name suggests, the component can be used with the <a> tag but it can be also bound to any other tag that supports the event handler onclick. When used with the <a> tag, the JavaScript code needed to submit the form will be placed inside href attribute while with other tags the script will go inside the event handler onclick.
-
-A notable difference between this component and Button is that SubmitLink can be placed outside the form it must submit. In this case we must specify the form to submit in its constructor:
-
-*HTML:*
-
-{code:html}
-<html xmlns:wicket="http://wicket.apache.org">
-<head>
- </head>
- <body>
- <form wicket:id="form">
- Password: <input type="password" wicket:id="password"/>
- <br/>
- </form>
- <button wicket:id="externalSubmitter">
- Submit
- </button>
- </body>
-</html>
-{code}
-
-*Java code:*
-
-{code}
-public class HomePage extends WebPage {
-
- public HomePage(final PageParameters parameters) {
- Form form = new Form("form");
-
- form.add(new PasswordTextField("password", Model.of("")));
- //specify the form to submit
- add(new SubmitLink("externalSubmitter", form));
- add(form);
- }
-}
{code}
+public HomePage(final PageParameters parameters) {
+ super(parameters);
-h3. Disabling default form processing
+ setDefaultModel(new CompoundPropertyModel<Person>(new Person()));
+
+ Form<Void> form = new Form<Void>("form");
+
+ form.add(new TextField("name").add(new PropertyValidator()));
+ form.add(new TextField("email").add(new PropertyValidator()));
+ form.add(new TextField("age").add(new PropertyValidator()));
+ //...
+}
+{code}
-With an IFormSubmittingComponent we can choose to skip the default form submission process by setting the appropriate flag to false with the setDefaultFormProcessing method. When the default form processing is disabled only the submitter's onSubmit is called while form's validation and models updating are skipped.
+Now we can run our application an see that JSR 303 annotations are fully effective:
-This can be useful if we want to implement a âCancelâ button on our form which redirects user to another page without validating his/her input.
+!jsr303-form-validation.png!
-When we set this flag to false we can decide to manually invoke the form processing by calling the process(IFormSubmittingComponent) method.
\ No newline at end of file
Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_5.gdoc
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_5.gdoc?rev=1589849&r1=1589848&r2=1589849&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_5.gdoc (original)
+++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_5.gdoc Thu Apr 24 19:41:13 2014
@@ -1,22 +1,124 @@
-As you might already known, HTLM doesn't allow to have nested forms. However with Wicket we can overcome this limitation by adding one or more form components to a parent form.
+Besides submitting forms with a standard HTML submit button, Wicket allows us to use special components which implement interface IFormSubmittingComponent. This entity is a subinterface of IFormSubmitter:
-This can be useful if we want to split a big form into smaller ones in order to reuse them and to better distribute responsibilities among different components.
-Forms can be nested to an arbitrary level:
+!class-diag-IFormSubmittingComponent.png!
+
+At the beginning of this chapter we have seen that form processing is started by process method which takes as input an instance of IFormSubmitter. This parameter corresponds to the IFormSubmittingComponent clicked by a user to submit the form and it is null if we have used a standard HTML submit button (like we have done so far).
+
+A submitting component is added to a form just like any other child component using method add(Component...).
+
+A form can have any number of submitting components and we can specify which one among them is the default one by calling the Form's method setDefaultButton(IFormSubmittingComponent  component). The default submitter is the one that will be used when user presses 'Enter' key in a field of the form. In order to make the default button work, Wicket will add to our form a hidden <div> tag containing a text field and a submit button with some JavaScript code to trigger it:
+
+{code:html}
+<div style="width:0px;height:0px;position:absolute;left:-100px;top:-100px;overflow:hidden">
+ <input type="text" autocomplete="off"/>
+ <input type="submit" name="submit2" onclick=" var b=document...."/>
+</div>
+{code}
+
+Just like Wicket forms, interface IFormSubmitter defines methods onSubmit and onError. These two methods have the priority over the namesake methods of the form, meaning that when a form is submitted with an IFormSubmitter, the onSubmit of the submitter is called before the one of the form. Similarly, if validation errors occurs during the first step of form processing, submitter's method onError is called before the form's one.
+
+{note}
+Starting with Wicket version 6.0 interface IFormSubmitter defines a further callback method called onAfterSubmit(). This method is called after form's method onSubmit() has been executed.
+{note}
+
+h3. Components Button and SubmitLink
+
+Component @org.apache.wicket.markup.html.form.Button@ is a basic implementation of a form submitter. It can be used with either the <input> or <button> tags. The string model received as input by its constructor is used as button label and it will be the value of the markup attribute value.
+
+In the following snippet we have a form with two submit buttons bound to an <input> tag. One of them is set as default button and both have a string model for the label:
+
+*HTML:*
+
+{code:html}
+<body>
+ <form wicket:id="form">
+ Username: <input type="text" wicket:id="username"/>
+ <br/>
+ <input type="submit" wicket:id="submit1"/>
+ <input type="submit" wicket:id="submit2"/>
+ </form>
+</body>
+{code}
+
+*Java code:*
+
+{code}
+public class HomePage extends WebPage {
+
+ public HomePage(final PageParameters parameters) {
+ Form form = new Form("form");
+
+ form.add(new TextField("username", Model.of("")));
+ form.add(new Button("submit1", Model.of("First submitter")));
+ Button secondSubmitter;
+ form.add(secondSubmitter = new Button("submit2", Model.of("Second submitter")));
+
+ form.setDefaultButton(secondSubmitter);
+ add(form);
+ }
+}
+{code}
+
+*Generated markup:*
{code:html}
-<form wicket:id="outerForm">
- ...
- <form wicket:id="innerForm">
- ...
- <form wicket:id="veryInnerForm">
- ...
- </form>
- </form>
+<form wicket:id="form" id="form1" method="post" action="?0-1.IFormSubmitListener-form">
+ <div>
+ ...
+ <!-- Code generated by Wicket to handle the default button -->
+ ...
+ </div>
+ Username: <input type="text" wicket:id="username" value="" name="username"/>
+ <br/>
+ <input type="submit" wicket:id="submit1" name="submit1" id="submit13" value="First submitter"/>
+ <input type="submit" wicket:id="submit2" name="submit2" id="submit22" value="Second submitter"/>
</form>
{code}
-When a form is submitted also its nested forms are submitted and they participate in the validation step. This means that if a nested form contains invalid input values, the outer form won't be submitted. On the contrary, nested forms can be singularly submitted without depending on the status of their outer form.
+Another component that can be used to submit a form is @org.apache.wicket.markup.html.form.SubmitLink@. This component uses JavaScript to submit the form. Like the name suggests, the component can be used with the <a> tag but it can be also bound to any other tag that supports the event handler onclick. When used with the <a> tag, the JavaScript code needed to submit the form will be placed inside href attribute while with other tags the script will go inside the event handler onclick.
+
+A notable difference between this component and Button is that SubmitLink can be placed outside the form it must submit. In this case we must specify the form to submit in its constructor:
+
+*HTML:*
+
+{code:html}
+<html xmlns:wicket="http://wicket.apache.org">
+<head>
+ </head>
+ <body>
+ <form wicket:id="form">
+ Password: <input type="password" wicket:id="password"/>
+ <br/>
+ </form>
+ <button wicket:id="externalSubmitter">
+ Submit
+ </button>
+ </body>
+</html>
+{code}
+
+*Java code:*
+
+{code}
+public class HomePage extends WebPage {
+
+ public HomePage(final PageParameters parameters) {
+ Form form = new Form("form");
+
+ form.add(new PasswordTextField("password", Model.of("")));
+ //specify the form to submit
+ add(new SubmitLink("externalSubmitter", form));
+ add(form);
+ }
+}
+{code}
+
+h3. Disabling default form processing
+
+With an IFormSubmittingComponent we can choose to skip the default form submission process by setting the appropriate flag to false with the setDefaultFormProcessing method. When the default form processing is disabled only the submitter's onSubmit is called while form's validation and models updating are skipped.
+
+This can be useful if we want to implement a âCancelâ button on our form which redirects user to another page without validating his/her input.
-To submit a parent form when one of its children forms is submitted, we must override its method wantSubmitOnNestedFormSubmit and make it return true.
\ No newline at end of file
+When we set this flag to false we can decide to manually invoke the form processing by calling the process(IFormSubmittingComponent) method.
\ No newline at end of file
Modified: wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_6.gdoc
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_6.gdoc?rev=1589849&r1=1589848&r2=1589849&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_6.gdoc (original)
+++ wicket/common/site/trunk/_site/guide/guide/src/docs/guide/forms2/forms2_6.gdoc Thu Apr 24 19:41:13 2014
@@ -1,17 +1,22 @@
-HTML provides a multi-line text input control with <textarea> tag. The Wicket counterpart for this kind of control is @org.apache.wicket.markup.html.form.TextArea@ component:
+As you might already known, HTLM doesn't allow to have nested forms. However with Wicket we can overcome this limitation by adding one or more form components to a parent form.
-*HTML:*
+This can be useful if we want to split a big form into smaller ones in order to reuse them and to better distribute responsibilities among different components.
+Forms can be nested to an arbitrary level:
{code:html}
-<textarea wicket:id="description" rows="5" cols="40"></textarea>
+<form wicket:id="outerForm">
+ ...
+ <form wicket:id="innerForm">
+ ...
+ <form wicket:id="veryInnerForm">
+ ...
+ </form>
+ </form>
+</form>
{code}
-*Java code:*
+When a form is submitted also its nested forms are submitted and they participate in the validation step. This means that if a nested form contains invalid input values, the outer form won't be submitted. On the contrary, nested forms can be singularly submitted without depending on the status of their outer form.
-{code}
-form.add(new TextArea("description", Model.of("")));
-{code}
-
-Component TextArea is used just like any other single-line text field. To specify the size of the text area we can write attributes rows and cols directly in the markup file or we can create new attribute modifiers and add them to our TextArea component.
\ No newline at end of file
+To submit a parent form when one of its children forms is submitted, we must override its method wantSubmitOnNestedFormSubmit and make it return true.
\ No newline at end of file