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"> 3 <head> 4 5 6 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 7 8 9 10 <title>Creating Applications: Add Structure</title> 11 <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 12 13 14 <link href="styles.css" rel="stylesheet" type="text/css" /> 15 </head> 16 17 18 <body> 19 20 <h1>Creating Applications: Add Structure</h1> 21 22 <p>During the <a href="design.html">design</a> activity, it was 23 necessary to consider the structure of the information being presented. 24 In proper XSLForms templates, we make such structural information 25 explicit by adding special attributes to the HTML code. Consider the 26 hierarchy example presented in the previous activity:</p> 27 <ul> 28 <li>A list of editable items, each containing...<br /> 29 <ul> 30 <li>A list of editable items.</li> 31 </ul> 32 </li> 33 </ul> 34 <h2>The XSLForms Conceptual Model</h2> 35 <p>In XSLForms applications form data is processed as XML documents.</p> 36 <ul> 37 <li>We start with an initial XML document which is then used together 38 with a template to produce a Web page that can be understood by a Web 39 browser, and inside this Web page is a form which is used to collect 40 information from users of our application.</li> 41 <li>Upon submission of the form, the form data is processed and appears within our application as an XML document once again.</li> 42 <li>This newly-received document can be processed, validated, and so 43 on, and then used to produce another Web page for the users to interact 44 with.</li> 45 <li>And so the process repeats itself many times.</li> 46 </ul> 47 <p>Therefore, it becomes important to imagine how we would represent 48 the data described above as an XML document; something like this might 49 be appropriate:</p> 50 <pre><?xml version="1.0"?><br /><item value="some value"><br /> <subitem subvalue="some other value"/><br /></item></pre> 51 <p>Therefore, we must seek to add the following structural information to our HTML code:</p> 52 <ul> 53 <li>Each list item is represented by an XML element called "item".</li> 54 <li>The value of each list item is represented by an XML attribute called "value".</li> 55 <li>Items within items are represented by XML elements called "subitem".</li> 56 <li>Each value of these subitems is represented by an XML attribute called "subvalue".</li> 57 </ul> 58 <p>What we must do is to find a way to describe how our template will 59 map onto the form data and present it as a Web page for the purpose of 60 user interaction.<br /> 61 </p> 62 <h2>Annotating the Template</h2> 63 <p>Taking the HTML example from before, we add special annotations to the template to produce something like this:</p> 64 <pre><html xmlns="http://www.w3.org/1999/xhtml"<br /> xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"><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" type="submit" value="Remove" /><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:field-name()}" type="text" value="{$this-value}" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /></div><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></html></pre> 65 <p>The following annotations have been added:</p> 66 <ul> 67 <li>For elements, the <code>template:element</code> attributes were added to the HTML elements which will be replicated when presenting the final output.</li> 68 <li>For attributes, the <code>template:attribute</code> attributes were added to the form <code>input</code> elements.</li> 69 </ul> 70 <p>In addition, some of the attributes in the original HTML code have been changed:</p> 71 <ul> 72 <li>The <code>input</code> elements' <code>name</code> attributes have been redefined to use the special <code>{template:field-name()}</code> value.</li> 73 <li>The <code>input</code> elements' <code>value</code> attributes have been redefined to use the special <code>{$this-value}</code> value.</li> 74 </ul> 75 <p>Whereas the first set of annotations reproduce the desired 76 structure, the latter modifications are really housekeeping measures to 77 make sure that the final output contains the correct names and values 78 for each of the form fields shown to the user.</p> 79 <div class="WebStack"> 80 <h3>Basic Template Annotation</h3> 81 <p>The following special annotations can be used to describe XML document structures in templates:</p> 82 <dl> 83 <dt><code>template:element</code></dt> 84 <dd>This attribute should be added to an element in the template in 85 order to mark that element and its contents as mapping onto or 86 representing an element in the XML document version of the 87 form. In the example, the <code>div</code> element is annotated with this attribute to indicate that it maps onto the <code>item</code> element in the XML document version of the form. It is possible to specify more than one name as the value for a <code>template:element</code> attribute by separating each name with a comma; for example:<br /> 88 <pre><div template:element="parent,child"><br /> <p>This is a child element in the XML document version of the form.</p><br /></div></pre> 89 </dd> 90 <dd>The meaning of this is that the annotated element maps onto all <code>child</code> elements within all <code>parent</code> 91 elements in the XML document version of the form. In other words, 92 instead of having to create separate HTML elements in the template for 93 each XML document element being represented, we can collapse the 94 annotations into a single <code>template:element</code> attribute on a single HTML element.</dd> 95 <dt><code>template:attribute</code></dt> 96 <dd>This attribute should be added to an element in the template in 97 order to mark that element and its contents as mapping onto or 98 representing an attribute in the XML document version of the form. 99 The <code>template:attribute</code> annotation exposes various 100 special values which are described below - such value insert dynamic 101 content from the XML document version of the form into the final output 102 generated from the template.</dd> 103 <dt><code>{$this-value}</code></dt> 104 <dd>This special value should be used in HTML attributes where the 105 value of an attribute from the XML document version of the form is 106 to be included or presented in the final output. In the example, 107 the <code>value</code> and <code>subvalue</code> attributes are presented in the <code>value</code> attributes of the HTML <code>input</code> elements in this way.</dd> 108 <dt><code>{template:field-name()}</code></dt> 109 <dd>This special value should be used in HTML attributes where the 110 name of an attribute from the XML document version of the form is to be 111 included or presented in the final output.</dd> 112 </dl> 113 <p>The <a href="reference.html">reference guide</a> provides a complete list of special values for use in template annotations.</p> 114 </div> 115 <h2>Adding Selectors</h2> 116 <p>Whilst the above annotations permit the template to display the data 117 in XML documents containing form data, the other aspects of the user 118 interface - the addition and removal of items and subitems - are not 119 yet modelled in the template.</p> 120 121 </body> 122 </html>