1.1 --- a/docs/multiple.html Thu Jul 21 16:13:09 2005 +0000
1.2 +++ b/docs/multiple.html Thu Jul 21 16:14:08 2005 +0000
1.3 @@ -137,25 +137,16 @@
1.4 <ol>
1.5 <li>Copy the element "skeleton" and its attributes so that
1.6 the <code>value</code> attribute is retained.</li>
1.7 - <li>Look for a <code>type</code> element inside the <code>item</code>
1.8 -element.</li>
1.9 - <li>Where a <code>type</code> element exists, process
1.10 -it; otherwise, make a new <code>type</code> element and process
1.11 -that.</li>
1.12 - </ol>
1.13 - </li>
1.14 - <li>When encountering an existing <code>type</code> element, do
1.15 -the following:<br />
1.16 - <ol>
1.17 - <li>Copy the element "skeleton" and its attributes so that
1.18 -the <code>value</code> attribute is retained.</li>
1.19 - <li>Add the <code>type-enum</code> elements from the
1.20 -document defined above.</li>
1.21 + <li>Make a <code>type</code> element inside the <code>item</code>
1.22 +element and process it.</li>
1.23 </ol>
1.24 </li>
1.25 <li>When processing a new <code>type</code> element, do the
1.26 following:<br />
1.27 <ol>
1.28 + <li>Copy the attributes of any existing <code>type</code>
1.29 +element so that
1.30 +the <code>value</code> attribute is retained.</li>
1.31 <li>Add the <code>type-enum</code> elements from the
1.32 document defined above.</li>
1.33 </ol>
2.1 --- a/docs/multivalue.html Thu Jul 21 16:13:09 2005 +0000
2.2 +++ b/docs/multivalue.html Thu Jul 21 16:14:08 2005 +0000
2.3 @@ -20,7 +20,7 @@
2.4 with our items. We revise our <a href="data.html">form data structure</a>
2.5 to
2.6 be the following:</p>
2.7 -<pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <types><br /> <type value="some type"/><br /> <type value="some other type"/><br /> </types><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre>
2.8 +<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>
2.9 <h2>Multivalued Fields</h2>
2.10 <p>We shall now take advantage of those HTML form fields which permit
2.11 users to select one
2.12 @@ -45,16 +45,14 @@
2.13 definition of this new list to the template to produce something
2.14 like this:</p>
2.15 <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="value" name="{template:this-attribute()}" type="text" value="{$this-value}" /><br /> <input name="remove={template:this-element()}" type="submit" value="Remove" /><br /> </p><br /> <span
2.16 - style="font-weight: bold;"><p template:element="types"></span><br /> Item type:<br /> <select template:element="type" name="<span
2.17 - style="font-weight: bold;">{template:list-attribute('value')}</span>" <span
2.18 + style="font-weight: bold;"><p></span><br /> Item type:<br /> <select template:element="type" name="<span
2.19 + style="font-weight: bold;">{template:list-attribute('type-enum', 'value')}</span>" <span
2.20 style="font-weight: bold;">multiple="multiple"</span>><br /> <option template:element="type-enum" template:expr="<span
2.21 style="font-weight: bold;">@value-is-set</span>" template:expr-attr="selected"<br /> template:value="@value" value="{@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="subvalue" name="{template:this-attribute()}" type="text" value="{$this-value}" /><br /> <input name="remove2={template:this-element()}" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="add2={template:this-element()}" type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="add={template:this-element()}" type="submit" value="Add item" /><br /></p><span
2.22 style="font-weight: bold;"><br /><br /></span><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
2.23 <p>From the previous <a href="mulitple.html">single-valued case</a>,
2.24 some crucial changes have been made:</p>
2.25 <ol>
2.26 - <li>The paragraph surrounding the field has been annotated to map
2.27 -onto the <code>types</code> element in the form data structure.</li>
2.28 <li>The <code>select</code> element remains mapped onto the <code>type</code>
2.29 element in the form data structure. However, we indicate in the name of
2.30 the <code>select</code>
2.31 @@ -62,8 +60,8 @@
2.32 Instead of mapping onto a single attribute on a single element, the
2.33 value maps onto a single attribute on a single element <span
2.34 style="font-style: italic;">for each value submitted</span>. So for
2.35 -each value selected in the list or menu, a <code>type</code>
2.36 -element is created with the <code>value</code>
2.37 +each value selected in the list or menu, a <code>type-enum</code>
2.38 +element is created (inside the <code>type</code> element) with a <code>value</code>
2.39 attribute containing that value.</li>
2.40 <li>Of course, the <code>select</code> element now has a <code>multiple</code>
2.41 attribute defined to permit multiple value selections.</li>
2.42 @@ -73,48 +71,50 @@
2.43 condition than was used before.</li>
2.44 </ol>
2.45 <h2>Output Structures</h2>
2.46 -<p>Just as in the single-valued case, the revised the form data
2.47 -structure for input does not quite match the structure used by the
2.48 -template. Therefore, we shall define an output form data structure as
2.49 -follows:</p>
2.50 -<pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <types><br /> <type><br /> <type-enum value="some type"/><br /> <type-enum value="some other type"/><br /> </type><br /> </types><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre>
2.51 -<p>It is worth noting that the above structure does not define whether
2.52 -many <code>type</code> elements will exist within each <code>types</code>
2.53 -element or whether another mechanism will be used to specify multiple
2.54 -values for each type field.<br />
2.55 +<p>Unlike in the single-valued case, the revised the form data
2.56 +structure for input is almost the same as the structure used by the
2.57 +template. Indeed, the subtle differences cannot be represented in our
2.58 +simplistic presentation of the structure:</p>
2.59 +<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>
2.60 +<p>In fact, the principal difference arises through the number of <code>type-enum</code>
2.61 +elements that occur in the input, representing the values selected by
2.62 +the user, and the number that occur in the output, representing the
2.63 +complete range of values available for selection.
2.64 </p>
2.65 <h3>Presenting the Extra Values</h3>
2.66 <p>In most respects, the presentation of the extra values is the same
2.67 as in the single-valued case. The result of the presentation of the
2.68 -extra values is that the <code>types</code> element in the
2.69 +extra values is that the <code>type</code> element in the
2.70 this example structure fragment...</p>
2.71 -<pre><types><br /> <type><br /> <type-enum value="1"/><br /> <type-enum value="2" value-is-set="true"/><br /> <type-enum value="3" value-is-set="true"/><br /> </type><br /></types></pre>
2.72 +<pre><type><br /> <type-enum value="1"/><br /> <type-enum value="2" value-is-set="true"/><br /> <type-enum value="3" value-is-set="true"/><br /></type><br /></pre>
2.73 <p>...is transformed into something resembling this HTML code:</p>
2.74 -<pre><p><br /> <select name="..." multiple="multiple"><br /> <option value="1">1</option><br /> <option value="2" selected="selected">2</option><br /> <option value="3" selected="selected">3</option><br /> </select><br /></p></pre>
2.75 -<p>Numerous issues arise when considering the above transformation:</p>
2.76 +<pre><select name="..." multiple="multiple"><br /> <option value="1">1</option><br /> <option value="2" selected="selected">2</option><br /> <option value="3" selected="selected">3</option><br /></select><br /></pre>
2.77 +<p>One principal issue arises when considering the above
2.78 +transformation: where does the special <code>value-is-set</code>
2.79 +attribute
2.80 +come from?</p>
2.81 <ul>
2.82 - <li>Were we not supposed to have many <code>type</code> elements?</li>
2.83 - <li>Where does the special <code>value-is-set</code> attribute
2.84 -come from?</li>
2.85 </ul>
2.86 -Here, we have made a strategic decision: with the template as defined
2.87 -above, many <code>type</code> elements would have produced
2.88 -many <code>select</code> elements in the Web form, yet this is not
2.89 -what we want; we need to restrict the number of <code>select</code>
2.90 -elements to one per <code>types</code> element whilst marking the
2.91 -selected values so that they may be displayed appropriately in the list
2.92 -or menu.
2.93 +Here, we have to do two things: to include the full range of possible
2.94 +values so that the user may select from that range, and yet we must
2.95 +remember which values were previously selected. If we just merged
2.96 +the <code>type-enum</code> elements into the <code>type</code>
2.97 +element, we would lose track of which values were selected. Therefore,
2.98 +we need to employ a different strategy in remembering those values than
2.99 +that of assuming that those <code>type-enum</code> elements which
2.100 +are present are those which are selected.
2.101 <h2>Merging and Collecting Values</h2>
2.102 <p>As in the single-valued case, we need to insert the permitted values
2.103 into the form data so that the template may visit the <code>type-enum</code>
2.104 elements and extract those values. However, we have now introduced
2.105 -another task to this activity: to collect the selected values together
2.106 -and to produce a unified <code>type</code> element within
2.107 -each <code>types</code> element. In other words, we want to turn
2.108 +another task to this activity: to mark the selected values in the
2.109 +entire list of <code>type-enum</code> elements in order to
2.110 +distinguish them from the values which are not selected. In other
2.111 +words, we want to turn
2.112 something like this...</p>
2.113 -<pre><types><br /> <type value="2"/><br /> <type value="3"/><br /></types></pre>
2.114 +<pre><type><br /> <type-enum value="2"/><br /> <type-enum value="3"/><br /></type><br /></pre>
2.115 <p>...into something like this:</p>
2.116 -<pre><types><br /> <type><br /> <type-enum value="1"/><br /> <type-enum value="2" value-is-set="true"/><br /> <type-enum value="3" value-is-set="true"/><br /> </type><br /></types></pre>
2.117 +<pre><type><br /> <type-enum value="1"/><br /> <type-enum value="2" value-is-set="true"/><br /> <type-enum value="3" value-is-set="true"/><br /></type><br /></pre>
2.118 Using the same document containing all the permitted values as our
2.119 source of information to be merged into the form data, we can now
2.120 develop a stylesheet which performs the above transformation; this
2.121 @@ -128,24 +128,24 @@
2.122 <ol>
2.123 <li>Copy the element "skeleton" and its attributes so that
2.124 the <code>value</code> attribute is retained.</li>
2.125 - <li>Produce a new <code>types</code> element and process it.</li>
2.126 + <li>Produce a new <code>type</code> element and process it.</li>
2.127 </ol>
2.128 </li>
2.129 - <li>When processing a new <code>types</code> element, do the
2.130 + <li>When processing a new <code>type</code> element, do the
2.131 following:<br />
2.132 <ol>
2.133 - <li>Add a single <code>type</code> element within it.</li>
2.134 <li>Inside this new <code>type</code> element, add the <code>type-enum</code>
2.135 elements from the
2.136 -document containing the values, and if any <code>type</code>
2.137 -elements were found within the <code>item</code> element, specify
2.138 +values document, and if any <code>type-enum</code>
2.139 +elements were found within an existing <code>type</code> element from
2.140 +the form data, specify
2.141 these for the activity.</li>
2.142 </ol>
2.143 </li>
2.144 <li>When adding the <code>type-enum</code> elements, if any of
2.145 them have a <code>value</code> attribute which matches any of the <code>value</code>
2.146 -attributes of the found <code>type</code> elements, set the special
2.147 - <code>value-is-set</code> attribute on that <code>type-enum</code>
2.148 +attributes of the found <code>type-enum</code> elements, set the
2.149 +special <code>value-is-set</code> attribute on that <code>type-enum</code>
2.150 element.</li>
2.151 </ol>
2.152 <p>The stylesheet source code can be found in <code>examples/Common/VerySimple/Resources/structure_multivalue_types.xsl</code>,
2.153 @@ -157,6 +157,9 @@
2.154 others:</p>
2.155 <pre> template_resources = {<br /> "structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl")<br /> }<br /> transform_resources = {<br /> "types" : ["structure_multivalue_types.xsl"]<br /> }<br /></pre>
2.156 <p>With these adjustments, it should now be possible to manipulate the
2.157 -items and subitems whilst specifying multiple type values on each item.</p>
2.158 +items and subitems whilst specifying multiple type values on each item.
2.159 +Note that it may be necessary to remove the old stylesheet for
2.160 +producing output, <code>structure_output.xsl</code>, so that the
2.161 +multivalue version of the template is taken into use.</p>
2.162 </body>
2.163 </html>