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