1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2 <html xmlns="http://www.w3.org/1999/xhtml"><head> 3 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 4 5 <title>Creating Applications: Adding Multiple-Choice Fields and Values</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 6 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 7 <body> 8 <h1>Creating Applications: Adding Multiple-Choice Fields and Values</h1> 9 <p>Up to this point, we have only considered two kinds of Web form 10 fields: text entry fields and action buttons. Since most Web forms 11 offer more convenient ways of entering certain kinds of data, we shall 12 now investigate multiple-choice fields as an example of how XSLForms 13 handles more complicated types of fields.</p> 14 <p>We shall revise our <a href="data.html">form data structure</a> to 15 be the following:</p> 16 <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> 17 <h2>Single-Valued Fields</h2> 18 <p>Whilst HTML offers types of form fields where users can select one 19 or many values presented in a list or menu, we shall first consider the 20 case where only a single value can be chosen from such a selection.</p> 21 <form method="post" action="" name="single"> 22 <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p> 23 <p>Item type: 24 <select name="type"><option>(Not selected)</option><option>Important</option><option>Not important</option><option>Personal</option></select> 25 </p> 26 <p>Itself containing more items:</p> 27 <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p> 28 </form> 29 From the item type list only one value may be selected. 30 <p>Taking the example HTML code from before, we can add a 31 definition of this new list to the template to produce something 32 like this:</p> 33 <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> 34 <p>There are a lot of details here that need to be explained. Here is 35 what was done:</p> 36 <ol> 37 <li>A paragraph was added to provide some space on the page for the 38 field.</li> 39 <li>Inside the paragraph, next to the label text, an HTML <code>select</code> 40 element was added.</li> 41 <li>The <code>select</code> element is mapped onto the <code>type</code> 42 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> 43 element will contain any chosen value from the list of values displayed in the page.</li> 44 <li>Inside the <code>select</code> element, we include an <code>option</code> 45 element which defines the values which will be presented to users 46 of the form. Here, the special <code>template:multiple-choice-value</code> attribute indicates that the <code>option</code> element maps onto 47 a <code>type-enum</code> element which is not mentioned in our 48 revised form data structure above; this will be discussed below.</li> 49 </ol> 50 <h2>Output Structures</h2> 51 <p>Although we revised the form data structure above, and whilst the 52 revised structure can describe form data submitted by users of our 53 application, it is unfortunately not sufficient to define the form data 54 that is to be presented. Consider the multiple-choice values that shall 55 be presented to users: such values are not defined in our revised 56 structure. Therefore, we shall define an output form data structure as 57 follows:</p> 58 <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> 59 <h3>Presenting the Extra Values</h3> 60 <p>In the template, the <code>option</code> element is presented 61 using a number of special annotations which make more sense when 62 considering the above output structure:</p> 63 <ul> 64 <li>The <code>template:multiple-choice-value</code> annotation states that the 65 <code>option</code> element maps into the <code>type-enum</code> 66 element, meaning that each <code>type-enum</code> element will be 67 reproduced as an option inside the list or menu presented in the Web 68 form.</li> 69 <li>The <code>template:multiple-choice-value</code> annotation also states that the 70 contents of the <code>option</code> element will correspond to 71 the value of the <code>type-enum</code> element's <code>value</code> 72 attribute.</li> 73 <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. 74 </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> 75 <p>The result of this is that the <code>type</code> element in the 76 this example structure fragment...</p> 77 <pre><type value="2"><br /> <type-enum value="1"/><br /> <type-enum value="2"/><br /> <type-enum value="3"/><br /></type></pre> 78 <p>...is transformed into something resembling this HTML code:</p> 79 <pre><select name="..."><br /> <option value="1">1</option><br /> <option value="2" selected="selected">2</option><br /> <option value="3">3</option><br /></select></pre> 80 <p>Such presentation techniques are sufficient if the input form data 81 structure is identical to the output structure, but since we will 82 receive a structure resembling that defined 83 earlier (where the multiple-choice values are never sent back to the 84 application), yet need to present a structure like the one above, we 85 will 86 need to find a way of merging the range of allowed values into the 87 user-edited form data before presenting that data using our template.</p> 88 <h2>Document Initialisation</h2> 89 <p>There are many possible ways of inserting extra XML elements into an 90 existing XML document, but XSLForms provides an easy way of defining 91 lists of values that will be included in the way we desire. First, let 92 us define a 93 document containing all the possible values for the type field:</p> 94 <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> 95 <p>We shall refer to this document when inserting the different <code>type-enum</code> 96 elements into our input form data structure to produce the output 97 structure described above; it can be 98 found in <code>examples/Common/VerySimple/Resources/structure_types.xml</code>.</p> 99 <h3>Amending the Resource</h3> 100 <p>To take advantage of this new information, it is necessary to 101 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 102 convenient mechanisms for introducing XML documents and initialisations, and we 103 shall add a few extra attributes to our resource class in order to take 104 advantage of them:</p> 105 <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> 106 <p>These attributes define the following things:</p> 107 <ol> 108 <li>A initialisation called <code>structure</code> which links 109 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> 110 <li>A document referred to by the name <code>types</code> which 111 is provided by the <code>structure_types.xml</code> file.</li> 112 </ol> 113 <p>To actually perform the initalisation or merge operation, we need to add a few extra 114 lines of code after the addition and deletion operations in the <code>respond_to_form</code> 115 method:</p> 116 <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> 117 <p>These lines do the following things:</p> 118 <ol> 119 <li>Obtain the stylesheet for the <code>structure</code> initialisation.</li> 120 <li>Obtain the <code>types</code> document containing the 121 values to be merged into the form data.</li> 122 <li>Take the stylesheet and apply it to the form data, <code>structure</code>, 123 using a reference to the <code>types</code> document containing 124 the values.</li> 125 </ol> 126 <p>The result of this should be a processed <code>structure</code> 127 document containing the type values for each <code>type</code> 128 element in that document.</p> 129 <h2>Other Multiple-Choice Data</h2> 130 <p>We have now added a simple, single-valued multiple-choice field to 131 the application. However, many applications often need to obtain <a href="multivalue.html">multivalued multiple-choice data</a>, and this 132 kind of information is investigated in the next part of the development 133 <a href="overview.html">process</a>.</p> 134 </body></html>