1.1 --- a/docs/multiple.html Wed Jul 20 17:02:18 2005 +0000
1.2 +++ b/docs/multiple.html Wed Jul 20 17:59:42 2005 +0000
1.3 @@ -78,9 +78,130 @@
1.4 structure. Therefore, we shall define an output form data structure as
1.5 follows:</p>
1.6 <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.7 -<p>But since we will receive a structure resembling that defined
1.8 -earlier, yet need to present a structure like the one above, we will
1.9 +<h3>Presenting the Extra Values</h3>
1.10 +<p>In the template, the <code>option</code> element is presented
1.11 +using a number of special annotations which make more sense when
1.12 +considering the above output structure:</p>
1.13 +<ul>
1.14 + <li>The <code>template:element</code> annotation states that the
1.15 + <code>option</code> element maps into the <code>type-enum</code>
1.16 +element, meaning that each <code>type-enum</code> element will be
1.17 +reproduced as an option inside the list or menu presented in the Web
1.18 +form.</li>
1.19 + <li>The <code>template:value</code> annotation states that the
1.20 +contents of the <code>option</code> element will correspond to
1.21 +the value of the <code>type-enum</code> element's <code>value</code>
1.22 +attribute - the notation employed here actually belongs to XSL.</li>
1.23 + <li>The <code>template:expr</code> and <code>template:expr-attr</code>
1.24 +annotations work together and state that...<br />
1.25 + <ol>
1.26 + <li>When the expression in <code>template:expr</code> is true...</li>
1.27 + <li>The attribute in <code>template:expr-attr</code> will be
1.28 +added to the <code>option</code> element with a value identical to its
1.29 +name.</li>
1.30 + </ol>
1.31 + </li>
1.32 + <li>The <code>value</code> attribute is defined to reproduce
1.33 +the <code>value</code> attribute from the <code>type-enum</code>
1.34 +element - the notation employed here belongs, once again, to XSL.</li>
1.35 +</ul>
1.36 +<p>The result of this is that the <code>type</code> element in the
1.37 +this example structure fragment...</p>
1.38 +<pre><type value="2"><br /> <type-enum value="1"/><br /> <type-enum value="2"/><br /> <type-enum value="3"/><br /></type></pre>
1.39 +<p>...is transformed into something resembling this HTML code:</p>
1.40 +<pre><select name="..."><br /> <option value="1">1</option><br /> <option value="2" selected="selected">2</option><br /> <option value="3">3</option><br /></select></pre>
1.41 +<p>Such presentation techniques are sufficient if the input form data
1.42 +structure is identical to the output structure, but since we will
1.43 +receive a structure resembling that defined
1.44 +earlier (where the multiple-choice values are never sent back to the
1.45 +application), yet need to present a structure like the one above, we
1.46 +will
1.47 need to find a way of merging the range of allowed values into the
1.48 user-edited form data before presenting that data using our template.</p>
1.49 +<h2>Merging Values into the Form Data</h2>
1.50 +<p>There are many possible ways of inserting extra XML elements into an
1.51 +existing XML document, but we shall concentrate on using an XSL
1.52 +stylesheet to perform this merge operation. First, let us define a
1.53 +document containing all the possible values for the type field:</p>
1.54 +<pre><?xml version="1.0"?><br /><types><br /> <type-enum value="(Not selected)"/><br /> <type-enum value="Important"/><br /> <type-enum value="Not important"/><br /> <type-enum value="Personal"/><br /></types></pre>
1.55 +<p>We shall refer to this document when inserting the different <code>type-enum</code>
1.56 +elements into our input form data structure to produce the output
1.57 +structure described above. The stylesheet which performs this task is
1.58 +quite scary for those not familiar with XSL, but it works on the
1.59 +following principles:</p>
1.60 +<ol>
1.61 + <li>Descend into the form data structure, copying all elements,
1.62 +attributes and text that the stylesheet is not programmed to recognise.</li>
1.63 + <li>When encountering an <code>item</code> element (which the
1.64 +stylesheet is programmed to recognise), do the following:<br />
1.65 + <ol>
1.66 + <li>Copy the element "skeleton" and its attributes so that
1.67 +the <code>value</code> attribute is retained.</li>
1.68 + <li>Look for a <code>type</code> element inside the <code>item</code>
1.69 +element.</li>
1.70 + <li>Where a <code>type</code> element exists, process
1.71 +it; otherwise, make a new <code>type</code> element and process
1.72 +that.</li>
1.73 + </ol>
1.74 + </li>
1.75 + <li>When encountering an existing <code>type</code> element, do
1.76 +the following:<br />
1.77 + <ol>
1.78 + <li>Copy the element "skeleton" and its attributes so that
1.79 +the <code>value</code> attribute is retained.</li>
1.80 + <li>Add the <code>type-enum</code> elements from the
1.81 +document defined above.</li>
1.82 + </ol>
1.83 + </li>
1.84 + <li>When processing a new <code>type</code> element, do the
1.85 +following:<br />
1.86 + <ol>
1.87 + <li>Add the <code>type-enum</code> elements from the
1.88 +document defined above.</li>
1.89 + </ol>
1.90 + </li>
1.91 +</ol>
1.92 +<p>The stylesheet source code can be found in <code>examples/Common/VerySimple/Resources/structure_types.xsl</code>,
1.93 +whereas the document defined above which contains the values can be
1.94 +found in <code>examples/Common/VerySimple/Resources/structure_types.xml</code>.</p>
1.95 +<h3>Performing the Merge</h3>
1.96 +<p>To take advantage of these new documents, it is necessary to
1.97 +introduce some code into the Web resource to perform the merge
1.98 +operation. The special WebStack resource that we <a
1.99 + href="Web-resource.html">subclassed earlier</a> provides some
1.100 +convenient mechanisms for introducing XSL-based transformations, and we
1.101 +shall add a few extra attributes to our resource class in order to take
1.102 +advantage of them:</p>
1.103 +<pre> # Under template_resources...<br /><br /> transform_resources = {<br /> "types" : ["structure_types.xsl"]<br /> }<br /> document_resources = {<br /> "types" : "structure_types.xml"<br /> }</pre>
1.104 +<p>These attributes define the following things:</p>
1.105 +<ol>
1.106 + <li>A transformation called <code>types</code> which uses
1.107 +the <code>structure_types.xsl</code> stylesheet file.</li>
1.108 + <li>A document referred to by the name <code>types</code> which
1.109 +is provided by the <code>structure_types.xml</code> file.</li>
1.110 +</ol>
1.111 +<p>To actually perform the merge operation, we need to add a few extra
1.112 +lines of code after the addition and deletion operations in the <code>respond_to_form</code>
1.113 +method:</p>
1.114 +<pre> # Under the addition and deletion operations...<br /><br /> # Transform, adding enumerations/ranges.<br /><br /> types_xsl_list = self.prepare_transform("types")<br /> types_xml = self.prepare_document("types")<br /> structure = self.get_result(types_xsl_list, structure, references={"types" : types_xml})<br /><br /> # Start the response.</pre>
1.115 +<p>These lines do the following things:</p>
1.116 +<ol>
1.117 + <li>Obtain the stylesheets for the <code>types</code>
1.118 +transformation.</li>
1.119 + <li>Obtain the <code>types</code> document containing the
1.120 +values to be merged into the form data.</li>
1.121 + <li>Take the stylesheets and apply them to the form data, <code>structure</code>,
1.122 +using a reference to the <code>types</code> document containing
1.123 +the values.</li>
1.124 +</ol>
1.125 +<p>The result of this should be a processed <code>structure</code>
1.126 +document containing the type values for each <code>type</code>
1.127 +element in that document.</p>
1.128 +<h2>Other Multiple-Choice Data</h2>
1.129 +<p>We have now added a simple, single-valued multiple-choice field to
1.130 +the application. However, many applications often need to obtain <a
1.131 + href="multivalued.html">multivalued multiple-choice data</a>, and this
1.132 +kind of information is investigated in the next part of the development
1.133 +<a href="overview.html">process</a>.</p>
1.134 </body>
1.135 </html>