1.1 --- a/docs/multiple.html Mon Oct 03 23:04:48 2005 +0000
1.2 +++ b/docs/multiple.html Mon Oct 03 23:05:27 2005 +0000
1.3 @@ -1,12 +1,9 @@
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 Multiple-Choice Fields and Values</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 Multiple-Choice Fields and Values</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 <body>
1.18 <h1>Creating Applications: Adding Multiple-Choice Fields and Values</h1>
1.19 <p>Up to this point, we have only considered two kinds of Web form
1.20 @@ -22,33 +19,18 @@
1.21 or many values presented in a list or menu, we shall first consider the
1.22 case where only a single value can be chosen from such a selection.</p>
1.23 <form method="post" action="" name="single">
1.24 - <p>Some item: <input name="value" value="some value" /><input
1.25 - name="remove" value="Remove" type="submit" /></p>
1.26 + <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
1.27 <p>Item type:
1.28 - <select name="type">
1.29 - <option>(Not selected)</option>
1.30 - <option>Important</option>
1.31 - <option>Not important</option>
1.32 - <option>Personal</option>
1.33 - </select>
1.34 + <select name="type"><option>(Not selected)</option><option>Important</option><option>Not important</option><option>Personal</option></select>
1.35 </p>
1.36 <p>Itself containing more items:</p>
1.37 - <p>Sub-item: <input name="subvalue" value="some other value" /><input
1.38 - name="remove2" value="Remove" type="submit" /></p>
1.39 + <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p>
1.40 </form>
1.41 From the item type list only one value may be selected.
1.42 <p>Taking the example HTML code from before, we can add a
1.43 definition of this new list to the template to produce something
1.44 like this:</p>
1.45 -<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.46 - style="font-weight: bold;"><p></span><br
1.47 - style="font-weight: bold;" /><span style="font-weight: bold;"> Item type:</span><br
1.48 - style="font-weight: bold;" /><span style="font-weight: bold;"> <select template:element="type" name="{template:new-attribute('value')}"></span><br
1.49 - style="font-weight: bold;" /><span style="font-weight: bold;"> <option template:element="type-enum" template:expr="@value = ../@value" template:expr-attr="selected"</span><br
1.50 - style="font-weight: bold;" /><span style="font-weight: bold;"> template:value="@value" value="{@value}" /></span><br
1.51 - style="font-weight: bold;" /><span style="font-weight: bold;"> </select></span><br
1.52 - 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="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.53 - 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 +<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.55 <p>There are a lot of details here that need to be explained. Here is
1.56 what was done:</p>
1.57 <ol>
1.58 @@ -57,15 +39,11 @@
1.59 <li>Inside the paragraph, next to the label text, an HTML <code>select</code>
1.60 element was added.</li>
1.61 <li>The <code>select</code> element is mapped onto the <code>type</code>
1.62 -element in the form data structure. However, HTML fields must produce
1.63 -values and it makes no sense to interpret a textual value as an
1.64 -element. Therefore, we indicate in the name of the <code>select</code>
1.65 -element that the value submitted maps onto the <code>value</code>
1.66 -attribute of the <code>type</code> element in the form data
1.67 -structure.</li>
1.68 +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.69 +element will contain any chosen value from the list of values displayed in the page.</li>
1.70 <li>Inside the <code>select</code> element, we include an <code>option</code>
1.71 element which defines the values which will be presented to users
1.72 -of the form. Note that the <code>option</code> element maps onto
1.73 +of the form. Here, the special <code>template:multiple-choice-value</code> attribute indicates that the <code>option</code> element maps onto
1.74 a <code>type-enum</code> element which is not mentioned in our
1.75 revised form data structure above; this will be discussed below.</li>
1.76 </ol>
1.77 @@ -83,28 +61,17 @@
1.78 using a number of special annotations which make more sense when
1.79 considering the above output structure:</p>
1.80 <ul>
1.81 - <li>The <code>template:element</code> annotation states that the
1.82 + <li>The <code>template:multiple-choice-value</code> annotation states that the
1.83 <code>option</code> element maps into the <code>type-enum</code>
1.84 element, meaning that each <code>type-enum</code> element will be
1.85 reproduced as an option inside the list or menu presented in the Web
1.86 form.</li>
1.87 - <li>The <code>template:value</code> annotation states that the
1.88 + <li>The <code>template:multiple-choice-value</code> annotation also states that the
1.89 contents of the <code>option</code> element will correspond to
1.90 the value of the <code>type-enum</code> element's <code>value</code>
1.91 -attribute - the notation employed here actually belongs to XSL.</li>
1.92 - <li>The <code>template:expr</code> and <code>template:expr-attr</code>
1.93 -annotations work together and state that...<br />
1.94 - <ol>
1.95 - <li>When the expression in <code>template:expr</code> is true...</li>
1.96 - <li>The attribute in <code>template:expr-attr</code> will be
1.97 -added to the <code>option</code> element with a value identical to its
1.98 -name.</li>
1.99 - </ol>
1.100 - </li>
1.101 - <li>The <code>value</code> attribute is defined to reproduce
1.102 -the <code>value</code> attribute from the <code>type-enum</code>
1.103 -element - the notation employed here belongs, once again, to XSL.</li>
1.104 -</ul>
1.105 +attribute.</li>
1.106 + <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.107 + </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.108 <p>The result of this is that the <code>type</code> element in the
1.109 this example structure fragment...</p>
1.110 <pre><type value="2"><br /> <type-enum value="1"/><br /> <type-enum value="2"/><br /> <type-enum value="3"/><br /></type></pre>
1.111 @@ -118,70 +85,41 @@
1.112 will
1.113 need to find a way of merging the range of allowed values into the
1.114 user-edited form data before presenting that data using our template.</p>
1.115 -<h2>Merging Values into the Form Data</h2>
1.116 +<h2>Document Initialisation</h2>
1.117 <p>There are many possible ways of inserting extra XML elements into an
1.118 -existing XML document, but we shall concentrate on using an XSL
1.119 -stylesheet to perform this merge operation. First, let us define a
1.120 +existing XML document, but XSLForms provides an easy way of defining
1.121 +lists of values that will be included in the way we desire. First, let
1.122 +us define a
1.123 document containing all the possible values for the type field:</p>
1.124 -<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.125 +<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.126 <p>We shall refer to this document when inserting the different <code>type-enum</code>
1.127 elements into our input form data structure to produce the output
1.128 -structure described above. The stylesheet which performs this task is
1.129 -quite scary for those not familiar with XSL, but it works on the
1.130 -following principles:</p>
1.131 -<ol>
1.132 - <li>Descend into the form data structure, copying all elements,
1.133 -attributes and text that the stylesheet is not programmed to recognise.</li>
1.134 - <li>When encountering an <code>item</code> element (which the
1.135 -stylesheet is programmed to recognise), do the following:<br />
1.136 - <ol>
1.137 - <li>Copy the element "skeleton" and its attributes so that
1.138 -the <code>value</code> attribute is retained.</li>
1.139 - <li>Make a <code>type</code> element inside the <code>item</code>
1.140 -element and process it.</li>
1.141 - </ol>
1.142 - </li>
1.143 - <li>When processing a new <code>type</code> element, do the
1.144 -following:<br />
1.145 - <ol>
1.146 - <li>Copy the attributes of any existing <code>type</code>
1.147 -element so that
1.148 -the <code>value</code> attribute is retained.</li>
1.149 - <li>Add the <code>type-enum</code> elements from the
1.150 -document defined above.</li>
1.151 - </ol>
1.152 - </li>
1.153 -</ol>
1.154 -<p>The stylesheet source code can be found in <code>examples/Common/VerySimple/Resources/structure_types.xsl</code>,
1.155 -whereas the document defined above which contains the values can be
1.156 +structure described above; it can be
1.157 found in <code>examples/Common/VerySimple/Resources/structure_types.xml</code>.</p>
1.158 -<h3>Performing the Merge</h3>
1.159 -<p>To take advantage of these new documents, it is necessary to
1.160 -introduce some code into the Web resource to perform the merge
1.161 -operation. The special WebStack resource that we <a
1.162 - href="Web-resource.html">subclassed earlier</a> provides some
1.163 -convenient mechanisms for introducing XSL-based transformations, and we
1.164 +<h3>Amending the Resource</h3>
1.165 +<p>To take advantage of this new information, it is necessary to
1.166 +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.167 +convenient mechanisms for introducing XML documents and initialisations, and we
1.168 shall add a few extra attributes to our resource class in order to take
1.169 advantage of them:</p>
1.170 -<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.171 +<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.172 <p>These attributes define the following things:</p>
1.173 <ol>
1.174 - <li>A transformation called <code>types</code> which uses
1.175 -the <code>structure_types.xsl</code> stylesheet file.</li>
1.176 + <li>A initialisation called <code>structure</code> which links
1.177 +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.178 <li>A document referred to by the name <code>types</code> which
1.179 is provided by the <code>structure_types.xml</code> file.</li>
1.180 </ol>
1.181 -<p>To actually perform the merge operation, we need to add a few extra
1.182 +<p>To actually perform the initalisation or merge operation, we need to add a few extra
1.183 lines of code after the addition and deletion operations in the <code>respond_to_form</code>
1.184 method:</p>
1.185 -<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.186 +<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.187 <p>These lines do the following things:</p>
1.188 <ol>
1.189 - <li>Obtain the stylesheets for the <code>types</code>
1.190 -transformation.</li>
1.191 + <li>Obtain the stylesheet for the <code>structure</code> initialisation.</li>
1.192 <li>Obtain the <code>types</code> document containing the
1.193 values to be merged into the form data.</li>
1.194 - <li>Take the stylesheets and apply them to the form data, <code>structure</code>,
1.195 + <li>Take the stylesheet and apply it to the form data, <code>structure</code>,
1.196 using a reference to the <code>types</code> document containing
1.197 the values.</li>
1.198 </ol>
1.199 @@ -190,9 +128,7 @@
1.200 element in that document.</p>
1.201 <h2>Other Multiple-Choice Data</h2>
1.202 <p>We have now added a simple, single-valued multiple-choice field to
1.203 -the application. However, many applications often need to obtain <a
1.204 - href="multivalue.html">multivalued multiple-choice data</a>, and this
1.205 +the application. However, many applications often need to obtain <a href="multivalue.html">multivalued multiple-choice data</a>, and this
1.206 kind of information is investigated in the next part of the development
1.207 <a href="overview.html">process</a>.</p>
1.208 -</body>
1.209 -</html>
1.210 +</body></html>
1.211 \ No newline at end of file