1.1 --- a/docs/multiple.html Wed Jul 20 22:46:04 2005 +0000
1.2 +++ b/docs/multiple.html Wed Jul 20 23:41:03 2005 +0000
1.3 @@ -200,7 +200,7 @@
1.4 <h2>Other Multiple-Choice Data</h2>
1.5 <p>We have now added a simple, single-valued multiple-choice field to
1.6 the application. However, many applications often need to obtain <a
1.7 - href="multivalued.html">multivalued multiple-choice data</a>, and this
1.8 + href="multivalue.html">multivalued multiple-choice data</a>, and this
1.9 kind of information is investigated in the next part of the development
1.10 <a href="overview.html">process</a>.</p>
1.11 </body>
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/multivalue.html Wed Jul 20 23:41:03 2005 +0000
2.3 @@ -0,0 +1,162 @@
2.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.5 +<html xmlns="http://www.w3.org/1999/xhtml">
2.6 +<head>
2.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
2.8 + <title>Creating Applications: Adding Multivalued Fields</title>
2.9 + <meta name="generator"
2.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
2.12 +</head>
2.13 +<body>
2.14 +<h1>Creating Applications: Adding Multivalued Fields</h1>
2.15 +<p>Although some applications only require multiple-choice fields where
2.16 +only a single value may be chosen, in many situations it is desirable
2.17 +to be able to choose an arbitrary number of values for a particular
2.18 +field. However, up to this point, we have been content to
2.19 +represent form data using a single attribute on a single element to
2.20 +represent any given field value. With multivalued fields, we must
2.21 +choose a different strategy in using XML to represent such information.</p>
2.22 +<p>Let us consider permitting multiple type values to be associated
2.23 +with our items. We revise our <a href="data.html">form data structure</a>
2.24 +to
2.25 +be the following:</p>
2.26 +<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.27 +<h2>Multivalued Fields</h2>
2.28 +<p>We shall now take advantage of those HTML form fields which permit
2.29 +users to select one
2.30 +or many values presented in a list or menu.</p>
2.31 +<form method="post" action="" name="single">
2.32 + <p>Some item: <input name="value" value="some value" /><input
2.33 + name="remove" value="Remove" type="submit" /></p>
2.34 + <p>Item type:
2.35 + <select multiple="multiple" name="type">
2.36 + <option>(Not selected)</option>
2.37 + <option>Important</option>
2.38 + <option>Not important</option>
2.39 + <option>Personal</option>
2.40 + </select>
2.41 + </p>
2.42 + <p>Itself containing more items:</p>
2.43 + <p>Sub-item: <input name="subvalue" value="some other value" /><input
2.44 + name="remove2" value="Remove" type="submit" /></p>
2.45 +</form>
2.46 +From the item type list many value may now be selected.
2.47 +<p>Taking the example HTML code from before, we can add a
2.48 +definition of this new list to the template to produce something
2.49 +like this:</p>
2.50 +<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.51 + style="font-weight: bold;"><p template:element="types"></span><br /> Item type:<br /> <select template:element="type" name="<span
2.52 + style="font-weight: bold;">{template:list-attribute('value')}</span>" <span
2.53 + style="font-weight: bold;">multiple="multiple"</span>><br /> <option template:element="type-enum" template:expr="<span
2.54 + 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.55 + 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.56 +<p>From the previous <a href="mulitple.html">single-valued case</a>,
2.57 +some crucial changes have been made:</p>
2.58 +<ol>
2.59 + <li>The paragraph surrounding the field has been annotated to map
2.60 +onto the <code>types</code> element in the form data structure.</li>
2.61 + <li>The <code>select</code> element remains mapped onto the <code>type</code>
2.62 +element in the form data structure. However, we indicate in the name of
2.63 +the <code>select</code>
2.64 +element that the value submitted maps onto a special kind of attribute.
2.65 +Instead of mapping onto a single attribute on a single element, the
2.66 +value maps onto a single attribute on a single element <span
2.67 + style="font-style: italic;">for each value submitted</span>. So for
2.68 +each value selected in the list or menu, a <code>type</code>
2.69 +element is created with the <code>value</code>
2.70 +attribute containing that value.</li>
2.71 + <li>Of course, the <code>select</code> element now has a <code>multiple</code>
2.72 +attribute defined to permit multiple value selections.</li>
2.73 + <li>Inside the <code>select</code> element, the <code>option</code>
2.74 +element mapping onto
2.75 +a <code>type-enum</code> element using a different <code>template:expr</code>
2.76 +condition than was used before.</li>
2.77 +</ol>
2.78 +<h2>Output Structures</h2>
2.79 +<p>Just as in the single-valued case, the revised the form data
2.80 +structure for input does not quite match the structure used by the
2.81 +template. Therefore, we shall define an output form data structure as
2.82 +follows:</p>
2.83 +<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.84 +<p>It is worth noting that the above structure does not define whether
2.85 +many <code>type</code> elements will exist within each <code>types</code>
2.86 +element or whether another mechanism will be used to specify multiple
2.87 +values for each type field.<br />
2.88 +</p>
2.89 +<h3>Presenting the Extra Values</h3>
2.90 +<p>In most respects, the presentation of the extra values is the same
2.91 +as in the single-valued case. The result of the presentation of the
2.92 +extra values is that the <code>types</code> element in the
2.93 +this example structure fragment...</p>
2.94 +<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.95 +<p>...is transformed into something resembling this HTML code:</p>
2.96 +<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.97 +<p>Numerous issues arise when considering the above transformation:</p>
2.98 +<ul>
2.99 + <li>Were we not supposed to have many <code>type</code> elements?</li>
2.100 + <li>Where does the special <code>value-is-set</code> attribute
2.101 +come from?</li>
2.102 +</ul>
2.103 +Here, we have made a strategic decision: with the template as defined
2.104 +above, many <code>type</code> elements would have produced
2.105 +many <code>select</code> elements in the Web form, yet this is not
2.106 +what we want; we need to restrict the number of <code>select</code>
2.107 +elements to one per <code>types</code> element whilst marking the
2.108 +selected values so that they may be displayed appropriately in the list
2.109 +or menu.
2.110 +<h2>Merging and Collecting Values</h2>
2.111 +<p>As in the single-valued case, we need to insert the permitted values
2.112 +into the form data so that the template may visit the <code>type-enum</code>
2.113 +elements and extract those values. However, we have now introduced
2.114 +another task to this activity: to collect the selected values together
2.115 +and to produce a unified <code>type</code> element within
2.116 +each <code>types</code> element. In other words, we want to turn
2.117 +something like this...</p>
2.118 +<pre><types><br /> <type value="2"/><br /> <type value="3"/><br /></types></pre>
2.119 +<p>...into something like this:</p>
2.120 +<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.121 +Using the same document containing all the permitted values as our
2.122 +source of information to be merged into the form data, we can now
2.123 +develop a stylesheet which performs the above transformation; this
2.124 +stylesheet needs to work on the
2.125 +following principles:
2.126 +<ol>
2.127 + <li>Descend into the form data structure, copying all elements,
2.128 +attributes and text that the stylesheet is not programmed to recognise.</li>
2.129 + <li>When encountering an <code>item</code> element (which the
2.130 +stylesheet is programmed to recognise), do the following:<br />
2.131 + <ol>
2.132 + <li>Copy the element "skeleton" and its attributes so that
2.133 +the <code>value</code> attribute is retained.</li>
2.134 + <li>Produce a new <code>types</code> element and process it.</li>
2.135 + </ol>
2.136 + </li>
2.137 + <li>When processing a new <code>types</code> element, do the
2.138 +following:<br />
2.139 + <ol>
2.140 + <li>Add a single <code>type</code> element within it.</li>
2.141 + <li>Inside this new <code>type</code> element, add the <code>type-enum</code>
2.142 +elements from the
2.143 +document containing the values, and if any <code>type</code>
2.144 +elements were found within the <code>item</code> element, specify
2.145 +these for the activity.</li>
2.146 + </ol>
2.147 + </li>
2.148 + <li>When adding the <code>type-enum</code> elements, if any of
2.149 +them have a <code>value</code> attribute which matches any of the <code>value</code>
2.150 +attributes of the found <code>type</code> elements, set the special
2.151 + <code>value-is-set</code> attribute on that <code>type-enum</code>
2.152 +element.</li>
2.153 +</ol>
2.154 +<p>The stylesheet source code can be found in <code>examples/Common/VerySimple/Resources/structure_multivalue_types.xsl</code>,
2.155 +whereas the document defined above which contains the values can be
2.156 +found in <code>examples/Common/VerySimple/Resources/structure_types.xml</code>.</p>
2.157 +<h3>Updating the Web Resource</h3>
2.158 +<p>To update the special WebStack resource, we
2.159 +now need to modify a few of the class attributes and to add a few
2.160 +others:</p>
2.161 +<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.162 +<p>With these adjustments, it should now be possible to manipulate the
2.163 +items and subitems whilst specifying multiple type values on each item.</p>
2.164 +</body>
2.165 +</html>
3.1 --- a/docs/overview.html Wed Jul 20 22:46:04 2005 +0000
3.2 +++ b/docs/overview.html Wed Jul 20 23:41:03 2005 +0000
3.3 @@ -20,6 +20,7 @@
3.4 <li><a href="Web-resource.html">Write a Web resource to display the
3.5 form</a></li>
3.6 <li><a href="multiple.html">Adding multiple-choice fields and values</a></li>
3.7 + <li><a href="multivalue.html">Adding multivalued fields</a></li>
3.8 </ol>
3.9 <h2>Recommendations</h2>
3.10 <ol>