1.1 --- a/docs/multivalue.html Mon Oct 03 23:04:48 2005 +0000
1.2 +++ b/docs/multivalue.html Mon Oct 03 23:05:27 2005 +0000
1.3 @@ -1,12 +1,10 @@
1.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 -<html xmlns="http://www.w3.org/1999/xhtml">
1.6 -<head>
1.7 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
1.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.9 - <title>Creating Applications: Adding Multivalued Fields</title>
1.10 - <meta name="generator"
1.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.12 - <link href="styles.css" rel="stylesheet" type="text/css" />
1.13 -</head>
1.14 +
1.15 + <title>Creating Applications: Adding Multivalued Fields</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.16 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.17 +
1.18 <body>
1.19 <h1>Creating Applications: Adding Multivalued Fields</h1>
1.20 <p>Although some applications only require multiple-choice fields where
1.21 @@ -26,49 +24,32 @@
1.22 users to select one
1.23 or many values presented in a list or menu.</p>
1.24 <form method="post" action="" name="single">
1.25 - <p>Some item: <input name="value" value="some value" /><input
1.26 - name="remove" value="Remove" type="submit" /></p>
1.27 + <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
1.28 <p>Item type:
1.29 - <select multiple="multiple" name="type">
1.30 - <option>(Not selected)</option>
1.31 - <option>Important</option>
1.32 - <option>Not important</option>
1.33 - <option>Personal</option>
1.34 - </select>
1.35 + <select multiple="multiple" name="type"><option>(Not selected)</option><option>Important</option><option>Not important</option><option>Personal</option></select>
1.36 </p>
1.37 <p>Itself containing more items:</p>
1.38 - <p>Sub-item: <input name="subvalue" value="some other value" /><input
1.39 - name="remove2" value="Remove" type="submit" /></p>
1.40 + <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p>
1.41 </form>
1.42 From the item type list many value may now be selected.
1.43 <p>Taking the example HTML code from before, we can add a
1.44 definition of this new list to the template to produce something
1.45 like this:</p>
1.46 -<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
1.47 - style="font-weight: bold;"><p></span><br /> Item type:<br /> <select template:element="type" name="<span
1.48 - style="font-weight: bold;">{template:list-attribute('type-enum', 'value')}</span>" <span
1.49 - style="font-weight: bold;">multiple="multiple"</span>><br /> <option template:element="type-enum" template:expr="<span
1.50 - 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
1.51 - 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.52 +<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.53 <p>From the previous <a href="multiple.html">single-valued case</a>,
1.54 some crucial changes have been made:</p>
1.55 <ol>
1.56 <li>The <code>select</code> element remains mapped onto the <code>type</code>
1.57 -element in the form data structure. However, we indicate in the name of
1.58 -the <code>select</code>
1.59 -element that the value submitted maps onto a special kind of attribute.
1.60 -Instead of mapping onto a single attribute on a single element, the
1.61 -value maps onto a single attribute on a single element <span
1.62 - style="font-style: italic;">for each value submitted</span>. So for
1.63 -each value selected in the list or menu, a <code>type-enum</code>
1.64 -element is created (inside the <code>type</code> element) with a <code>value</code>
1.65 -attribute containing that value.</li>
1.66 +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.67 +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.68 +element is created within the <code>type</code>
1.69 +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.70 +elements may be created within the <code>type</code>
1.71 +element, and each one of them will have a different <code>value</code> attribute.</li>
1.72 <li>Of course, the <code>select</code> element now has a <code>multiple</code>
1.73 attribute defined to permit multiple value selections.</li>
1.74 <li>Inside the <code>select</code> element, the <code>option</code>
1.75 -element mapping onto
1.76 -a <code>type-enum</code> element using a different <code>template:expr</code>
1.77 -condition than was used before.</li>
1.78 +element now employs the <code>template:multiple-choice-list-value</code> annotation.</li>
1.79 </ol>
1.80 <h2>Output Structures</h2>
1.81 <p>Unlike in the single-valued case, the revised the form data
1.82 @@ -89,73 +70,17 @@
1.83 <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>
1.84 <p>...is transformed into something resembling this HTML code:</p>
1.85 <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>
1.86 -<p>One principal issue arises when considering the above
1.87 -transformation: where does the special <code>value-is-set</code>
1.88 -attribute
1.89 -come from?</p>
1.90 +<p>Above, the special <code>value-is-set</code>
1.91 +attribute is an XSLForms mechanism to remember which values were set.
1.92 +Fortunately, the document initialisation mechanism automatically
1.93 +distinguishes between different multiple-choice field types and
1.94 +understands where the above approach needs to be employed.</p>
1.95 <ul>
1.96 -</ul>
1.97 -Here, we have to do two things: to include the full range of possible
1.98 -values so that the user may select from that range, and yet we must
1.99 -remember which values were previously selected. If we just merged
1.100 -the <code>type-enum</code> elements into the <code>type</code>
1.101 -element, we would lose track of which values were selected. Therefore,
1.102 -we need to employ a different strategy in remembering those values than
1.103 -that of assuming that those <code>type-enum</code> elements which
1.104 -are present are those which are selected.
1.105 -<h2>Merging and Collecting Values</h2>
1.106 -<p>As in the single-valued case, we need to insert the permitted values
1.107 -into the form data so that the template may visit the <code>type-enum</code>
1.108 -elements and extract those values. However, we have now introduced
1.109 -another task to this activity: to mark the selected values in the
1.110 -entire list of <code>type-enum</code> elements in order to
1.111 -distinguish them from the values which are not selected. In other
1.112 -words, we want to turn
1.113 -something like this...</p>
1.114 -<pre><type><br /> <type-enum value="2"/><br /> <type-enum value="3"/><br /></type><br /></pre>
1.115 -<p>...into something like this:</p>
1.116 -<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>
1.117 -Using the same document containing all the permitted values as our
1.118 -source of information to be merged into the form data, we can now
1.119 -develop a stylesheet which performs the above transformation; this
1.120 -stylesheet needs to work on the
1.121 -following principles:
1.122 -<ol>
1.123 - <li>Descend into the form data structure, copying all elements,
1.124 -attributes and text that the stylesheet is not programmed to recognise.</li>
1.125 - <li>When encountering an <code>item</code> element (which the
1.126 -stylesheet is programmed to recognise), do the following:<br />
1.127 - <ol>
1.128 - <li>Copy the element "skeleton" and its attributes so that
1.129 -the <code>value</code> attribute is retained.</li>
1.130 - <li>Produce a new <code>type</code> element and process it.</li>
1.131 - </ol>
1.132 - </li>
1.133 - <li>When processing a new <code>type</code> element, do the
1.134 -following:<br />
1.135 - <ol>
1.136 - <li>Inside this new <code>type</code> element, add the <code>type-enum</code>
1.137 -elements from the
1.138 -values document, and if any <code>type-enum</code>
1.139 -elements were found within an existing <code>type</code> element from
1.140 -the form data, specify
1.141 -these for the activity.</li>
1.142 - </ol>
1.143 - </li>
1.144 - <li>When adding the <code>type-enum</code> elements, if any of
1.145 -them have a <code>value</code> attribute which matches any of the <code>value</code>
1.146 -attributes of the found <code>type-enum</code> elements, set the
1.147 -special <code>value-is-set</code> attribute on that <code>type-enum</code>
1.148 -element.</li>
1.149 -</ol>
1.150 -<p>The stylesheet source code can be found in <code>examples/Common/VerySimple/Resources/structure_multivalue_types.xsl</code>,
1.151 -whereas the document defined above which contains the values can be
1.152 -found in <code>examples/Common/VerySimple/Resources/structure_types.xml</code>.</p>
1.153 -<h3>Updating the Web Resource</h3>
1.154 +</ul><h3>Updating the Web Resource</h3>
1.155 <p>To update the special WebStack resource, we
1.156 now need to modify a few of the class attributes and to add a few
1.157 others:</p>
1.158 -<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>
1.159 +<pre> template_resources = {<br /> "structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl")<br /> }<br /></pre>
1.160 <p>With these adjustments, it should now be possible to manipulate the
1.161 items and subitems whilst specifying multiple type values on each item.
1.162 Note that it may be necessary to remove the old stylesheet for
1.163 @@ -165,5 +90,4 @@
1.164 <p>Now that we have designed and implemented a simple application, it
1.165 may be worth reading some <a href="advice.html">recommendations</a>
1.166 about developing your own applications.</p>
1.167 -</body>
1.168 -</html>
1.169 +</body></html>
1.170 \ No newline at end of file
