1 <?xml version="1.0" encoding="iso-8859-1"?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3 <html xmlns="http://www.w3.org/1999/xhtml"><head> 4 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 5 <title>Creating Applications: Adding Multivalued Fields</title> 6 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 7 <body> 8 <h1>Creating Applications: Adding Multivalued Fields</h1> 9 10 <p>Although some applications only require multiple-choice fields where 11 only a single value may be chosen, in many situations it is desirable 12 to be able to choose an arbitrary number of values for a particular 13 field. However, up to this point, we have been content to 14 represent form data using a single attribute on a single element to 15 represent any given field value. With multivalued fields, we must 16 choose a different strategy in using XML to represent such information.</p> 17 18 <p>Let us consider permitting multiple type values to be associated 19 with our items. We revise our <a href="data.html">form data structure</a> 20 to be the following:</p> 21 22 <pre><?xml version="1.0"?> 23 <structure> 24 <item value="some value"> 25 <type> 26 <type-enum value="some type"/> 27 <type-enum value="some other type"/> 28 </type> 29 <subitem subvalue="some other value"/> 30 </item> 31 </structure></pre> 32 33 <h2>Multivalued Fields</h2> 34 35 <p>We shall now take advantage of those HTML form fields which permit 36 users to select one or many values presented in a list or menu.</p> 37 38 <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p> 39 <p>Item type: 40 <select multiple="multiple" name="type"> 41 <option>(Not selected)</option> 42 <option>Important</option> 43 <option>Not important</option> 44 <option>Personal</option> 45 </select> 46 </p> 47 <p>Itself containing more items:</p> 48 <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p> 49 50 <p>From the item type list many values may now be selected.</p> 51 52 <p>Taking the example HTML code from before, we can add a 53 definition of this new list to the template to produce something 54 like this:</p> 55 56 <pre><html xmlns="http://www.w3.org/1999/xhtml" 57 xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"> 58 <head> 59 <title>Example</title> 60 </head> 61 <body template:element="structure"> 62 <form action="" method="post"> 63 64 <!-- Template text between the start and the interesting part. --> 65 66 <div template:element="item"> 67 <p> 68 Some item: <input template:attribute-field="value" name="..." type="text" value="..." /> 69 <input name="..." template:selector-field="remove" type="submit" value="Remove" /> 70 </p> 71 <p> 72 Item type: 73 <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>> 74 <option <span style="font-weight: bold;"><span style="font-family: monospace;">template:multiple-choice-list-value="type-enum,value,selected"</span></span> value="..." /> 75 </select> 76 </p> 77 <p> 78 Itself containing more items: 79 </p> 80 <p template:element="subitem"> 81 Sub-item: <input template:attribute-field="subvalue" name="..." type="text" value="..." /> 82 <input name="..." template:selector-field="remove2" type="submit" value="Remove" /> 83 </p> 84 <p> 85 <input name="..." template:selector-field="add2,subitem" type="submit" value="Add subitem" /> 86 </p> 87 </div> 88 <p> 89 <input name="..." template:selector-field="add,item" type="submit" value="Add item" /> 90 </p> 91 92 <!-- Template text between the interesting part and the end. --> 93 94 </form> 95 </body> 96 </html></pre> 97 98 <p>From the previous <a href="multiple.html">single-valued case</a>, 99 some crucial changes have been made:</p> 100 101 <ol> 102 <li>The <code>select</code> element remains mapped onto the <code>type</code> 103 element in the form data structure. However, we use a different attribute, 104 <code>template:multiple-choice-list-field</code>, to indicate that a 105 <code>type</code> element is created when the form data is submitted, but 106 instead of a single value being added to the <code>value</code> attribute of 107 that one element, a separate <code>type-enum</code> element is created within 108 the <code>type</code> element with a value in its <code>value</code> attribute 109 <span style="font-style: italic;">for each value submitted</span>. This means 110 that many <code>type-enum</code> elements may be created within the 111 <code>type</code> element, and each one of them will have a different 112 <code>value</code> attribute.</li> 113 <li>Of course, the <code>select</code> element now has a <code>multiple</code> 114 attribute defined to permit multiple value selections.</li> 115 <li>Inside the <code>select</code> element, the <code>option</code> 116 element now employs the <code>template:multiple-choice-list-value</code> annotation.</li> 117 </ol> 118 119 <h2>Output Structures</h2> 120 121 <p>Unlike in the single-valued case, the revised the form data 122 structure for input is almost the same as the structure used by the 123 template. Indeed, the subtle differences cannot be represented in our 124 simplistic presentation of the structure:</p> 125 126 <pre><?xml version="1.0"?> 127 <structure> 128 <item value="some value"> 129 <type> 130 <type-enum value="some type"/> 131 <type-enum value="some other type"/> 132 </type> 133 <subitem subvalue="some other value"/> 134 </item> 135 </structure></pre> 136 137 <p>In fact, the principal difference arises through the number of <code>type-enum</code> 138 elements that occur in the input, representing the values selected by 139 the user, and the number that occur in the output, representing the 140 complete range of values available for selection. 141 </p> 142 143 <h3>Presenting the Extra Values</h3> 144 145 <p>In most respects, the presentation of the extra values is the same 146 as in the single-valued case. The result of the presentation of the 147 extra values is that the <code>type</code> element in the 148 this example structure fragment...</p> 149 150 <pre><type> 151 <type-enum value="(Not selected)"/> 152 <type-enum value="Important" value-is-set="true"/> 153 <type-enum value="Not important" value-is-set="true"/> 154 <type-enum value="Personal"/> 155 </type> 156 </pre> 157 158 <p>...is transformed into something resembling this HTML code:</p> 159 160 <pre><select name="..." multiple="multiple"> 161 <option value="(Not selected)">(Not selected)</option> 162 <option value="Important" selected="selected">Important</option> 163 <option value="Not important" selected="selected">Not important</option> 164 <option value="Personal">Personal</option> 165 </select> 166 </pre> 167 168 <p>Above, the special <code>value-is-set</code> 169 attribute is an XSLForms mechanism to remember which values were set. 170 Fortunately, the document initialisation mechanism automatically 171 distinguishes between different multiple-choice field types and 172 understands where the above approach needs to be employed.</p> 173 174 <h3>Updating the Web Resource</h3> 175 176 <p>To update the special WebStack resource, we 177 now need to modify a few of the class attributes and to add a few 178 others:</p> 179 180 <pre> 181 template_resources = { 182 "structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl") 183 } 184 </pre> 185 186 <p>With these adjustments, it should now be possible to manipulate the 187 items and subitems whilst specifying multiple type values on each item. 188 Note that it may be necessary to remove the old stylesheet for 189 producing output, <code>structure_output.xsl</code>, so that the 190 multivalue version of the template is taken into use.</p> 191 192 <h2>Improving the Presented Values</h2> 193 194 <p>In the application we have been developing, we have been content to show the 195 multiple-choice values as they are known in the application - that is, the 196 application refers to values like <code>Personal</code> and the same text is 197 shown to users of the application. However, there are various situations where 198 this is not desirable, and the <a href="labels.html">usage of separate 199 labels</a> is described in the next section of the development <a 200 href="overview.html">process</a>.</p> 201 202 </body></html>