1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/multiple.html Tue Jul 19 22:40:50 2005 +0000
1.3 @@ -0,0 +1,86 @@
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 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.8 + <title>Creating Applications: Adding Multiple-Choice Fields and Values</title>
1.9 + <meta name="generator"
1.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.12 +</head>
1.13 +<body>
1.14 +<h1>Creating Applications: Adding Multiple-Choice Fields and Values</h1>
1.15 +<p>Up to this point, we have only considered two kinds of Web form
1.16 +fields: text entry fields and action buttons. Since most Web forms
1.17 +offer more convenient ways of entering certain kinds of data, we shall
1.18 +now investigate multiple-choice fields as an example of how XSLForms
1.19 +handles more complicated types of fields.</p>
1.20 +<p>We shall revise our <a href="data.html">form data structure</a> to
1.21 +be the following:</p>
1.22 +<pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <type value="some type"/><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre>
1.23 +<h2>Single-Valued Fields</h2>
1.24 +<p>Whilst HTML offers types of form fields where users can select one
1.25 +or many values presented in a list or menu, we shall first consider the
1.26 +case where only a single value can be chosen from such a selection.</p>
1.27 +<form Method="POST" Action="none" Name="single">
1.28 + <p>Some item: <input name="value" value="some value" /><input
1.29 + name="remove" value="Remove" type="submit" /></p>
1.30 + <p>Item type:
1.31 + <select name="type">
1.32 + <option>(Not selected)</option>
1.33 + <option>Important</option>
1.34 + <option>Not important</option>
1.35 + <option>Personal</option>
1.36 + </select>
1.37 + </p>
1.38 + <p>Itself containing more items:</p>
1.39 + <p>Sub-item: <input name="subvalue" value="some other value" /><input
1.40 + name="remove2" value="Remove" type="submit" /></p>
1.41 +</form>
1.42 +From the item type list only one value may 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:field-name()}" type="text" value="{$this-value}" /><br /> <input name="remove={template:this-position()}" type="submit" value="Remove" /><br /> </p><br /> <span
1.47 + style="font-weight: bold;"><p></span><br
1.48 + style="font-weight: bold;" /><span style="font-weight: bold;"> Item type:</span><br
1.49 + style="font-weight: bold;" /><span style="font-weight: bold;"> <select template:element="type" name="{template:new-field('value')}"></span><br
1.50 + style="font-weight: bold;" /><span style="font-weight: bold;"> <option template:element="type-enum" template:expr="@value-is-set" template:expr-attr="selected"</span><br
1.51 + style="font-weight: bold;" /><span style="font-weight: bold;"> template:value="@value" value="{@value}"></option></span><br
1.52 + style="font-weight: bold;" /><span style="font-weight: bold;"> </select></span><br
1.53 + 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:field-name()}" type="text" value="{$this-value}" /><br /> <input name="remove2={template:this-position()}" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="add2={template:this-position()}" type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="add={template:this-position()}" type="submit" value="Add item" /><br /></p><span
1.54 + 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 + <li>A paragraph was added to provide some space on the page for the
1.59 +field.</li>
1.60 + <li>Inside the paragraph, next to the label text, an HTML <code>select</code>
1.61 +element was added.</li>
1.62 + <li>The <code>select</code> element is mapped onto the <code>type</code>
1.63 +element in the form data structure. However, HTML fields must produce
1.64 +values and it makes no sense to interpret a textual value as an
1.65 +element. Therefore, we indicate in the name of the <code>select</code>
1.66 +element that the value submitted maps onto the <code>value</code>
1.67 +attribute of the <code>type</code> element in the form data
1.68 +structure.</li>
1.69 + <li>Inside the <code>select</code> element, we include an <code>option</code>
1.70 +element which defines the values which will be presented to users
1.71 +of the form. Note that the <code>option</code> element maps onto
1.72 +a <code>type-enum</code> element which is not mentioned in our
1.73 +revised form data structure above; this will be discussed below.</li>
1.74 +</ol>
1.75 +<h2>Output Structures</h2>
1.76 +<p>Although we revised the form data structure above, and whilst the
1.77 +revised structure can describe form data submitted by users of our
1.78 +application, it is unfortunately not sufficient to define the form data
1.79 +that is to be presented. Consider the multiple-choice values that shall
1.80 +be presented to users: such values are not defined in our revised
1.81 +structure. Therefore, we shall define an output form data structure as
1.82 +follows:</p>
1.83 +<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.84 +<p>But since we will receive a structure resembling that defined
1.85 +earlier, yet need to present a structure like the one above, we will
1.86 +need to find a way of merging the range of allowed values into the
1.87 +user-edited form data before presenting that data using our template.</p>
1.88 +</body>
1.89 +</html>