1.1 --- a/docs/multivalue.html Sun Nov 29 02:01:41 2009 +0100
1.2 +++ b/docs/multivalue.html Wed Feb 24 00:59:37 2010 +0100
1.3 @@ -6,6 +6,7 @@
1.4 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.5 <body>
1.6 <h1>Creating Applications: Adding Multivalued Fields</h1>
1.7 +
1.8 <p>Although some applications only require multiple-choice fields where
1.9 only a single value may be chosen, in many situations it is desirable
1.10 to be able to choose an arbitrary number of values for a particular
1.11 @@ -13,80 +14,189 @@
1.12 represent form data using a single attribute on a single element to
1.13 represent any given field value. With multivalued fields, we must
1.14 choose a different strategy in using XML to represent such information.</p>
1.15 +
1.16 <p>Let us consider permitting multiple type values to be associated
1.17 with our items. We revise our <a href="data.html">form data structure</a>
1.18 -to
1.19 -be the following:</p>
1.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>
1.21 +to be the following:</p>
1.22 +
1.23 +<pre><?xml version="1.0"?>
1.24 +<structure>
1.25 + <item value="some value">
1.26 + <type>
1.27 + <type-enum value="some type"/>
1.28 + <type-enum value="some other type"/>
1.29 + </type>
1.30 + <subitem subvalue="some other value"/>
1.31 + </item>
1.32 +</structure></pre>
1.33 +
1.34 <h2>Multivalued Fields</h2>
1.35 +
1.36 <p>We shall now take advantage of those HTML form fields which permit
1.37 -users to select one
1.38 -or many values presented in a list or menu.</p>
1.39 +users to select one or many values presented in a list or menu.</p>
1.40
1.41 <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
1.42 <p>Item type:
1.43 - <select multiple="multiple" name="type"><option>(Not selected)</option><option>Important</option><option>Not important</option><option>Personal</option></select>
1.44 + <select multiple="multiple" name="type">
1.45 + <option>(Not selected)</option>
1.46 + <option>Important</option>
1.47 + <option>Not important</option>
1.48 + <option>Personal</option>
1.49 + </select>
1.50 </p>
1.51 <p>Itself containing more items:</p>
1.52 <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p>
1.53
1.54 -From the item type list many value may now be selected.
1.55 +<p>From the item type list many values may now be selected.</p>
1.56 +
1.57 <p>Taking the example HTML code from before, we can add a
1.58 definition of this new list to the template to produce something
1.59 like this:</p>
1.60 -<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>
1.61 +
1.62 +<pre><html xmlns="http://www.w3.org/1999/xhtml"
1.63 + xmlns:template="http://www.boddie.org.uk/ns/xmltools/template">
1.64 +<head>
1.65 + <title>Example</title>
1.66 +</head>
1.67 +<body template:element="structure">
1.68 +<form action="" method="post">
1.69 +
1.70 +<!-- Template text between the start and the interesting part. -->
1.71 +
1.72 +<div template:element="item">
1.73 + <p>
1.74 + Some item: <input template:attribute-field="value" name="..." type="text" value="..." />
1.75 + <input name="..." template:selector-field="remove" type="submit" value="Remove" />
1.76 + </p>
1.77 + <p>
1.78 + Item type:
1.79 + <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>>
1.80 + <option <span style="font-weight: bold;"><span style="font-family: monospace;">template:multiple-choice-list-value="type-enum,value,selected"</span></span> value="..." />
1.81 + </select>
1.82 + </p>
1.83 + <p>
1.84 + Itself containing more items:
1.85 + </p>
1.86 + <p template:element="subitem">
1.87 + Sub-item: <input template:attribute-field="subvalue" name="..." type="text" value="..." />
1.88 + <input name="..." template:selector-field="remove2" type="submit" value="Remove" />
1.89 + </p>
1.90 + <p>
1.91 + <input name="..." template:selector-field="add2,subitem" type="submit" value="Add subitem" />
1.92 + </p>
1.93 +</div>
1.94 +<p>
1.95 + <input name="..." template:selector-field="add,item" type="submit" value="Add item" />
1.96 +</p>
1.97 +
1.98 +<!-- Template text between the interesting part and the end. -->
1.99 +
1.100 +</form>
1.101 +</body>
1.102 +</html></pre>
1.103 +
1.104 <p>From the previous <a href="multiple.html">single-valued case</a>,
1.105 some crucial changes have been made:</p>
1.106 +
1.107 <ol>
1.108 <li>The <code>select</code> element remains mapped onto the <code>type</code>
1.109 -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>
1.110 -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>
1.111 -element is created within the <code>type</code>
1.112 -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>
1.113 -elements may be created within the <code>type</code>
1.114 -element, and each one of them will have a different <code>value</code> attribute.</li>
1.115 + element in the form data structure. However, we use a different attribute,
1.116 + <code>template:multiple-choice-list-field</code>, to indicate that a
1.117 + <code>type</code> element is created when the form data is submitted, but
1.118 + instead of a single value being added to the <code>value</code> attribute of
1.119 + that one element, a separate <code>type-enum</code> element is created within
1.120 + the <code>type</code> element with a value in its <code>value</code> attribute
1.121 + <span style="font-style: italic;">for each value submitted</span>. This means
1.122 + that many <code>type-enum</code> elements may be created within the
1.123 + <code>type</code> element, and each one of them will have a different
1.124 + <code>value</code> attribute.</li>
1.125 <li>Of course, the <code>select</code> element now has a <code>multiple</code>
1.126 -attribute defined to permit multiple value selections.</li>
1.127 + attribute defined to permit multiple value selections.</li>
1.128 <li>Inside the <code>select</code> element, the <code>option</code>
1.129 -element now employs the <code>template:multiple-choice-list-value</code> annotation.</li>
1.130 + element now employs the <code>template:multiple-choice-list-value</code> annotation.</li>
1.131 </ol>
1.132 +
1.133 <h2>Output Structures</h2>
1.134 +
1.135 <p>Unlike in the single-valued case, the revised the form data
1.136 structure for input is almost the same as the structure used by the
1.137 template. Indeed, the subtle differences cannot be represented in our
1.138 simplistic presentation of the structure:</p>
1.139 -<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>
1.140 +
1.141 +<pre><?xml version="1.0"?>
1.142 +<structure>
1.143 + <item value="some value">
1.144 + <type>
1.145 + <type-enum value="some type"/>
1.146 + <type-enum value="some other type"/>
1.147 + </type>
1.148 + <subitem subvalue="some other value"/>
1.149 + </item>
1.150 +</structure></pre>
1.151 +
1.152 <p>In fact, the principal difference arises through the number of <code>type-enum</code>
1.153 elements that occur in the input, representing the values selected by
1.154 the user, and the number that occur in the output, representing the
1.155 complete range of values available for selection.
1.156 </p>
1.157 +
1.158 <h3>Presenting the Extra Values</h3>
1.159 +
1.160 <p>In most respects, the presentation of the extra values is the same
1.161 as in the single-valued case. The result of the presentation of the
1.162 extra values is that the <code>type</code> element in the
1.163 this example structure fragment...</p>
1.164 -<pre><type><br /> <type-enum value="(Not selected)"/><br /> <type-enum value="Important" value-is-set="true"/><br /> <type-enum value="Not important" value-is-set="true"/><br /> <type-enum value="Personal"/><br /></type><br /></pre>
1.165 +
1.166 +<pre><type>
1.167 + <type-enum value="(Not selected)"/>
1.168 + <type-enum value="Important" value-is-set="true"/>
1.169 + <type-enum value="Not important" value-is-set="true"/>
1.170 + <type-enum value="Personal"/>
1.171 +</type>
1.172 +</pre>
1.173 +
1.174 <p>...is transformed into something resembling this HTML code:</p>
1.175 -<pre><select name="..." multiple="multiple"><br /> <option value="(Not selected)">(Not selected)</option><br /> <option value="Important" selected="selected">Important</option><br /> <option value="Not important" selected="selected">Not important</option><br /> <option value="Personal">Personal</option><br /></select><br /></pre>
1.176 +
1.177 +<pre><select name="..." multiple="multiple">
1.178 + <option value="(Not selected)">(Not selected)</option>
1.179 + <option value="Important" selected="selected">Important</option>
1.180 + <option value="Not important" selected="selected">Not important</option>
1.181 + <option value="Personal">Personal</option>
1.182 +</select>
1.183 +</pre>
1.184 +
1.185 <p>Above, the special <code>value-is-set</code>
1.186 attribute is an XSLForms mechanism to remember which values were set.
1.187 Fortunately, the document initialisation mechanism automatically
1.188 distinguishes between different multiple-choice field types and
1.189 understands where the above approach needs to be employed.</p>
1.190 -<ul>
1.191 -</ul><h3>Updating the Web Resource</h3>
1.192 +
1.193 +<h3>Updating the Web Resource</h3>
1.194 +
1.195 <p>To update the special WebStack resource, we
1.196 now need to modify a few of the class attributes and to add a few
1.197 others:</p>
1.198 -<pre> template_resources = {<br /> "structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl")<br /> }<br /></pre>
1.199 +
1.200 +<pre>
1.201 + template_resources = {
1.202 + "structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl")
1.203 + }
1.204 +</pre>
1.205 +
1.206 <p>With these adjustments, it should now be possible to manipulate the
1.207 items and subitems whilst specifying multiple type values on each item.
1.208 Note that it may be necessary to remove the old stylesheet for
1.209 producing output, <code>structure_output.xsl</code>, so that the
1.210 multivalue version of the template is taken into use.</p>
1.211 +
1.212 <h2>Improving the Presented Values</h2>
1.213 -<p>In the application we have been developing, we have been content to show the multiple-choice values as they are known in the application - that is, the application refers to values like <code>Personal</code>
1.214 -and the same text is shown to users of the application. However, there
1.215 -are various situations where this is not desirable, and the <a href="labels.html">usage of separate labels</a> is described in the next section of the development <a href="overview.html">process</a>.</p>
1.216 +
1.217 +<p>In the application we have been developing, we have been content to show the
1.218 +multiple-choice values as they are known in the application - that is, the
1.219 +application refers to values like <code>Personal</code> and the same text is
1.220 +shown to users of the application. However, there are various situations where
1.221 +this is not desirable, and the <a href="labels.html">usage of separate
1.222 +labels</a> is described in the next section of the development <a
1.223 +href="overview.html">process</a>.</p>
1.224 +
1.225 </body></html>