| I"Æ4<p>One of the most problematic components for beginners of Wicket is the |
| <code class="language-plaintext highlighter-rouge">DropDownChoice</code> component. In this example we will work the component to |
| give a little more insight into its workings. This example requires that you |
| have some understanding of the Wicket component model (nothing fancy though, |
| but you might want to read the other examples first), and the Model concept |
| used in Wicket (you can read more on models |
| <a href="https://cwiki.apache.org/confluence/display/WICKET/Working+with+Wicket+models">here</a>).</p> |
| |
| <h2 id="the-example-domain">The example domain</h2> |
| |
| <p>The <code class="language-plaintext highlighter-rouge">DropDownChoice</code> component is typically used <em>inside</em> a form. This |
| example will expand on that usage. The component is particularly designed to |
| work with objects. So letâs say we have a list of people and we want to |
| select the manager of an employee.</p> |
| |
| <figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">Person</span> <span class="o">{</span> |
| <span class="kd">private</span> <span class="nc">Long</span> <span class="n">id</span><span class="o">;</span> |
| <span class="kd">private</span> <span class="nc">String</span> <span class="n">name</span><span class="o">;</span> |
| <span class="kd">private</span> <span class="nc">Person</span> <span class="n">managedBy</span><span class="o">;</span> |
| |
| <span class="c1">// ... insert getters and setters</span> |
| |
| <span class="cm">/** |
| * Used to display the person. |
| */</span> |
| <span class="kd">public</span> <span class="nc">String</span> <span class="nf">toString</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">return</span> <span class="n">name</span><span class="o">;</span> |
| <span class="o">}</span> |
| |
| <span class="cm">/** |
| * Gets the list of possible managers from the database. |
| */</span> |
| <span class="kd">public</span> <span class="kd">static</span> <span class="nc">List</span><span class="o"><</span><span class="nc">Person</span><span class="o">></span> <span class="nf">getManagers</span><span class="o">()</span> <span class="o">{</span> |
| <span class="c1">// gets the managers from the database</span> |
| <span class="o">}</span> |
| <span class="o">}</span></code></pre></figure> |
| |
| <h2 id="the-assign-manager-page">The assign manager page</h2> |
| |
| <p>Next we want to create a page where we assign a manager to an employee. This |
| is how the page would look like in HTML:</p> |
| |
| <figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt"><html></span> |
| <span class="nt"><body></span> |
| <span class="nt"><form</span> <span class="na">wicket:id=</span><span class="s">"form"</span><span class="nt">></span> |
| <span class="nt"><h1></span>Assign manager<span class="nt"></h1></span> |
| <span class="nt"><table></span> |
| <span class="nt"><tr></span> |
| <span class="nt"><th></span>Name<span class="nt"></th></span> |
| <span class="nt"><td</span> <span class="na">wicket:id=</span><span class="s">"name"</span><span class="nt">></span>Some employee<span class="nt"></td></span> |
| <span class="nt"></tr></span> |
| <span class="nt"><tr></span> |
| <span class="nt"><th></span>Managed by<span class="nt"></th></span> |
| <span class="nt"><td><select</span> <span class="na">wicket:id=</span><span class="s">"managedBy"</span><span class="nt">></span> |
| <span class="nt"><option></span>Some Person<span class="nt"></option></span> |
| <span class="nt"><option></span>Some Other Person<span class="nt"></option></span> |
| <span class="nt"></select></span> |
| <span class="nt"></td></span> |
| <span class="nt"></tr></span> |
| <span class="nt"><tr><td</span> <span class="na">colspan=</span><span class="s">"2"</span><span class="nt">><input</span> <span class="na">type=</span><span class="s">"submit"</span> <span class="na">value=</span><span class="s">"Save"</span><span class="nt">/></td></tr></span> |
| <span class="nt"></table></span> |
| <span class="nt"></form></span> |
| <span class="nt"></body></span> |
| <span class="nt"></html></span></code></pre></figure> |
| |
| <p>This page has three components:</p> |
| |
| <ul> |
| <li>a form (needed to process the input),</li> |
| <li>a label (to show the name of the employee) and</li> |
| <li>a select box for picking the manager.</li> |
| </ul> |
| |
| <p>We will focus on the select box, because that will be our <code class="language-plaintext highlighter-rouge">DropDownChoice</code>. |
| The <code class="language-plaintext highlighter-rouge"><option></code> tags are there for preview, our component will replace them |
| with the generated choices.</p> |
| |
| <p>Letâs see how the page looks like from the Java side:</p> |
| |
| <figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">AssignManagerPage</span> <span class="kd">extends</span> <span class="nc">WebPage</span> <span class="o">{</span> |
| <span class="kd">public</span> <span class="nf">AssignManagerPage</span><span class="o">(</span><span class="nc">Person</span> <span class="n">employee</span><span class="o">)</span> <span class="o">{</span> |
| <span class="nc">Form</span> <span class="n">form</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">Form</span><span class="o">(</span><span class="s">"form"</span><span class="o">);</span> |
| <span class="n">add</span><span class="o">(</span><span class="n">form</span><span class="o">);</span> |
| <span class="n">form</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="k">new</span> <span class="nc">Label</span><span class="o">(</span><span class="s">"name"</span><span class="o">,</span> <span class="k">new</span> <span class="nc">PropertyModel</span><span class="o"><</span><span class="nc">String</span><span class="o">>(</span><span class="n">employee</span><span class="o">,</span> <span class="s">"name"</span><span class="o">)));</span> |
| |
| <span class="nc">DropDownChoice</span><span class="o"><</span><span class="nc">Person</span><span class="o">></span> <span class="n">ddc</span> <span class="o">=</span> |
| <span class="k">new</span> <span class="nc">DropDownChoice</span><span class="o"><</span><span class="nc">Person</span><span class="o">>(</span><span class="s">"name"</span><span class="o">,</span> |
| <span class="k">new</span> <span class="nc">PropertyModel</span><span class="o"><</span><span class="nc">Person</span><span class="o">>(</span><span class="n">employee</span><span class="o">,</span> <span class="s">"managedBy"</span><span class="o">),</span> |
| <span class="k">new</span> <span class="nc">LoadableDetachableModel</span><span class="o"><</span><span class="nc">List</span><span class="o"><</span><span class="nc">Person</span><span class="o">>>()</span> <span class="o">{</span> |
| <span class="nd">@Override</span> |
| <span class="kd">protected</span> <span class="nc">Object</span> <span class="nf">load</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">return</span> <span class="nc">Person</span><span class="o">.</span><span class="na">getManagers</span><span class="o">();</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| <span class="o">);</span> |
| <span class="n">form</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">ddc</span><span class="o">));</span> |
| <span class="o">}</span> |
| <span class="o">}</span></code></pre></figure> |
| |
| <p>In this example you see that we add the <code class="language-plaintext highlighter-rouge">DropDownChoice</code> to the form, and |
| provide it with 3 parameters. The first is the component identifier. The |
| second is the item that needs to be updated, in this case the <code class="language-plaintext highlighter-rouge">managedBy</code> |
| field of the <code class="language-plaintext highlighter-rouge">employee</code>. The third parameter is a <code class="language-plaintext highlighter-rouge">LoadableDetachableModel</code> |
| that retrieves the list of available choices.</p> |
| |
| <p>Note that the <code class="language-plaintext highlighter-rouge">DropDownChoice</code> component has many constructors, and that you |
| need to read the JavaDoc documentation to pick the right one for you.</p> |
| |
| <p>This generates (basically) the following markup when the list of managers is |
| Kyle Brovlovski, Stan Marsh, Eric Cartman, and Kenny McCormick:</p> |
| |
| <figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt"><tr></span> |
| <span class="nt"><th></span>Managed by<span class="nt"></th></span> |
| <span class="nt"><td></span> |
| <span class="nt"><select</span> <span class="na">wicket:id=</span><span class="s">"managedBy"</span> <span class="na">name=</span><span class="s">"managedBy"</span><span class="nt">></span> |
| <span class="nt"><option</span> <span class="na">selected=</span><span class="s">"selected"</span> <span class="na">value=</span><span class="s">""</span><span class="nt">></span>Choose one<span class="nt"></option></span> |
| <span class="nt"><option</span> <span class="na">value=</span><span class="s">"0"</span><span class="nt">></span>Kyle Brovlovski<span class="nt"></option></span> |
| <span class="nt"><option</span> <span class="na">value=</span><span class="s">"1"</span><span class="nt">></span>Stan Marsh<span class="nt"></option></span> |
| <span class="nt"><option</span> <span class="na">value=</span><span class="s">"2"</span><span class="nt">></span>Eric Cartman<span class="nt"></option></span> |
| <span class="nt"><option</span> <span class="na">value=</span><span class="s">"3"</span><span class="nt">></span>Kenny McCormick<span class="nt"></option></span> |
| <span class="nt"></select></span> |
| <span class="nt"></td></span> |
| <span class="nt"></tr></span></code></pre></figure> |
| |
| <p>As you can see from this markup is that Wicket added the items of the |
| managers list and numbered the values of the options. These are the indices |
| of the items in the list. If the order of the list can change between |
| requests, <em>or</em> if the list itself can change, then please use an |
| <code class="language-plaintext highlighter-rouge">IChoiceRenderer</code>.</p> |
| |
| <h2 id="selecting-a-choice">Selecting a choice</h2> |
| |
| <p>Now if a user selects a value and submits the form, Wicket will assign the |
| manager to the employee (the <code class="language-plaintext highlighter-rouge">PropertyModel</code> takes care of that). The |
| following list shows what basically happens:</p> |
| |
| <ol> |
| <li>create new Employee, with <code class="language-plaintext highlighter-rouge">null</code> for its manager</li> |
| <li>create AssignManagerPage with the employee</li> |
| <li>render page, selected value is <code class="language-plaintext highlighter-rouge">"Choose one"</code></li> |
| <li>user selects âEric Cartmanâ and submits form</li> |
| <li>Wicket assigns manager âEric Cartmanâ to <code class="language-plaintext highlighter-rouge">managedBy</code> field of the employee</li> |
| </ol> |
| |
| <p>So there is no need for getting or setting the value from the drop down |
| component: Wicket binds directly to your domain objects if you use the |
| correct models.</p> |
| |
| <h2 id="selecting-a-default-choice">Selecting a default choice</h2> |
| |
| <p>If you want to select a default value for the manager, then all you need to |
| do is assign the default manager to the employee and Wicket will take care of |
| the rest:</p> |
| |
| <figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="c1">// some add new employee code</span> |
| <span class="nc">Employee</span> <span class="n">manager</span> <span class="o">=</span> <span class="nc">Employee</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">"Eric Cartman"</span><span class="o">);</span> <span class="c1">// gets a manager</span> |
| <span class="nc">Employee</span> <span class="n">newEmployee</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">Employee</span><span class="o">();</span> |
| <span class="n">newEmployee</span><span class="o">.</span><span class="na">setManagedBy</span><span class="o">(</span><span class="n">manager</span><span class="o">);</span> |
| |
| <span class="n">setResponsePage</span><span class="o">(</span><span class="k">new</span> <span class="nc">AssignManagerPage</span><span class="o">(</span><span class="n">newEmployee</span><span class="o">));</span></code></pre></figure> |
| |
| <h2 id="summary">Summary</h2> |
| |
| <p>This concludes the (small) example of using a <code class="language-plaintext highlighter-rouge">DropDownChoice</code> component |
| correctly. The ideas behind Wicket are perfectly reflected in this component: |
| work with your domain objects, bind them to your components and get on with |
| the rest of your application.</p> |
| :ET |