1.1 --- a/docs/design.html Sun Jul 17 22:33:17 2005 +0000
1.2 +++ b/docs/design.html Sun Jul 17 22:34:52 2005 +0000
1.3 @@ -2,14 +2,21 @@
1.4 <html xmlns="http://www.w3.org/1999/xhtml">
1.5 <head>
1.6
1.7 +
1.8 +
1.9
1.10 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.11
1.12 +
1.13 +
1.14 +
1.15
1.16
1.17 <title>Creating Applications: Design a Template</title>
1.18 <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.19
1.20 +
1.21 +
1.22
1.23 <link href="styles.css" rel="stylesheet" type="text/css" />
1.24 </head>
1.25 @@ -17,9 +24,11 @@
1.26
1.27 <body>
1.28
1.29 +
1.30 <h1>Creating Applications: Design
1.31 a Template</h1>
1.32
1.33 +
1.34 <p>To design a template, create a
1.35 new Web page using whichever tools or applications you feel most
1.36 comfortable with. Given that XSLForms applications involve Web forms,
1.37 @@ -29,11 +38,11 @@
1.38 is not that important to use the correct names in each of the fields -
1.39 these will be added later.</p>
1.40
1.41 -<p>Here are some tips for
1.42 -designing the template:</p>
1.43
1.44 +<p>The following sections discuss various techniques used in designing a template.</p>
1.45 <h2>Page Structure</h2>
1.46
1.47 +
1.48 <p>Think about your form in terms
1.49 of the structure of the data being represented. You may want to have a
1.50 list of items where each item can be edited by changing a text field
1.51 @@ -42,17 +51,23 @@
1.52 like
1.53 this:</p>
1.54
1.55 +
1.56 <form method="post" action="none" name="structure">
1.57
1.58 +
1.59 <p>Some
1.60 item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" />
1.61 </p>
1.62
1.63 +
1.64 </form>
1.65
1.66 -<p>The HTML code which produces this item might look like this:</p>
1.67 +
1.68 +<p>The HTML code which produces this item in a Web page might look like this:</p>
1.69
1.70 -<pre><p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /></p></pre>
1.71 +
1.72 +<pre><html xmlns="http://www.w3.org/1999/xhtml"><br /><head><br /> <title>Example</title><br /></head><br /><body><br /><br /><!-- Template text between the start and the interesting part. --><br /><br /><form action="" method="POST"><br /><p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /></p><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
1.73 +
1.74
1.75 <p>Although you will only need to
1.76 "paint" one such item in the document, you should imagine that when
1.77 @@ -61,38 +76,52 @@
1.78 an HTML element which can be replicated many times at a particular
1.79 position in a document, like this:</p>
1.80
1.81 +
1.82 <pre><p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /></p><br /><p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /></p><br /><p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /></p></pre>
1.83
1.84 +
1.85 <p>Making sure that the final form of the list is sensible HTML code is
1.86 an activity explored <a href="structure.html">later</a> in the
1.87 development <a href="overview.html">process</a>.</p>
1.88
1.89 +
1.90 <h2>Hierarchical Structures</h2>
1.91
1.92 +
1.93 <p>Although we need not consider the structure of the template too
1.94 deeply, given the above advice about how structure should be
1.95 represented in HTML, it is interesting to consider hierarchical or
1.96 nested structures. For example, each item in a list may itself contain
1.97 a number of other items; for example:</p>
1.98
1.99 +
1.100 <form method="post" action="none" name="hierarchical">
1.101
1.102 +
1.103 <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
1.104
1.105 +
1.106 +
1.107
1.108 <p>Itself containing more items:</p>
1.109
1.110 +
1.111 +
1.112
1.113 <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p>
1.114
1.115 +
1.116 </form>
1.117
1.118 +
1.119 <p>Given that the whole of the above fragment is a single item in a
1.120 list, to ensure that the above advice is heeded about items being
1.121 easily replicated, we need to enclose the fragment in a single HTML
1.122 element, like this:</p>
1.123
1.124 -<pre><div><br /> <p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /></div></pre>
1.125 +
1.126 +<pre><html xmlns="http://www.w3.org/1999/xhtml"><br /><head><br /> <title>Example</title><br /></head><br /><body><br /><form action="" method="POST"><br /><br /><!-- Template text between the start and the interesting part. --><br /><br /><div><br /> <p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other 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 /></form><br /></body><br /></html></pre>
1.127 +
1.128
1.129 <p>In the above example, the <code>div</code> element encloses the
1.130 outer list item. Meanwhile, the inner list item is itself enclosed
1.131 @@ -100,13 +129,17 @@
1.132 example enclosed its simple list item. Consider the above example with
1.133 replicated items:</p>
1.134
1.135 +
1.136 <pre><div><br /> <p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /></div><br /><div><br /> <p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /></div><br /></pre>
1.137
1.138 +
1.139 <h2>Saving the Template</h2>
1.140
1.141 +
1.142 <p>Once you are happy with the
1.143 design of the page, save it to the <a href="directory.html">directory</a>
1.144 created earlier, then proceed to <a href="structure.html">adding structure information</a> in the next stage of the <a href="overview.html">process</a>.</p>
1.145
1.146 +
1.147 </body>
1.148 </html>
2.1 --- a/docs/selectors.html Sun Jul 17 22:33:17 2005 +0000
2.2 +++ b/docs/selectors.html Sun Jul 17 22:34:52 2005 +0000
2.3 @@ -2,52 +2,25 @@
2.4 <html xmlns="http://www.w3.org/1999/xhtml">
2.5 <head>
2.6
2.7 -
2.8 -
2.9 -
2.10 -
2.11 -
2.12 -
2.13 -
2.14 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
2.15 -
2.16 -
2.17 + <title>Creating Applications: Add Selectors</title>
2.18
2.19
2.20 -
2.21 -
2.22 -
2.23 -
2.24 -
2.25 -
2.26 -
2.27 -
2.28 - <title>Creating Applications: Add Selectors</title>
2.29 <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.30
2.31 -
2.32 -
2.33 + <link href="styles.css" rel="stylesheet" type="text/css" />
2.34
2.35 -
2.36 -
2.37 -
2.38 -
2.39 - <link href="styles.css" rel="stylesheet" type="text/css" />
2.40 </head>
2.41
2.42
2.43 <body>
2.44
2.45 -
2.46 -
2.47 -
2.48 <h1>Creating Applications: Add Selectors</h1>
2.49
2.50 -
2.51 -
2.52 -
2.53 -<p>In the previous activity we annotated the template with
2.54 -structural information, and these annotations should be sufficient in
2.55 +<p>In the previous activity we annotated the template
2.56 +with
2.57 +<a href="structure.html">structural information</a>,
2.58 +and these annotations should be sufficient in
2.59 presenting XML documents as Web pages for users to interact with.
2.60 However, in our design, we also wanted to be able to add and remove
2.61 list items from the example hierarchy:</p>
2.62 @@ -56,150 +29,174 @@
2.63
2.64 <li>A list of editable items, each containing...<br />
2.65
2.66 -
2.67 -
2.68 -
2.69 -
2.70 -
2.71 <ul>
2.72
2.73 -
2.74 -
2.75 <li>A list of editable items.</li>
2.76
2.77 -
2.78 -
2.79 -
2.80 -
2.81 -
2.82 </ul>
2.83
2.84 -
2.85 -
2.86 </li>
2.87
2.88 -
2.89 -
2.90 </ul>
2.91
2.92 -<p>What we want to do is to have buttons beside each list item
2.93 +<p>What we want to do is to have buttons beside each
2.94 +list item
2.95 (and subitem) which remove only that particular item. In addition, we
2.96 also want buttons which add items only to the particular list each
2.97 button appears beneath.<br />
2.98
2.99 -
2.100 -
2.101 </p>
2.102
2.103 -
2.104 -
2.105 <h2>Introducing Selectors</h2>
2.106
2.107 -
2.108 -
2.109 -<p>Taking the HTML example from before, we add some additional annotations to the template to produce something like this:</p>
2.110 +<p>So, we need to add buttons to the Web form which,
2.111 +upon being pressed, provide information about their context to
2.112 +the XSLForms framework and subsequently to the application, so that we
2.113 +know which part of the form is to be altered. To make sure that such
2.114 +contextual information is available in the Web form, we must include
2.115 +such references in the descriptions of these buttons in the template.</p>
2.116
2.117 -
2.118 +<p>The concept of a "selector" is a reference which is expressed
2.119 +in a special notation in the template, converted to concrete references
2.120 +in the final output, and can be interpreted when a user submits a form
2.121 +such that the associated section of the XML document version of the
2.122 +form data can be identified in connection with an action. In other
2.123 +words, we write a special value into the definition of a button in a
2.124 +Web form which can automatically be used to refer to other form data
2.125 +when the form is submitted.</p>
2.126
2.127 -<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 /><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 /> <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><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></body><br /></html></pre>
2.128 +<p>Taking the HTML example from before, we add some
2.129 +additional annotations to the template to produce something
2.130 +like this:</p>
2.131 +
2.132 +<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><span style="font-weight: bold;"></span><br /> <span template:attribute="value"><br /> Some item: <input name="{template:field-name()}" type="text" value="{$this-value}" /><br /> </span><br /> <span style="font-weight: bold;"> <input name="remove={template:this-position()}" type="submit" value="Remove" /></span><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p template:element="subitem"><br /> <span template:attribute="subvalue"><br /> Sub-item: <input name="{template:field-name()}" type="text" value="{$this-value}" /><br /> </span><br /> <span style="font-weight: bold;"> <input name="remove2={template:this-position()}" type="submit" value="Remove" /></span><br /> </p><br /> <span style="font-weight: bold;"> <p></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <input name="add2={template:this-position()}" type="submit" value="Add subitem" /></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> </p></span><br /></div><br /><span style="font-weight: bold;"><p></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <input name="add={template:this-position()}" type="submit" value="Add item" /></span><br style="font-weight: bold;" /><span style="font-weight: bold;"></p></span><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
2.133
2.134 <h3>The Remove Buttons</h3>
2.135 -<p>Some of the attributes in the original HTML code have been changed:</p>
2.136
2.137 -
2.138 +<p>Some of the attributes in the original HTML code have been
2.139 +changed:</p>
2.140
2.141 <ul>
2.142
2.143 -
2.144 -
2.145 - <li>The <code>input</code> element for the first <code>Remove</code> button (mapping to <code>item</code> elements in the XML document) has a modified <code>name</code> attribute, containing the special <code>remove={template:this-position()}</code> value.</li>
2.146 + <li>The <code>input</code> element for the
2.147 +first <code>Remove</code> button (mapping
2.148 +to <code>item</code> elements in the XML document)
2.149 +has a modified <code>name</code> attribute,
2.150 +containing the special <code>remove={template:this-position()}</code>
2.151 +value.</li>
2.152
2.153 - <li>The <code>input</code> element for the second <code>Remove</code> button (mapping to <code>subitem</code> elements in the XML document) has a modified <code>name</code> attribute, containing the special <code>remove2={template:this-position()}</code> value.</li>
2.154 -
2.155 -
2.156 -
2.157 -
2.158 + <li>The <code>input</code> element for the second <code>Remove</code>
2.159 +button (mapping to <code>subitem</code> elements in the
2.160 +XML document) has a modified <code>name</code>
2.161 +attribute, containing the special <code>remove2={template:this-position()}</code>
2.162 +value.</li>
2.163
2.164 </ul>
2.165
2.166 -
2.167 -
2.168 -<p>What these amendments provide is a means for the XSLForms framework
2.169 +<p>What these amendments provide is a means for the XSLForms
2.170 +framework
2.171 to connect together the usage of a button in the Web form with an XML
2.172 document element.</p>
2.173
2.174 <ul>
2.175
2.176 - <li>The first <code>Remove</code> button appears within the <code>p</code> element which is annotated as mapping onto the <code>item</code>
2.177 + <li>The first <code>Remove</code> button
2.178 +appears within the <code>p</code> element which is
2.179 +annotated as mapping onto the <code>item</code>
2.180 element in the XML document. This means that the special value added
2.181 above will, in the final output, refer to that specific list item from
2.182 the XML document.</li>
2.183
2.184 - <li>The second <code>Remove</code> button appears within the <code>p</code> element which is annotated as mapping onto the <code>subitem</code>
2.185 + <li>The second <code>Remove</code> button appears
2.186 +within the <code>p</code> element which is
2.187 +annotated as mapping onto the <code>subitem</code>
2.188 element in the XML document. This means that the special value added
2.189 -above will, in the final output, refer to that specific list (sub)item from
2.190 +above will, in the final output, refer to that specific list (sub)item
2.191 +from
2.192 the XML document.</li>
2.193
2.194 </ul>
2.195
2.196 <h3>The Add Buttons</h3>
2.197 -<p>Some additional sections have been added to the original HTML code:</p>
2.198 +
2.199 +<p>Some additional sections have been added to the original HTML
2.200 +code:</p>
2.201
2.202 <ul>
2.203
2.204 - <li>An extra paragraph appears below the <code>subitem</code> paragraph, containing an <code>input</code> element which employs the special <code>add2={template:this-position()}</code> value in the <code>name</code> attribute to represent an <code>Add subitem</code> button.</li>
2.205 + <li>An extra paragraph appears below the <code>subitem</code>
2.206 +paragraph, containing an <code>input</code>
2.207 +element which employs the special <code>add2={template:this-position()}</code>
2.208 +value in the <code>name</code> attribute to
2.209 +represent an <code>Add subitem</code> button.</li>
2.210
2.211 - <li>An extra paragraph appears below the <code>item</code> section, containing an <code>input</code> element which employs the special <code>add={template:this-position()}</code> value in the <code>name</code> attribute to represent an <code>Add item</code> button.</li>
2.212 + <li>An extra paragraph appears below the <code>item</code>
2.213 +section, containing an <code>input</code> element
2.214 +which employs the special <code>add={template:this-position()}</code>
2.215 +value in the <code>name</code> attribute to
2.216 +represent an <code>Add item</code> button.</li>
2.217
2.218 </ul>
2.219
2.220 -<p>What these amendments provide is also a means for the XSLForms framework to connect these buttons to parts of the XML document.</p>
2.221 +<p>What these amendments provide is also a means for the XSLForms
2.222 +framework to connect these buttons to parts of the XML document.</p>
2.223
2.224 <ul>
2.225
2.226 - <li>The <code>Add subitem</code> button appears outside the <code>p</code> element mapping onto the <code>subitem</code> element in the XML document. Instead, it appears within the <code>p</code> element mapping onto the <code>item</code>
2.227 + <li>The <code>Add subitem</code> button appears
2.228 +outside the <code>p</code> element mapping onto
2.229 +the <code>subitem</code> element in the XML
2.230 +document. Instead, it appears within the <code>p</code>
2.231 +element mapping onto the <code>item</code>
2.232 element in the XML document. This means that the special value added
2.233 -above will, in the final output, refer to a specific <code>item</code> from
2.234 -the XML document, and the consequence of adding a <code>subitem</code> will be the extension of that list of <code>subitem</code> elements within that <code>item</code> element.</li>
2.235 +above will, in the final output, refer to a specific <code>item</code>
2.236 +from
2.237 +the XML document, and the consequence of adding a <code>subitem</code>
2.238 +will be the extension of that list of <code>subitem</code>
2.239 +elements within that <code>item</code> element.</li>
2.240
2.241 - <li>The <code>Add item</code> button appears outside the <code>p</code> element mapping onto the <code>item</code>
2.242 -element in the XML document. Instead, it appears within the <code>body</code> element mapping onto the top-level <code>structure</code>
2.243 + <li>The <code>Add item</code> button
2.244 +appears outside the <code>p</code>
2.245 +element mapping onto the <code>item</code>
2.246 +element in the XML document. Instead, it appears within the <code>body</code>
2.247 +element mapping onto the top-level <code>structure</code>
2.248 element in the XML document. This means that the special value added
2.249 above will, in the final output, refer to the top-level <code>structure</code>
2.250 element in
2.251 -the XML document, and the consequence of adding an <code>item</code> will be the extension of the main list of <code>item</code> elements.</li>
2.252 +the XML document, and the consequence of adding an <code>item</code> will
2.253 +be the extension of the main list of <code>item</code>
2.254 +elements.</li>
2.255
2.256 </ul>
2.257 +
2.258 <div class="WebStack">
2.259 <h3>Selector Annotation</h3>
2.260
2.261 -
2.262 -
2.263 -<p>Special values of the following form can be used to connect parts of
2.264 -the template with elements in the XML document representation of a form:</p>
2.265 -
2.266 -
2.267 +<p>Special values of the following form can be used to connect
2.268 +parts of the template with elements in the XML document representation
2.269 +of a form:</p>
2.270
2.271 <dl>
2.272 +
2.273 <dt><code>selector={template:this-position()}</code></dt>
2.274
2.275 -
2.276 -
2.277 - <dd>Given a selector name (<code>selector</code> in this example),
2.278 -this special value produces a reference to an XML document element (or
2.279 -attribute) in the final output. The referenced element or attribute is
2.280 -defined by those <code>template:element</code> and <code>template:attribute</code> annotations on template elements which surround the template element within which this special value is used.</dd>
2.281 -
2.282 -
2.283 + <dd>Given a selector name (<code>selector</code> in
2.284 +this example), this special value produces a reference to an XML
2.285 +document element (or attribute) in the final output. The referenced
2.286 +element or attribute is defined by those <code>template:element</code>
2.287 +and <code>template:attribute</code> annotations on
2.288 +template elements which surround the template element within
2.289 +which this special value is used.</dd>
2.290
2.291 </dl>
2.292
2.293 -
2.294 -
2.295 -<p>The <a href="reference.html">reference guide</a> provides a complete list of special values for use in template annotations.</p>
2.296 -
2.297 -
2.298 +<p>The <a href="reference.html">reference guide</a>
2.299 +provides a complete list of special values for use in template
2.300 +annotations.</p>
2.301
2.302 </div>
2.303 +
2.304 +<p>Whilst many forms consist only of text fields and action buttons, other types of data are very likely to also be used. <a href="multiple.html">Multiple-choice or enumerated value fields</a> in forms are covered in the next activity in the development <a href="overview.html">process</a>.</p>
2.305 +
2.306 </body>
2.307 </html>
3.1 --- a/docs/structure.html Sun Jul 17 22:33:17 2005 +0000
3.2 +++ b/docs/structure.html Sun Jul 17 22:34:52 2005 +0000
3.3 @@ -5,6 +5,8 @@
3.4
3.5
3.6
3.7 +
3.8 +
3.9
3.10
3.11
3.12 @@ -14,6 +16,9 @@
3.13
3.14
3.15
3.16 +
3.17 +
3.18 +
3.19
3.20
3.21
3.22 @@ -28,6 +33,8 @@
3.23
3.24
3.25
3.26 +
3.27 +
3.28
3.29
3.30
3.31 @@ -41,11 +48,13 @@
3.32
3.33
3.34
3.35 +
3.36 <h1>Creating Applications: Add Structure</h1>
3.37
3.38
3.39
3.40
3.41 +
3.42 <p>During the <a href="design.html">design</a> activity, it was
3.43 necessary to consider the structure of the information being presented.
3.44 In proper XSLForms templates, we make such structural information
3.45 @@ -54,14 +63,18 @@
3.46
3.47
3.48
3.49 +
3.50 <ul>
3.51
3.52
3.53
3.54 +
3.55 <li>A list of editable items, each containing...<br />
3.56
3.57
3.58
3.59 +
3.60 +
3.61
3.62
3.63
3.64 @@ -69,81 +82,102 @@
3.65
3.66
3.67
3.68 +
3.69 <li>A list of editable items.</li>
3.70
3.71
3.72
3.73 +
3.74
3.75
3.76
3.77 +
3.78 </ul>
3.79
3.80
3.81
3.82 +
3.83 </li>
3.84
3.85
3.86
3.87 +
3.88 </ul>
3.89
3.90 +
3.91 <p>
3.92 Since XSLForms is all about the processing of <a href="model.html">form data as simple XML documents</a>, it becomes important to imagine how we would represent
3.93 the data described above as an XML document; something like this might
3.94 be appropriate:
3.95 </p>
3.96
3.97 +
3.98 <pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre>
3.99
3.100
3.101
3.102 +
3.103 <p>Therefore, we must seek to add the following structural information to our HTML code:</p>
3.104
3.105
3.106
3.107 +
3.108 <ul>
3.109
3.110
3.111
3.112 +
3.113 <li>Each list item is represented by an XML element called <code>item</code>.</li>
3.114
3.115
3.116
3.117 +
3.118 <li>The value of each list item is represented by an XML attribute called <code>value</code>.</li>
3.119
3.120
3.121
3.122 +
3.123 <li>Items within items are represented by XML elements called <code>subitem</code>.</li>
3.124
3.125
3.126
3.127 +
3.128 <li>Each value of these subitems is represented by an XML attribute called <code>subvalue</code>.</li>
3.129 +
3.130 <li>Outside all this is a containing <code>structure</code>.</li>
3.131
3.132
3.133
3.134 +
3.135 </ul>
3.136
3.137
3.138
3.139 +
3.140 <p>What we must do is to find a way to describe how our template will
3.141 map onto the form data and present it as a Web page for the purpose of
3.142 user interaction.<br />
3.143
3.144
3.145
3.146 +
3.147 </p>
3.148
3.149
3.150
3.151 +
3.152 <h2>Annotating the Template</h2>
3.153
3.154
3.155
3.156 +
3.157 <p>Taking the HTML example from before, we add special annotations to the template to produce something like this:</p>
3.158
3.159
3.160
3.161 -<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 /><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 /></body><br /></html></pre>
3.162 +
3.163 +<pre><html xmlns="http://www.w3.org/1999/xhtml"<br /> <span style="font-weight: bold;">xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"</span>><br /><head><br /> <title>Example</title><br /></head><br /><span style="font-weight: bold;"><body template:element="structure"></span><br /><form action="" method="POST"><br /><br /><!-- Template text between the start and the interesting part. --><br /><br /><span style="font-weight: bold;"><div template:element="item"></span><br /> <p><br /> <span style="font-weight: bold;"><span template:attribute="value"><br /></span> Some item: <span style="font-weight: bold;"><input name="{template:field-name()}" type="text" value="{$this-value}" /><br /> </span><br /></span> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <span style="font-weight: bold;"><p template:element="subitem"></span><br /> <span style="font-weight: bold;"><span template:attribute="subvalue"></span><br /> Sub-item: <span style="font-weight: bold;"><input name="{template:field-name()}" type="text" value="{$this-value}" /><br /> </span><br /></span> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /></div><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
3.164 +
3.165
3.166
3.167
3.168 @@ -151,15 +185,19 @@
3.169
3.170
3.171
3.172 +
3.173 <ul>
3.174
3.175
3.176
3.177 +
3.178 <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>
3.179
3.180
3.181
3.182 - <li>For attributes, the <code>template:attribute</code> attributes were added to the form <code>input</code> elements.</li>
3.183 +
3.184 + <li>For attributes, the <code>template:attribute</code> attributes were added to some new HTML <code>span</code> elements.</li>
3.185 +
3.186
3.187
3.188
3.189 @@ -167,30 +205,39 @@
3.190
3.191
3.192
3.193 +
3.194 <p>In addition, some of the attributes in the original HTML code have been changed:</p>
3.195
3.196
3.197
3.198 +
3.199 <ul>
3.200
3.201
3.202
3.203 +
3.204 <li>The <code>input</code> elements' <code>name</code> attributes have been redefined to use the special <code>{template:field-name()}</code> value.</li>
3.205
3.206
3.207
3.208 +
3.209 <li>The <code>input</code> elements' <code>value</code> attributes have been redefined to use the special <code>{$this-value}</code> value.</li>
3.210
3.211
3.212
3.213 +
3.214 </ul>
3.215
3.216
3.217
3.218 +
3.219 <p>Whereas the first set of annotations reproduce the desired
3.220 structure, the latter modifications are really housekeeping measures to
3.221 make sure that the final output contains the correct names and values
3.222 for each of the form fields shown to the user.</p>
3.223 +<h3>The Template Namespace</h3>
3.224 +<p>Note also that a namespace declaration is required for the <code>template</code> attributes, and it is usually best to put this declaration on the top-level <code>html</code> element in the template.</p>
3.225 +
3.226
3.227
3.228
3.229 @@ -199,18 +246,22 @@
3.230
3.231
3.232
3.233 +
3.234 <p>The following special annotations can be used to describe XML document structures in templates:</p>
3.235
3.236
3.237
3.238 +
3.239 <dl>
3.240
3.241
3.242
3.243 +
3.244 <dt><code>template:element</code></dt>
3.245
3.246
3.247
3.248 +
3.249 <dd>This attribute should be added to an element in the template in
3.250 order to mark that element and its contents as mapping onto or
3.251 representing an element in the XML document version of the
3.252 @@ -218,6 +269,8 @@
3.253
3.254
3.255
3.256 +
3.257 +
3.258
3.259
3.260
3.261 @@ -225,10 +278,12 @@
3.262
3.263
3.264
3.265 +
3.266 </dd>
3.267
3.268
3.269
3.270 +
3.271 <dd>The meaning of this is that the annotated element maps onto all <code>child</code> elements within all <code>parent</code>
3.272 elements in the XML document version of the form. In other words,
3.273 instead of having to create separate HTML elements in the template for
3.274 @@ -237,12 +292,14 @@
3.275
3.276
3.277
3.278 +
3.279 <dt><code>template:attribute</code></dt>
3.280
3.281
3.282
3.283 +
3.284 <dd>This attribute should be added to an element in the template in
3.285 -order to mark that element and its contents as mapping onto or
3.286 +order to mark that element and its contents as mapping onto or
3.287 representing an attribute in the XML document version of the form.
3.288 The <code>template:attribute</code> annotation exposes various
3.289 special values which are described below - such value insert dynamic
3.290 @@ -251,10 +308,12 @@
3.291
3.292
3.293
3.294 +
3.295 <dt><code>{$this-value}</code></dt>
3.296
3.297
3.298
3.299 +
3.300 <dd>This special value should be used in HTML attributes where the
3.301 value of an attribute from the XML document version of the form is
3.302 to be included or presented in the final output. In the example,
3.303 @@ -262,28 +321,34 @@
3.304
3.305
3.306
3.307 +
3.308 <dt><code>{template:field-name()}</code></dt>
3.309
3.310
3.311
3.312 +
3.313 <dd>This special value should be used in HTML attributes where the
3.314 name of an attribute from the XML document version of the form is to be
3.315 included or presented in the final output.</dd>
3.316
3.317
3.318
3.319 +
3.320 </dl>
3.321
3.322
3.323
3.324 +
3.325 <p>The <a href="reference.html">reference guide</a> provides a complete list of special values for use in template annotations.</p>
3.326
3.327
3.328
3.329 +
3.330 </div>
3.331
3.332
3.333
3.334 +
3.335 <p>Whilst the above annotations permit the template to display the data
3.336 in XML documents containing form data, the other aspects of the user
3.337 interface - the addition and removal of items and subitems - are not
3.338 @@ -294,5 +359,6 @@
3.339
3.340
3.341
3.342 +
3.343 </body>
3.344 </html>