1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2 <html xmlns="http://www.w3.org/1999/xhtml"><head> 3 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 4 5 <title>Creating Applications: Adding Multivalued Fields</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 6 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 7 <body> 8 <h1>Creating Applications: Adding Multivalued Fields</h1> 9 <p>Although some applications only require multiple-choice fields where 10 only a single value may be chosen, in many situations it is desirable 11 to be able to choose an arbitrary number of values for a particular 12 field. However, up to this point, we have been content to 13 represent form data using a single attribute on a single element to 14 represent any given field value. With multivalued fields, we must 15 choose a different strategy in using XML to represent such information.</p> 16 <p>Let us consider permitting multiple type values to be associated 17 with our items. We revise our <a href="data.html">form data structure</a> 18 to 19 be the following:</p> 20 <pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <type><br /> <type-enum value="some type"/><br /> <type-enum value="some other type"/><br /> </type><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre> 21 <h2>Multivalued Fields</h2> 22 <p>We shall now take advantage of those HTML form fields which permit 23 users to select one 24 or many values presented in a list or menu.</p> 25 26 <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p> 27 <p>Item type: 28 <select multiple="multiple" name="type"><option>(Not selected)</option><option>Important</option><option>Not important</option><option>Personal</option></select> 29 </p> 30 <p>Itself containing more items:</p> 31 <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p> 32 33 From the item type list many value may now be selected. 34 <p>Taking the example HTML code from before, we can add a 35 definition of this new list to the template to produce something 36 like this:</p> 37 <pre><html xmlns="http://www.w3.org/1999/xhtml"<br /> xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"><br /><head><br /> <title>Example</title><br /></head><br /><body template:element="structure"><br /><form action="" method="post"><br /><br /><!-- Template text between the start and the interesting part. --><br /><br /><div template:element="item"><br /> <p><br /> Some item: <input template:attribute-field="value" name="..." type="text" value="..." /><br /> <input name="..." template:selector-field="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Item type:<br /> <select name="..." <span style="font-weight: bold;">template:multiple-choice-list-field="type,type-enum,value"</span> <span style="font-weight: bold;">multiple="multiple"</span>><br /> <option <span style="font-weight: bold;"><span style="font-family: monospace;">template:multiple-choice-list-value="type-enum,value,selected"</span></span> value="..." /><br /> </select><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p template:element="subitem"><br /> Sub-item: <input template:attribute-field="subvalue" name="..." type="text" value="..." /><br /> <input name="..." template:selector-field="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="..." template:selector-field="add2,subitem" type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="..." template:selector-field="add,item" type="submit" value="Add item" /><br /></p><span style="font-weight: bold;"><br /><br /></span><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre> 38 <p>From the previous <a href="multiple.html">single-valued case</a>, 39 some crucial changes have been made:</p> 40 <ol> 41 <li>The <code>select</code> element remains mapped onto the <code>type</code> 42 element in the form data structure. However, we use a different attribute, <code>template:multiple-choice-list-field</code>, to indicate that a <code>type</code> 43 element is created when the form data is submitted, but instead of a single value being added to the <code>value</code> attribute of that one element, a separate <code>type-enum</code> 44 element is created within the <code>type</code> 45 element with a value in its <code>value</code> attribute <span style="font-style: italic;">for each value submitted</span>. This means that many <code>type-enum</code> 46 elements may be created within the <code>type</code> 47 element, and each one of them will have a different <code>value</code> attribute.</li> 48 <li>Of course, the <code>select</code> element now has a <code>multiple</code> 49 attribute defined to permit multiple value selections.</li> 50 <li>Inside the <code>select</code> element, the <code>option</code> 51 element now employs the <code>template:multiple-choice-list-value</code> annotation.</li> 52 </ol> 53 <h2>Output Structures</h2> 54 <p>Unlike in the single-valued case, the revised the form data 55 structure for input is almost the same as the structure used by the 56 template. Indeed, the subtle differences cannot be represented in our 57 simplistic presentation of the structure:</p> 58 <pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <type><br /> <type-enum value="some type"/><br /> <type-enum value="some other type"/><br /> </type><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre> 59 <p>In fact, the principal difference arises through the number of <code>type-enum</code> 60 elements that occur in the input, representing the values selected by 61 the user, and the number that occur in the output, representing the 62 complete range of values available for selection. 63 </p> 64 <h3>Presenting the Extra Values</h3> 65 <p>In most respects, the presentation of the extra values is the same 66 as in the single-valued case. The result of the presentation of the 67 extra values is that the <code>type</code> element in the 68 this example structure fragment...</p> 69 <pre><type><br /> <type-enum value="1"/><br /> <type-enum value="2" value-is-set="true"/><br /> <type-enum value="3" value-is-set="true"/><br /></type><br /></pre> 70 <p>...is transformed into something resembling this HTML code:</p> 71 <pre><select name="..." multiple="multiple"><br /> <option value="1">1</option><br /> <option value="2" selected="selected">2</option><br /> <option value="3" selected="selected">3</option><br /></select><br /></pre> 72 <p>Above, the special <code>value-is-set</code> 73 attribute is an XSLForms mechanism to remember which values were set. 74 Fortunately, the document initialisation mechanism automatically 75 distinguishes between different multiple-choice field types and 76 understands where the above approach needs to be employed.</p> 77 <ul> 78 </ul><h3>Updating the Web Resource</h3> 79 <p>To update the special WebStack resource, we 80 now need to modify a few of the class attributes and to add a few 81 others:</p> 82 <pre> template_resources = {<br /> "structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl")<br /> }<br /></pre> 83 <p>With these adjustments, it should now be possible to manipulate the 84 items and subitems whilst specifying multiple type values on each item. 85 Note that it may be necessary to remove the old stylesheet for 86 producing output, <code>structure_output.xsl</code>, so that the 87 multivalue version of the template is taken into use.</p> 88 <h2>Further Reading</h2> 89 <p>Now that we have designed and implemented a simple application, it 90 may be worth reading some <a href="advice.html">recommendations</a> 91 about developing your own applications.</p> 92 </body></html>