1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/structure.html Sun Jul 17 01:07:10 2005 +0000
1.3 @@ -0,0 +1,122 @@
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 +
1.8 +
1.9 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.10 +
1.11 +
1.12 +
1.13 + <title>Creating Applications: Add Structure</title>
1.14 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.15 +
1.16 +
1.17 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.18 +</head>
1.19 +
1.20 +
1.21 +<body>
1.22 +
1.23 +<h1>Creating Applications: Add Structure</h1>
1.24 +
1.25 +<p>During the <a href="design.html">design</a> activity, it was
1.26 +necessary to consider the structure of the information being presented.
1.27 +In proper XSLForms templates, we make such structural information
1.28 +explicit by adding special attributes to the HTML code. Consider the
1.29 +hierarchy example presented in the previous activity:</p>
1.30 +<ul>
1.31 + <li>A list of editable items, each containing...<br />
1.32 + <ul>
1.33 + <li>A list of editable items.</li>
1.34 + </ul>
1.35 + </li>
1.36 +</ul>
1.37 +<h2>The XSLForms Conceptual Model</h2>
1.38 +<p>In XSLForms applications form data is processed as XML documents.</p>
1.39 +<ul>
1.40 + <li>We start with an initial XML document which is then used together
1.41 +with a template to produce a Web page that can be understood by a Web
1.42 +browser, and inside this Web page is a form which is used to collect
1.43 +information from users of our application.</li>
1.44 + <li>Upon submission of the form, the form data is processed and appears within our application as an XML document once again.</li>
1.45 + <li>This newly-received document can be processed, validated, and so
1.46 +on, and then used to produce another Web page for the users to interact
1.47 +with.</li>
1.48 + <li>And so the process repeats itself many times.</li>
1.49 +</ul>
1.50 +<p>Therefore, it becomes important to imagine how we would represent
1.51 +the data described above as an XML document; something like this might
1.52 +be appropriate:</p>
1.53 +<pre><?xml version="1.0"?><br /><item value="some value"><br /> <subitem subvalue="some other value"/><br /></item></pre>
1.54 +<p>Therefore, we must seek to add the following structural information to our HTML code:</p>
1.55 +<ul>
1.56 + <li>Each list item is represented by an XML element called "item".</li>
1.57 + <li>The value of each list item is represented by an XML attribute called "value".</li>
1.58 + <li>Items within items are represented by XML elements called "subitem".</li>
1.59 + <li>Each value of these subitems is represented by an XML attribute called "subvalue".</li>
1.60 +</ul>
1.61 +<p>What we must do is to find a way to describe how our template will
1.62 +map onto the form data and present it as a Web page for the purpose of
1.63 +user interaction.<br />
1.64 +</p>
1.65 +<h2>Annotating the Template</h2>
1.66 +<p>Taking the HTML example from before, we add special annotations to the template to produce something like this:</p>
1.67 +<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>
1.68 +<p>The following annotations have been added:</p>
1.69 +<ul>
1.70 + <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>
1.71 + <li>For attributes, the <code>template:attribute</code> attributes were added to the form <code>input</code> elements.</li>
1.72 +</ul>
1.73 +<p>In addition, some of the attributes in the original HTML code have been changed:</p>
1.74 +<ul>
1.75 + <li>The <code>input</code> elements' <code>name</code> attributes have been redefined to use the special <code>{template:field-name()}</code> value.</li>
1.76 + <li>The <code>input</code> elements' <code>value</code> attributes have been redefined to use the special <code>{$this-value}</code> value.</li>
1.77 +</ul>
1.78 +<p>Whereas the first set of annotations reproduce the desired
1.79 +structure, the latter modifications are really housekeeping measures to
1.80 +make sure that the final output contains the correct names and values
1.81 +for each of the form fields shown to the user.</p>
1.82 +<div class="WebStack">
1.83 +<h3>Basic Template Annotation</h3>
1.84 +<p>The following special annotations can be used to describe XML document structures in templates:</p>
1.85 +<dl>
1.86 + <dt><code>template:element</code></dt>
1.87 + <dd>This attribute should be added to an element in the template in
1.88 +order to mark that element and its contents as mapping onto or
1.89 +representing an element in the XML document version of the
1.90 +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 />
1.91 + <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>
1.92 + </dd>
1.93 + <dd>The meaning of this is that the annotated element maps onto all <code>child</code> elements within all <code>parent</code>
1.94 +elements in the XML document version of the form. In other words,
1.95 +instead of having to create separate HTML elements in the template for
1.96 +each XML document element being represented, we can collapse the
1.97 +annotations into a single <code>template:element</code> attribute on a single HTML element.</dd>
1.98 + <dt><code>template:attribute</code></dt>
1.99 + <dd>This attribute should be added to an element in the template in
1.100 +order to mark that element and its contents as mapping onto or
1.101 +representing an attribute in the XML document version of the form.
1.102 +The <code>template:attribute</code> annotation exposes various
1.103 +special values which are described below - such value insert dynamic
1.104 +content from the XML document version of the form into the final output
1.105 +generated from the template.</dd>
1.106 + <dt><code>{$this-value}</code></dt>
1.107 + <dd>This special value should be used in HTML attributes where the
1.108 +value of an attribute from the XML document version of the form is
1.109 +to be included or presented in the final output. In the example,
1.110 +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>
1.111 + <dt><code>{template:field-name()}</code></dt>
1.112 + <dd>This special value should be used in HTML attributes where the
1.113 +name of an attribute from the XML document version of the form is to be
1.114 +included or presented in the final output.</dd>
1.115 +</dl>
1.116 +<p>The <a href="reference.html">reference guide</a> provides a complete list of special values for use in template annotations.</p>
1.117 +</div>
1.118 +<h2>Adding Selectors</h2>
1.119 +<p>Whilst the above annotations permit the template to display the data
1.120 +in XML documents containing form data, the other aspects of the user
1.121 +interface - the addition and removal of items and subitems - are not
1.122 +yet modelled in the template.</p>
1.123 +
1.124 +</body>
1.125 +</html>