1.1 --- a/docs/multiple.html Sun Feb 03 22:44:31 2008 +0000
1.2 +++ b/docs/multiple.html Tue Feb 05 17:25:31 2008 +0000
1.3 @@ -6,48 +6,117 @@
1.4 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.5 <body>
1.6 <h1>Creating Applications: Adding Multiple-Choice Fields and Values</h1>
1.7 +
1.8 <p>Up to this point, we have only considered two kinds of Web form
1.9 fields: text entry fields and action buttons. Since most Web forms
1.10 offer more convenient ways of entering certain kinds of data, we shall
1.11 now investigate multiple-choice fields as an example of how XSLForms
1.12 handles more complicated types of fields.</p>
1.13 +
1.14 <p>We shall revise our <a href="data.html">form data structure</a> to
1.15 be the following:</p>
1.16 -<pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <type value="some type"/><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre>
1.17 +
1.18 +<pre><?xml version="1.0"?>
1.19 +<structure>
1.20 + <item value="some value">
1.21 + <type value="some type"/>
1.22 + <subitem subvalue="some other value"/>
1.23 + </item>
1.24 +</structure></pre>
1.25 +
1.26 <h2>Single-Valued Fields</h2>
1.27 +
1.28 <p>Whilst HTML offers types of form fields where users can select one
1.29 or many values presented in a list or menu, we shall first consider the
1.30 case where only a single value can be chosen from such a selection.</p>
1.31 +
1.32 <form method="post" action="" name="single">
1.33 <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
1.34 <p>Item type:
1.35 - <select name="type"><option>(Not selected)</option><option>Important</option><option>Not important</option><option>Personal</option></select>
1.36 + <select name="type">
1.37 + <option>(Not selected)</option>
1.38 + <option>Important</option>
1.39 + <option>Not important</option>
1.40 + <option>Personal</option>
1.41 + </select>
1.42 </p>
1.43 <p>Itself containing more items:</p>
1.44 <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p>
1.45 </form>
1.46 -From the item type list only one value may be selected.
1.47 +
1.48 +<p>From the item type list only one value may be selected.</p>
1.49 +
1.50 <p>Taking the example HTML code from before, we can add a
1.51 definition of this new list to the template to produce something
1.52 like this:</p>
1.53 -<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 /> <span style="font-weight: bold;"><p></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> Item type:</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <select template:multiple-choice-field="type,value" name="..."></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <option template:multiple-choice-value="type-enum,value,selected" value="..." /></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> </select></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> </p></span><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.54 +
1.55 +<pre>
1.56 +<html xmlns="http://www.w3.org/1999/xhtml"
1.57 + xmlns:template="http://www.boddie.org.uk/ns/xmltools/template">
1.58 +<head>
1.59 + <title>Example</title>
1.60 +</head>
1.61 +<body template:element="structure">
1.62 +<form action="" method="post">
1.63 +
1.64 +<!-- Template text between the start and the interesting part. -->
1.65 +
1.66 +<div template:element="item">
1.67 + <p>
1.68 + Some item: <input template:attribute-field="value" name="..." type="text" value="..." />
1.69 + <input name="..." template:selector-field="remove" type="submit" value="Remove" />
1.70 + </p>
1.71 + <span style="font-weight: bold;"><p></span>
1.72 + <span style="font-weight: bold;">Item type:</span>
1.73 + <span style="font-weight: bold;"><select template:multiple-choice-field="type,value" name="..."></span>
1.74 + <span style="font-weight: bold;"><option template:multiple-choice-value="type-enum,value,selected" value="..." /></span>
1.75 + <span style="font-weight: bold;"></select></span>
1.76 + <span style="font-weight: bold;"></p></span>
1.77 + <p>
1.78 + Itself containing more items:
1.79 + </p>
1.80 + <p template:element="subitem">
1.81 + Sub-item: <input template:attribute-field="subvalue" name="..." type="text" value="..." />
1.82 + <input name="..." template:selector-field="remove2" type="submit" value="Remove" />
1.83 + </p>
1.84 + <p>
1.85 + <input name="..." template:selector-field="add2,subitem" type="submit" value="Add subitem" />
1.86 + </p>
1.87 +</div>
1.88 +<p>
1.89 + <input name="..." template:selector-field="add,item" type="submit" value="Add item" />
1.90 +</p>
1.91 +
1.92 +<!-- Template text between the interesting part and the end. -->
1.93 +
1.94 +</form>
1.95 +</body>
1.96 +</html>
1.97 +</pre>
1.98 +
1.99 <p>There are a lot of details here that need to be explained. Here is
1.100 what was done:</p>
1.101 +
1.102 <ol>
1.103 <li>A paragraph was added to provide some space on the page for the
1.104 -field.</li>
1.105 + field.</li>
1.106 <li>Inside the paragraph, next to the label text, an HTML <code>select</code>
1.107 -element was added.</li>
1.108 + element was added.</li>
1.109 <li>The <code>select</code> element is mapped onto the <code>type</code>
1.110 -element in the form data structure, indicating using a special <code>template:multiple-choice-field</code> attribute that the <code>value</code> attribute of the <code>type</code>
1.111 -element will contain any chosen value from the list of values displayed in the page.</li>
1.112 + element in the form data structure, indicating using a special
1.113 + <code>template:multiple-choice-field</code> attribute that the
1.114 + <code>value</code> attribute of the <code>type</code> element will
1.115 + contain any chosen value from the list of values displayed in the page.</li>
1.116 <li>Inside the <code>select</code> element, we include an <code>option</code>
1.117 -element which defines the values which will be presented to users
1.118 -of the form. Here, the special <code>template:multiple-choice-value</code> attribute indicates that the <code>option</code> element maps onto
1.119 -a <code>type-enum</code> element which is not mentioned in our
1.120 -revised form data structure above; this will be discussed below.</li>
1.121 + element which defines the values which will be presented to users
1.122 + of the form. Here, the special <code>template:multiple-choice-value</code>
1.123 + attribute indicates that the <code>option</code> element maps onto a
1.124 + <code>type-enum</code> element which is not mentioned in our revised
1.125 + form data structure above; this will be discussed below.</li>
1.126 </ol>
1.127 +
1.128 <h2>Output Structures</h2>
1.129 +
1.130 <p>Although we revised the form data structure above, and whilst the
1.131 revised structure can describe form data submitted by users of our
1.132 application, it is unfortunately not sufficient to define the form data
1.133 @@ -55,28 +124,68 @@
1.134 be presented to users: such values are not defined in our revised
1.135 structure. Therefore, we shall define an output form data structure as
1.136 follows:</p>
1.137 -<pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <type value="some type"><br /> <type-enum value="choice #n"/><br /> </type><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre>
1.138 +
1.139 +<pre>
1.140 +<?xml version="1.0"?>
1.141 +<structure>
1.142 + <item value="some value">
1.143 + <type value="some type">
1.144 + <type-enum value="choice #n"/>
1.145 + </type>
1.146 + <subitem subvalue="some other value"/>
1.147 + </item>
1.148 +</structure>
1.149 +</pre>
1.150 +
1.151 <h3>Presenting the Extra Values</h3>
1.152 +
1.153 <p>In the template, the <code>option</code> element is presented
1.154 using a number of special annotations which make more sense when
1.155 considering the above output structure:</p>
1.156 +
1.157 <ul>
1.158 <li>The <code>template:multiple-choice-value</code> annotation states that the
1.159 <code>option</code> element maps into the <code>type-enum</code>
1.160 -element, meaning that each <code>type-enum</code> element will be
1.161 -reproduced as an option inside the list or menu presented in the Web
1.162 -form.</li>
1.163 + element, meaning that each <code>type-enum</code> element will be
1.164 + reproduced as an option inside the list or menu presented in the Web
1.165 + form.</li>
1.166 <li>The <code>template:multiple-choice-value</code> annotation also states that the
1.167 -contents of the <code>option</code> element will correspond to
1.168 -the value of the <code>type-enum</code> element's <code>value</code>
1.169 -attribute.</li>
1.170 - <li>The <code>template:multiple-choice-value</code> annotation provides a final piece of information: the name of an attribute which will be created on the <code>option</code> element if the element's value matches the enclosing <code>select</code> element's value. This has the effect of making sure that the <code>select</code> element always reveals the selected value in its list of values.
1.171 - </li><li>The <code>value</code> attribute is set to a value which does not matter - it will be replaced in the final output.</li></ul>
1.172 + contents of the <code>option</code> element will correspond to
1.173 + the value of the <code>type-enum</code> element's <code>value</code>
1.174 + attribute.</li>
1.175 + <li>The <code>template:multiple-choice-value</code> annotation provides
1.176 + a final piece of information: the name of an attribute which will be
1.177 + created on the <code>option</code> element if the element's value
1.178 + matches the enclosing <code>select</code> element's value. This has
1.179 + the effect of making sure that the <code>select</code> element always
1.180 + reveals the selected value in its list of values.</li>
1.181 + <li>The <code>value</code> attribute is set to a value which does not
1.182 + matter - it will be replaced in the final output.</li>
1.183 +</ul>
1.184 +
1.185 <p>The result of this is that the <code>type</code> element in the
1.186 this example structure fragment...</p>
1.187 -<pre><type value="2"><br /> <type-enum value="(Not selected)"/><br /> <type-enum value="Important"/><br /> <type-enum value="Not important"/><br /> <type-enum value="Personal"/><br /></type></pre>
1.188 +
1.189 +<pre>
1.190 +<type value="2">
1.191 + <type-enum value="(Not selected)"/>
1.192 + <type-enum value="Important"/>
1.193 + <type-enum value="Not important"/>
1.194 + <type-enum value="Personal"/>
1.195 +</type>
1.196 +</pre>
1.197 +
1.198 <p>...is transformed into something resembling this HTML code:</p>
1.199 -<pre><select name="..."><br /> <option value="(Not selected)">(Not selected)</option><br /> <option value="Important" selected="selected">Important</option><br /> <option value="Not important">Not important</option><br /> <option value="Personal">Personal</option><br /></select></pre>
1.200 +
1.201 +<pre>
1.202 +<select name="...">
1.203 + <option value="(Not selected)">(Not selected)</option>
1.204 + <option value="Important" selected="selected">Important</option>
1.205 + <option value="Not important">Not important</option>
1.206 + <option value="Personal">Personal</option>
1.207 +</select>
1.208 +</pre>
1.209 +
1.210 <p>Such presentation techniques are sufficient if the input form data
1.211 structure is identical to the output structure, but since we will
1.212 receive a structure resembling that defined
1.213 @@ -85,50 +194,97 @@
1.214 will
1.215 need to find a way of merging the range of allowed values into the
1.216 user-edited form data before presenting that data using our template.</p>
1.217 +
1.218 <h2><a name="DocumentInitialisation"></a>Document Initialisation</h2>
1.219 +
1.220 <p>There are many possible ways of inserting extra XML elements into an
1.221 existing XML document, but XSLForms provides an easy way of defining
1.222 lists of values that will be included in the way we desire. First, let
1.223 us define a
1.224 document containing all the possible values for the type field:</p>
1.225 -<pre><?xml version="1.0"?><br /><type><br /> <type-enum value="(Not selected)"/><br /> <type-enum value="Important"/><br /> <type-enum value="Not important"/><br /> <type-enum value="Personal"/><br /></type></pre>
1.226 +
1.227 +<pre>
1.228 +<?xml version="1.0"?>
1.229 +<type>
1.230 + <type-enum value="(Not selected)"/>
1.231 + <type-enum value="Important"/>
1.232 + <type-enum value="Not important"/>
1.233 + <type-enum value="Personal"/>
1.234 +</type>
1.235 +</pre>
1.236 +
1.237 <p>We shall refer to this document when inserting the different <code>type-enum</code>
1.238 elements into our input form data structure to produce the output
1.239 structure described above; it can be
1.240 found in <code>examples/Common/VerySimple/Resources/structure_types.xml</code>.</p>
1.241 +
1.242 <h3>Amending the Resource</h3>
1.243 +
1.244 <p>To take advantage of this new information, it is necessary to
1.245 introduce some code into the Web resource to perform the document initialisation. The special WebStack resource that we <a href="Web-resource.html">subclassed earlier</a> provides some
1.246 convenient mechanisms for introducing XML documents and initialisations, and we
1.247 shall add a few extra attributes to our resource class in order to take
1.248 advantage of them:</p>
1.249 -<pre> # Under template_resources...<br /><br /> init_resources = {<br /> "structure" : ("structure_template.xhtml", "structure_input.xsl")<br /> }<br /> document_resources = {<br /> "types" : "structure_types.xml"<br /> }</pre>
1.250 +
1.251 +<pre> # Under template_resources...
1.252 +
1.253 + init_resources = {
1.254 + "structure" : ("structure_template.xhtml", "structure_input.xsl")
1.255 + }
1.256 + document_resources = {
1.257 + "types" : "structure_types.xml"
1.258 + }</pre>
1.259 +
1.260 <p>These attributes define the following things:</p>
1.261 +
1.262 <ol>
1.263 <li>A initialisation called <code>structure</code> which links
1.264 -the <code>structure_template.xhtml</code> file (the template) to the <code>structure_input.xsl</code> stylesheet file. This is very similar to the way the <code>template_resources</code> dictionary links templates to other stylesheet files producing output.</li>
1.265 + the <code>structure_template.xhtml</code> file (the template)
1.266 + to the <code>structure_input.xsl</code> stylesheet file. This
1.267 + is very similar to the way the <code>template_resources</code>
1.268 + dictionary links templates to other stylesheet files producing
1.269 + output.</li>
1.270 <li>A document referred to by the name <code>types</code> which
1.271 -is provided by the <code>structure_types.xml</code> file.</li>
1.272 + is provided by the <code>structure_types.xml</code> file.</li>
1.273 </ol>
1.274 +
1.275 <p>To actually perform the initalisation or merge operation, we need to add a few extra
1.276 lines of code after the addition and deletion operations in the <code>respond_to_form</code>
1.277 method:</p>
1.278 -<pre> # Under the addition and deletion operations...<br /><br /> # Initialise the document, adding enumerations/ranges.<br /><br /> structure_xsl = self.prepare_initialiser("structure")<br /> types_xml = self.prepare_document("types")<br /> structure = self.get_result([structure_xsl], structure, references={"type" : types_xml})<br /><br /> # Start the response.</pre>
1.279 +
1.280 +<pre>
1.281 + # Under the addition and deletion operations...
1.282 +
1.283 + # Initialise the document, adding enumerations/ranges.
1.284 +
1.285 + structure_xsl = self.prepare_initialiser("structure")
1.286 + types_xml = self.prepare_document("types")
1.287 + structure = self.get_result([structure_xsl], structure, references={"type" : types_xml})
1.288 +
1.289 + # Start the response.
1.290 +</pre>
1.291 +
1.292 <p>These lines do the following things:</p>
1.293 +
1.294 <ol>
1.295 <li>Obtain the stylesheet for the <code>structure</code> initialisation.</li>
1.296 <li>Obtain the <code>types</code> document containing the
1.297 -values to be merged into the form data.</li>
1.298 + values to be merged into the form data.</li>
1.299 <li>Take the stylesheet and apply it to the form data, <code>structure</code>,
1.300 -using a reference to the <code>types</code> document containing
1.301 -the values.</li>
1.302 + using a reference to the <code>types</code> document containing
1.303 + the values.</li>
1.304 </ol>
1.305 +
1.306 <p>The result of this should be a processed <code>structure</code>
1.307 document containing the type values for each <code>type</code>
1.308 element in that document.</p>
1.309 +
1.310 <h2>Other Multiple-Choice Data</h2>
1.311 +
1.312 <p>We have now added a simple, single-valued multiple-choice field to
1.313 the application. However, many applications often need to obtain <a href="multivalue.html">multivalued multiple-choice data</a>, and this
1.314 kind of information is investigated in the next part of the development
1.315 <a href="overview.html">process</a>.</p>
1.316 -</body></html>
1.317 +
1.318 +</body>
1.319 +</html>