1.1 --- a/docs/index.html Sun Jul 17 01:07:10 2005 +0000
1.2 +++ b/docs/index.html Sun Jul 17 19:18:51 2005 +0000
1.3 @@ -1,46 +1,66 @@
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>Developing Web Applications with XSLTools</title>
1.14 - <meta name="generator"
1.15 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.16 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.17 +
1.18 +
1.19 <link href="styles.css" rel="stylesheet" type="text/css" />
1.20 </head>
1.21 +
1.22 +
1.23 <body>
1.24 +
1.25 <h1>Developing Web Applications with XSLTools</h1>
1.26 +
1.27 <p>This documentation introduces the XSLTools package and the XSLForms
1.28 -framework for developing forms-based Web applications using Python, <a
1.29 - href="http://www.boddie.org.uk/python/libxml2dom.html">libxml2dom</a>,
1.30 -libxml2, libxslt and (optionally) <a
1.31 - href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>.</p>
1.32 +framework for developing forms-based Web applications using Python, <a href="http://www.boddie.org.uk/python/libxml2dom.html">libxml2dom</a>,
1.33 +libxml2, libxslt and (optionally) <a href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>.</p>
1.34 +
1.35 <h2>Setting Up</h2>
1.36 +
1.37 <p>First of all, let us assume that the XSLTools distribution has been
1.38 unpacked and now sits in the <code>XSLTools-0.1</code> directory.</p>
1.39 +
1.40 <p>Before we begin, we must make sure that the XSLTools package is
1.41 available
1.42 to Python. The easiest way to do this is to change into the <code>XSLTools-0.1</code>
1.43 directory and to run the <code>setup.py</code>
1.44 script provided with the version of Python you are going to be using
1.45 (possibly as a privileged user like <code>root</code>):</p>
1.46 +
1.47 <pre>cd XSLTools-0.1<br />python setup.py install</pre>
1.48 +
1.49 <p>If you don't want to install XSLTools in this way, or if you can't
1.50 do so
1.51 because you don't have <code>root</code> privileges, you can just make
1.52 sure
1.53 that the <code>XSLTools-0.1</code> directory sits on your
1.54 <code>PYTHONPATH</code>.</p>
1.55 +
1.56 <h2>Viewing the API Documentation</h2>
1.57 +
1.58 <p>The API documentation for use in conjunction with this
1.59 guide can be found inside the <a href="../apidocs/index.html"><code>apidocs</code></a>
1.60 directory within the <code>XSLTools-0.1</code> directory. Of course,
1.61 it is always possible to view the API documentation
1.62 -within Python by importing modules (such as <a
1.63 - href="../apidocs/public/XSLOutput-module.html"><code>XSLOutput</code></a>)
1.64 +within Python by importing modules (such as <a href="../apidocs/public/XSLOutput-module.html"><code>XSLOutput</code></a>)
1.65 and using Python's built-in <code>help</code> function.</p>
1.66 +
1.67 <h2>About XSLForms Applications</h2>
1.68 +
1.69 <ul>
1.70 +
1.71 + <li><a href="model.html">The XSLForms Conceptual Model</a></li>
1.72 <li><a href="overview.html">Creating Applications: An Overview</a></li>
1.73 +
1.74 </ul>
1.75 +
1.76 </body>
1.77 </html>
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/model.html Sun Jul 17 19:18:51 2005 +0000
2.3 @@ -0,0 +1,56 @@
2.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.5 +<html xmlns="http://www.w3.org/1999/xhtml">
2.6 +<head>
2.7 +
2.8 +
2.9 +
2.10 +
2.11 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
2.12 +
2.13 +
2.14 +
2.15 +
2.16 +
2.17 +
2.18 + <title>The XSLForms Conceptual Model</title>
2.19 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.20 +
2.21 +
2.22 +
2.23 +
2.24 + <link href="styles.css" rel="stylesheet" type="text/css" />
2.25 +</head>
2.26 +
2.27 +
2.28 +<body>
2.29 +<h1>The XSLForms Conceptual Model</h1>
2.30 +
2.31 +<p>In applications based on XSLForms, form data is processed as XML documents as shown in the following diagram:</p>
2.32 +<table style="text-align: left; width: 80%;" align="center" border="0" cellpadding="5" cellspacing="5">
2.33 + <tbody>
2.34 + <tr>
2.35 + <td align="undefined" valign="undefined"></td>
2.36 + <th style="border: 1px solid rgb(0, 0, 0); background-color: rgb(193, 255, 102); text-align: center; vertical-align: top;">Application<br />
2.37 + <span class="method">Starting with an initial XML document...</span></th>
2.38 + <th style="text-align: center; vertical-align: top;">XSLForms<br />
2.39 + <span class="method">A template is used together with the XML document to produce a Web page...</span></th>
2.40 + <th style="border: 1px solid rgb(0, 0, 0); background-color: rgb(255, 204, 255); text-align: center; vertical-align: top;">Browser<br />
2.41 + <span class="method">The Web page contains a form which is filled out by users of the application and submitted back to the application...</span></th>
2.42 + </tr>
2.43 + <tr>
2.44 + <th style="text-align: center; vertical-align: top;">XSLForms<br />
2.45 + <span class="method">The incoming form data is converted to an XML document...</span></th>
2.46 + <th style="border: 1px solid rgb(0, 0, 0); background-color: rgb(193, 255, 102); text-align: center; vertical-align: top;">Application<br />
2.47 + <span class="method">The incoming XML document is processed, validated, and so on...</span></th>
2.48 + <th style="text-align: center; vertical-align: top;">XSLForms<span class="method">A template is used together with the new XML document to produce a Web page...</span></th>
2.49 + <th style="border: 1px solid rgb(0, 0, 0); background-color: rgb(255, 204, 255); text-align: center; vertical-align: top;">Browser<span class="method">An updated Web page is shown to the user. The page may contain a form which may be filled out and submitted...</span></th>
2.50 + </tr>
2.51 + </tbody>
2.52 +</table>
2.53 +<p>The XSLForms framework therefore performs two main functions:</p>
2.54 +<ul>
2.55 + <li>To present XML documents as Web pages containing forms.</li>
2.56 + <li>To interpret submitted Web form information and to convert that information to XML.</li>
2.57 +</ul>
2.58 +</body>
2.59 +</html>
3.1 --- a/docs/overview.html Sun Jul 17 01:07:10 2005 +0000
3.2 +++ b/docs/overview.html Sun Jul 17 19:18:51 2005 +0000
3.3 @@ -1,34 +1,59 @@
3.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.5 <html xmlns="http://www.w3.org/1999/xhtml">
3.6 <head>
3.7 +
3.8 +
3.9 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
3.10 +
3.11 +
3.12 +
3.13 <title>Creating Applications: An Overview</title>
3.14 - <meta name="generator"
3.15 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.16 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.17 +
3.18 +
3.19 <link href="styles.css" rel="stylesheet" type="text/css" />
3.20 </head>
3.21 +
3.22 +
3.23 <body>
3.24 +
3.25 <h1>Creating Applications: An Overview</h1>
3.26 +
3.27 <p>The following steps briefly describe how to make a new application:<br />
3.28 +
3.29 </p>
3.30 +
3.31 <ol>
3.32 +
3.33 <li><a href="directory.html">Create a directory to hold your files</a></li>
3.34 +
3.35 <li><a href="design.html">Design a template</a></li>
3.36 +
3.37 <li><a href="structure.html">Add structure to the template</a></li>
3.38 + <li><a href="selectors.html">Add selectors to the template</a></li>
3.39 +
3.40 <li><a href="catalogues.html">Prepare catalogues of multiple-choice
3.41 values</a></li>
3.42 +
3.43 <li><a href="Web-resource.html">Write a Web resource to display the
3.44 form</a></li>
3.45 +
3.46 </ol>
3.47 +
3.48 <h2>Recommendations</h2>
3.49 +
3.50 <ol>
3.51 +
3.52 <li>Where multiple fields exist and can be added and removed, put
3.53 them inside a separate element so that the selectors can successfully
3.54 identify them. Otherwise, changing element orders can result in the
3.55 wrong element being selected.</li>
3.56 +
3.57 <li>Make sure that transformations on the input document produce all
3.58 the necessary elements for the output document so that the resulting
3.59 page gives the user the opportunity to specify data that is missing.</li>
3.60 +
3.61 </ol>
3.62 +
3.63 </body>
3.64 </html>
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/selectors.html Sun Jul 17 19:18:51 2005 +0000
4.3 @@ -0,0 +1,205 @@
4.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4.5 +<html xmlns="http://www.w3.org/1999/xhtml">
4.6 +<head>
4.7 +
4.8 +
4.9 +
4.10 +
4.11 +
4.12 +
4.13 +
4.14 +
4.15 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
4.16 +
4.17 +
4.18 +
4.19 +
4.20 +
4.21 +
4.22 +
4.23 +
4.24 +
4.25 +
4.26 +
4.27 +
4.28 + <title>Creating Applications: Add Selectors</title>
4.29 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.30 +
4.31 +
4.32 +
4.33 +
4.34 +
4.35 +
4.36 +
4.37 +
4.38 + <link href="styles.css" rel="stylesheet" type="text/css" />
4.39 +</head>
4.40 +
4.41 +
4.42 +<body>
4.43 +
4.44 +
4.45 +
4.46 +
4.47 +<h1>Creating Applications: Add Selectors</h1>
4.48 +
4.49 +
4.50 +
4.51 +
4.52 +<p>In the previous activity we annotated the template with
4.53 +structural information, and these annotations should be sufficient in
4.54 +presenting XML documents as Web pages for users to interact with.
4.55 +However, in our design, we also wanted to be able to add and remove
4.56 +list items from the example hierarchy:</p>
4.57 +
4.58 +<ul>
4.59 +
4.60 + <li>A list of editable items, each containing...<br />
4.61 +
4.62 +
4.63 +
4.64 +
4.65 +
4.66 +
4.67 + <ul>
4.68 +
4.69 +
4.70 +
4.71 + <li>A list of editable items.</li>
4.72 +
4.73 +
4.74 +
4.75 +
4.76 +
4.77 +
4.78 + </ul>
4.79 +
4.80 +
4.81 +
4.82 + </li>
4.83 +
4.84 +
4.85 +
4.86 +</ul>
4.87 +
4.88 +<p>What we want to do is to have buttons beside each list item
4.89 +(and subitem) which remove only that particular item. In addition, we
4.90 +also want buttons which add items only to the particular list each
4.91 +button appears beneath.<br />
4.92 +
4.93 +
4.94 +
4.95 +</p>
4.96 +
4.97 +
4.98 +
4.99 +<h2>Introducing Selectors</h2>
4.100 +
4.101 +
4.102 +
4.103 +<p>Taking the HTML example from before, we add some additional annotations to the template to produce something like this:</p>
4.104 +
4.105 +
4.106 +
4.107 +<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>
4.108 +
4.109 +<h3>The Remove Buttons</h3>
4.110 +<p>Some of the attributes in the original HTML code have been changed:</p>
4.111 +
4.112 +
4.113 +
4.114 +<ul>
4.115 +
4.116 +
4.117 +
4.118 + <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>
4.119 +
4.120 + <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>
4.121 +
4.122 +
4.123 +
4.124 +
4.125 +
4.126 +</ul>
4.127 +
4.128 +
4.129 +
4.130 +<p>What these amendments provide is a means for the XSLForms framework
4.131 +to connect together the usage of a button in the Web form with an XML
4.132 +document element.</p>
4.133 +
4.134 +<ul>
4.135 +
4.136 + <li>The first <code>Remove</code> button appears within the <code>p</code> element which is annotated as mapping onto the <code>item</code>
4.137 +element in the XML document. This means that the special value added
4.138 +above will, in the final output, refer to that specific list item from
4.139 +the XML document.</li>
4.140 +
4.141 + <li>The second <code>Remove</code> button appears within the <code>p</code> element which is annotated as mapping onto the <code>subitem</code>
4.142 +element in the XML document. This means that the special value added
4.143 +above will, in the final output, refer to that specific list (sub)item from
4.144 +the XML document.</li>
4.145 +
4.146 +</ul>
4.147 +
4.148 +<h3>The Add Buttons</h3>
4.149 +<p>Some additional sections have been added to the original HTML code:</p>
4.150 +
4.151 +<ul>
4.152 +
4.153 + <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>
4.154 +
4.155 + <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>
4.156 +
4.157 +</ul>
4.158 +
4.159 +<p>What these amendments provide is also a means for the XSLForms framework to connect these buttons to parts of the XML document.</p>
4.160 +
4.161 +<ul>
4.162 +
4.163 + <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>
4.164 +element in the XML document. This means that the special value added
4.165 +above will, in the final output, refer to a specific <code>item</code> from
4.166 +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>
4.167 +
4.168 + <li>The <code>Add item</code> button appears outside the <code>p</code> element mapping onto the <code>item</code>
4.169 +element in the XML document. Instead, it appears within the <code>body</code> element mapping onto the top-level <code>structure</code>
4.170 +element in the XML document. This means that the special value added
4.171 +above will, in the final output, refer to the top-level <code>structure</code>
4.172 +element in
4.173 +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>
4.174 +
4.175 +</ul>
4.176 +<div class="WebStack">
4.177 +<h3>Selector Annotation</h3>
4.178 +
4.179 +
4.180 +
4.181 +<p>Special values of the following form can be used to connect parts of
4.182 +the template with elements in the XML document representation of a form:</p>
4.183 +
4.184 +
4.185 +
4.186 +<dl>
4.187 + <dt><code>selector={template:this-position()}</code></dt>
4.188 +
4.189 +
4.190 +
4.191 + <dd>Given a selector name (<code>selector</code> in this example),
4.192 +this special value produces a reference to an XML document element (or
4.193 +attribute) in the final output. The referenced element or attribute is
4.194 +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>
4.195 +
4.196 +
4.197 +
4.198 +</dl>
4.199 +
4.200 +
4.201 +
4.202 +<p>The <a href="reference.html">reference guide</a> provides a complete list of special values for use in template annotations.</p>
4.203 +
4.204 +
4.205 +
4.206 +</div>
4.207 +</body>
4.208 +</html>
5.1 --- a/docs/structure.html Sun Jul 17 01:07:10 2005 +0000
5.2 +++ b/docs/structure.html Sun Jul 17 19:18:51 2005 +0000
5.3 @@ -2,14 +2,35 @@
5.4 <html xmlns="http://www.w3.org/1999/xhtml">
5.5 <head>
5.6
5.7 +
5.8 +
5.9 +
5.10 +
5.11 +
5.12 +
5.13
5.14 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
5.15
5.16 +
5.17 +
5.18 +
5.19 +
5.20 +
5.21 +
5.22 +
5.23 +
5.24 +
5.25
5.26
5.27 <title>Creating Applications: Add Structure</title>
5.28 <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
5.29
5.30 +
5.31 +
5.32 +
5.33 +
5.34 +
5.35 +
5.36
5.37 <link href="styles.css" rel="stylesheet" type="text/css" />
5.38 </head>
5.39 @@ -17,82 +38,209 @@
5.40
5.41 <body>
5.42
5.43 +
5.44 +
5.45 +
5.46 <h1>Creating Applications: Add Structure</h1>
5.47
5.48 +
5.49 +
5.50 +
5.51 <p>During the <a href="design.html">design</a> activity, it was
5.52 necessary to consider the structure of the information being presented.
5.53 In proper XSLForms templates, we make such structural information
5.54 explicit by adding special attributes to the HTML code. Consider the
5.55 hierarchy example presented in the previous activity:</p>
5.56 -<ul>
5.57 - <li>A list of editable items, each containing...<br />
5.58 - <ul>
5.59 - <li>A list of editable items.</li>
5.60 - </ul>
5.61 - </li>
5.62 -</ul>
5.63 -<h2>The XSLForms Conceptual Model</h2>
5.64 -<p>In XSLForms applications form data is processed as XML documents.</p>
5.65 +
5.66 +
5.67 +
5.68 <ul>
5.69 - <li>We start with an initial XML document which is then used together
5.70 -with a template to produce a Web page that can be understood by a Web
5.71 -browser, and inside this Web page is a form which is used to collect
5.72 -information from users of our application.</li>
5.73 - <li>Upon submission of the form, the form data is processed and appears within our application as an XML document once again.</li>
5.74 - <li>This newly-received document can be processed, validated, and so
5.75 -on, and then used to produce another Web page for the users to interact
5.76 -with.</li>
5.77 - <li>And so the process repeats itself many times.</li>
5.78 +
5.79 +
5.80 +
5.81 + <li>A list of editable items, each containing...<br />
5.82 +
5.83 +
5.84 +
5.85 +
5.86 +
5.87 +
5.88 + <ul>
5.89 +
5.90 +
5.91 +
5.92 + <li>A list of editable items.</li>
5.93 +
5.94 +
5.95 +
5.96 +
5.97 +
5.98 +
5.99 + </ul>
5.100 +
5.101 +
5.102 +
5.103 + </li>
5.104 +
5.105 +
5.106 +
5.107 </ul>
5.108 -<p>Therefore, it becomes important to imagine how we would represent
5.109 +
5.110 +<p>
5.111 +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
5.112 the data described above as an XML document; something like this might
5.113 -be appropriate:</p>
5.114 -<pre><?xml version="1.0"?><br /><item value="some value"><br /> <subitem subvalue="some other value"/><br /></item></pre>
5.115 +be appropriate:
5.116 +</p>
5.117 +
5.118 +<pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre>
5.119 +
5.120 +
5.121 +
5.122 <p>Therefore, we must seek to add the following structural information to our HTML code:</p>
5.123 +
5.124 +
5.125 +
5.126 <ul>
5.127 - <li>Each list item is represented by an XML element called "item".</li>
5.128 - <li>The value of each list item is represented by an XML attribute called "value".</li>
5.129 - <li>Items within items are represented by XML elements called "subitem".</li>
5.130 - <li>Each value of these subitems is represented by an XML attribute called "subvalue".</li>
5.131 +
5.132 +
5.133 +
5.134 + <li>Each list item is represented by an XML element called <code>item</code>.</li>
5.135 +
5.136 +
5.137 +
5.138 + <li>The value of each list item is represented by an XML attribute called <code>value</code>.</li>
5.139 +
5.140 +
5.141 +
5.142 + <li>Items within items are represented by XML elements called <code>subitem</code>.</li>
5.143 +
5.144 +
5.145 +
5.146 + <li>Each value of these subitems is represented by an XML attribute called <code>subvalue</code>.</li>
5.147 + <li>Outside all this is a containing <code>structure</code>.</li>
5.148 +
5.149 +
5.150 +
5.151 </ul>
5.152 +
5.153 +
5.154 +
5.155 <p>What we must do is to find a way to describe how our template will
5.156 map onto the form data and present it as a Web page for the purpose of
5.157 user interaction.<br />
5.158 +
5.159 +
5.160 +
5.161 </p>
5.162 +
5.163 +
5.164 +
5.165 <h2>Annotating the Template</h2>
5.166 +
5.167 +
5.168 +
5.169 <p>Taking the HTML example from before, we add special annotations to the template to produce something like this:</p>
5.170 -<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>
5.171 +
5.172 +
5.173 +
5.174 +<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>
5.175 +
5.176 +
5.177 +
5.178 <p>The following annotations have been added:</p>
5.179 +
5.180 +
5.181 +
5.182 <ul>
5.183 +
5.184 +
5.185 +
5.186 <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>
5.187 +
5.188 +
5.189 +
5.190 <li>For attributes, the <code>template:attribute</code> attributes were added to the form <code>input</code> elements.</li>
5.191 +
5.192 +
5.193 +
5.194 </ul>
5.195 +
5.196 +
5.197 +
5.198 <p>In addition, some of the attributes in the original HTML code have been changed:</p>
5.199 +
5.200 +
5.201 +
5.202 <ul>
5.203 +
5.204 +
5.205 +
5.206 <li>The <code>input</code> elements' <code>name</code> attributes have been redefined to use the special <code>{template:field-name()}</code> value.</li>
5.207 +
5.208 +
5.209 +
5.210 <li>The <code>input</code> elements' <code>value</code> attributes have been redefined to use the special <code>{$this-value}</code> value.</li>
5.211 +
5.212 +
5.213 +
5.214 </ul>
5.215 +
5.216 +
5.217 +
5.218 <p>Whereas the first set of annotations reproduce the desired
5.219 structure, the latter modifications are really housekeeping measures to
5.220 make sure that the final output contains the correct names and values
5.221 for each of the form fields shown to the user.</p>
5.222 +
5.223 +
5.224 +
5.225 <div class="WebStack">
5.226 <h3>Basic Template Annotation</h3>
5.227 +
5.228 +
5.229 +
5.230 <p>The following special annotations can be used to describe XML document structures in templates:</p>
5.231 +
5.232 +
5.233 +
5.234 <dl>
5.235 +
5.236 +
5.237 +
5.238 <dt><code>template:element</code></dt>
5.239 +
5.240 +
5.241 +
5.242 <dd>This attribute should be added to an element in the template in
5.243 order to mark that element and its contents as mapping onto or
5.244 representing an element in the XML document version of the
5.245 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 />
5.246 +
5.247 +
5.248 +
5.249 +
5.250 +
5.251 +
5.252 <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>
5.253 +
5.254 +
5.255 +
5.256 </dd>
5.257 +
5.258 +
5.259 +
5.260 <dd>The meaning of this is that the annotated element maps onto all <code>child</code> elements within all <code>parent</code>
5.261 elements in the XML document version of the form. In other words,
5.262 instead of having to create separate HTML elements in the template for
5.263 each XML document element being represented, we can collapse the
5.264 annotations into a single <code>template:element</code> attribute on a single HTML element.</dd>
5.265 +
5.266 +
5.267 +
5.268 <dt><code>template:attribute</code></dt>
5.269 +
5.270 +
5.271 +
5.272 <dd>This attribute should be added to an element in the template in
5.273 order to mark that element and its contents as mapping onto or
5.274 representing an attribute in the XML document version of the form.
5.275 @@ -100,23 +248,51 @@
5.276 special values which are described below - such value insert dynamic
5.277 content from the XML document version of the form into the final output
5.278 generated from the template.</dd>
5.279 +
5.280 +
5.281 +
5.282 <dt><code>{$this-value}</code></dt>
5.283 +
5.284 +
5.285 +
5.286 <dd>This special value should be used in HTML attributes where the
5.287 value of an attribute from the XML document version of the form is
5.288 to be included or presented in the final output. In the example,
5.289 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>
5.290 +
5.291 +
5.292 +
5.293 <dt><code>{template:field-name()}</code></dt>
5.294 +
5.295 +
5.296 +
5.297 <dd>This special value should be used in HTML attributes where the
5.298 name of an attribute from the XML document version of the form is to be
5.299 included or presented in the final output.</dd>
5.300 +
5.301 +
5.302 +
5.303 </dl>
5.304 +
5.305 +
5.306 +
5.307 <p>The <a href="reference.html">reference guide</a> provides a complete list of special values for use in template annotations.</p>
5.308 +
5.309 +
5.310 +
5.311 </div>
5.312 -<h2>Adding Selectors</h2>
5.313 +
5.314 +
5.315 +
5.316 <p>Whilst the above annotations permit the template to display the data
5.317 in XML documents containing form data, the other aspects of the user
5.318 interface - the addition and removal of items and subitems - are not
5.319 -yet modelled in the template.</p>
5.320 +yet modelled in the template. These things will be added to the template as <a href="selectors.html">selectors</a> as part of the next activity in the development <a href="overview.html">process</a>.</p>
5.321 +
5.322 +
5.323 +
5.324 +
5.325 +
5.326
5.327 </body>
5.328 </html>