1.1 --- a/docs/Web-resource.html Mon Oct 03 23:04:48 2005 +0000
1.2 +++ b/docs/Web-resource.html Mon Oct 03 23:05:27 2005 +0000
1.3 @@ -1,23 +1,18 @@
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 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
1.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.9 - <title>Creating Applications: Write a Web Resource</title>
1.10 - <meta name="generator"
1.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.12 - <link href="styles.css" rel="stylesheet" type="text/css" />
1.13 -</head>
1.14 +
1.15 + <title>Creating Applications: Write a Web Resource</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.16 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.17 <body>
1.18 <h1>Creating Applications: Write a Web Resource</h1>
1.19 <p>With a completed template after the <a href="design.html">design</a>,
1.20 -<a href="structure.html">structure annotation</a> and <a
1.21 - href="selectors.html">selector annotation</a>, we may now write a Web
1.22 +<a href="structure.html">structure annotation</a> and <a href="selectors.html">selector annotation</a>, we may now write a Web
1.23 resource which will expose our form as a Web application, allowing
1.24 users to input information and to manipulate that information using
1.25 their Web browser. Whilst XSLForms is just a normal Python package
1.26 which can be used from many kinds of programs and environments, we
1.27 -shall concentrate on using the built-in <a
1.28 - href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>
1.29 +shall concentrate on using the built-in <a href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>
1.30 support to build a
1.31 WebStack application around our form template.</p>
1.32 <h2>XSLForms Meets WebStack </h2>
1.33 @@ -59,12 +54,9 @@
1.34 is automatically produced from the template, we only need to choose a
1.35 name which is not already in use by another file, and for clarity a
1.36 name similar to that of the template is recommended: <code>structure_output.xsl</code></li>
1.37 - </ol>
1.38 - </li>
1.39 -</ul>
1.40 + </ol></li></ul>
1.41 <p>The class also has a method which resembles the typical <code>respond</code>
1.42 -method of normal <a
1.43 - href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>
1.44 +method of normal <a href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>
1.45 resources: the <code>respond_to_form</code> method is, in fact, a
1.46 special version of that method providing ready-to-use information about
1.47 the form (or forms) being edited.</p>
1.48 @@ -139,7 +131,5 @@
1.49 <p>We should now have an application which can be deployed and tested
1.50 using the usual WebStack techniques. However, more advanced templates
1.51 can be designed, and we shall consider <a href="multiple.html">multiple-choice
1.52 -fields</a> in the next activity in the development <a
1.53 - href="overview.html">process</a>.</p>
1.54 -</body>
1.55 -</html>
1.56 +fields</a> in the next activity in the development <a href="overview.html">process</a>.</p>
1.57 +</body></html>
1.58 \ No newline at end of file
2.1 --- a/docs/advice.html Mon Oct 03 23:04:48 2005 +0000
2.2 +++ b/docs/advice.html Mon Oct 03 23:05:27 2005 +0000
2.3 @@ -1,12 +1,10 @@
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 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
2.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
2.9 - <title>Creating Applications: Recommendations and Advice</title>
2.10 - <meta name="generator"
2.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.12 - <link href="styles.css" rel="stylesheet" type="text/css" />
2.13 -</head>
2.14 +
2.15 + <title>Creating Applications: Recommendations and Advice</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.16 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
2.17 +
2.18 <body>
2.19 <h1>Creating Applications: Recommendations and Advice</h1>
2.20 <ol>
2.21 @@ -21,8 +19,7 @@
2.22 vary within your application, and the nested elements will appear
2.23 at a different position depending on how many such values have been
2.24 inserted. Whilst this might not affect some applications, at least not
2.25 -to begin with, the usage of more advanced features (<a
2.26 - href="in-page-updates.html">in-page updates</a>, for example) will
2.27 +to begin with, the usage of more advanced features (<a href="in-page-updates.html">in-page updates</a>, for example) will
2.28 probably expose
2.29 problems due to the way XSLForms reconstructs the XML document data
2.30 from the input form data.</p>
2.31 @@ -54,7 +51,7 @@
2.32 the necessary elements for the output document so that the resulting
2.33 page gives the user the opportunity to specify data that is missing.
2.34 Consider this section of an example template:</p>
2.35 -<pre><p template:element="package"><br /> <p template:element="author"><br /> Name: <input template:attribute="name" name="{template:this-attribute()}" type="text" value="{$this-value}"/><br /> </p><br /></p></pre>
2.36 +<pre><p template:element="package"><br /> <p template:element="author"><br /> Name: <input template:attribute-field="name" name="..." type="text" value="..."/><br /> </p><br /></p></pre>
2.37 <p>Here, if the <code>author</code> element is not found in the
2.38 output structure, no field will be produced in the Web page, no
2.39 opportunity will be given for an author to be specified, and no author
2.40 @@ -62,8 +59,10 @@
2.41 the <code>author</code> element into the XML document when
2.42 creating the <code>package</code> element - this should then
2.43 "bootstrap" the process and ensure that the author details will remain
2.44 -editable as long as the <code>package</code> element exists.</p>
2.45 +editable as long as the <code>package</code> element exists.</p><h3>Ensuring Element Structure with Document Initialisation</h3><p>Although it is not necessary to use <a href="multiple.html">document initialisation</a> in resources, the above case would be detected by an input/initialiser stylesheet, and the <code>package</code> and <code>author</code> elements would be added if no way of adding them was mentioned in the template. Typically, we would employ <a href="selectors.html">selectors</a> to provide the ability to add elements in templates, and the above example could be extended as follows:</p><pre><p template:element="package"><br /> <p template:element="author"><br /> Name: <input template:attribute-field="name" name="..." type="text" value="..."/><br /> </p><br /> <p><br /> <input name="..." template:selector-field="add-author,author" type="submit" value="Add author" /><br /> </p><br /></p></pre><p>With the newly-added selector, we can see that <code>author</code> elements could at least be added by users of the application, but <code>package</code>
2.46 +elements would still be impossible to create in the user interface. The
2.47 +document initialisation mechanism distinguishes between these two cases
2.48 +by looking for selectors which mention element names; here, the <code>template:selector-field</code> attribute has two parts to its value:</p><ol><li>A name used to identify the selector.</li><li>The name of an element: <code>author</code></li></ol><p>Since the <code>author</code> element is mentioned, the mechanism knows not to create such elements automatically. However, since no such selector exists for <code>package</code> elements, those elements are created automatically.</p>
2.49 <ol>
2.50 </ol>
2.51 -</body>
2.52 -</html>
2.53 +</body></html>
2.54 \ No newline at end of file
3.1 --- a/docs/in-page-updates.html Mon Oct 03 23:04:48 2005 +0000
3.2 +++ b/docs/in-page-updates.html Mon Oct 03 23:05:27 2005 +0000
3.3 @@ -1,12 +1,10 @@
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 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
3.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
3.9 - <title>Creating Applications: In-Page Updates</title>
3.10 - <meta name="generator"
3.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.12 - <link href="styles.css" rel="stylesheet" type="text/css" />
3.13 -</head>
3.14 +
3.15 + <title>Creating Applications: In-Page Updates</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.16 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
3.17 +
3.18 <body>
3.19 <h1>Creating Applications: In-Page Updates</h1>
3.20 <p>One fashionable avenue in Web application design has been that of
3.21 @@ -16,33 +14,26 @@
3.22 such "in-page" or "live" updates.</p>
3.23 <p>Consider the addition of a comment field to our application. Here is
3.24 how the HTML code might look:</p>
3.25 -<pre><div template:element="item"><br /> <p><br /> Some item: <input template:attribute="value" name="{template:this-attribute()}" type="text" value="{$this-value}" /><br /> <input name="remove={template:this-element()}" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Item type:<br /> <select template:element="type" name="{template:list-attribute('type-enum', 'value')}" multiple="multiple"><br /> <option template:element="type-enum" template:expr="@value-is-set" template:expr-attr="selected"<br /> template:value="@value" value="{@value}" /><br /> </select><br /> </p><br /> <span
3.26 - style="font-weight: bold;"><p template:element="options"></span><br
3.27 - style="font-weight: bold;" /><span style="font-weight: bold;"> <span </span><span
3.28 - style="font-weight: bold;">template:element="comment"></span><span
3.29 - style="font-weight: bold;">Comment:</span><br
3.30 - style="font-weight: bold;" /><span style="font-weight: bold;"> <textarea template:attribute="value" name="{template:this-attribute()}" cols="40" rows="3"></span><br
3.31 - style="font-weight: bold;" /><span style="font-weight: bold;"> <span template:value="$this-value" template:effect="replace">Some comment</span></span><br
3.32 - style="font-weight: bold;" /><span style="font-weight: bold;"> </textarea><br /> </span><br
3.33 - style="font-weight: bold;" /></span><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="subvalue" name="{template:this-attribute()}" type="text" value="{$this-value}" /><br /> <input name="remove2={template:this-element()}" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="add2={template:this-element()}" type="submit" value="Add subitem" /><br /> </p><br /></div></pre>
3.34 -<p>The newly-added <code>textarea</code> field will not be
3.35 -presented in the application in its current state; this is due to the
3.36 -lack of any <code>options</code> or <code>comment</code> elements
3.37 +<pre><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 /> <p><br /> Item type:<br /> <select template:multiple-choice-list-field="type,type-enum,value" name="..." multiple="multiple"><br /> <option template:multiple-choice-list-value="type-enum,value,selected" value="..." /><br /> </select><br /> </p><br /> <span style="font-weight: bold;"><p template:element="options"></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <span </span><span style="font-weight: bold;">template:element="comment"></span><span style="font-weight: bold;">Comment:</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <textarea template:attribute-area="value,insert" name="..." cols="40" rows="3"></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> Some comment</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> </textarea><br /> </span><br style="font-weight: bold;" /></span><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></pre>
3.38 +<p>Here, a <code>textarea</code> element has been added with a special <code>template:attribute-area</code> annotation being used to state that the contents of the element are to be mapped to the <code>value</code> attribute, and that the attribute contents are to be inserted inside the <code>textarea</code> element (replacing the <code>Some Comment</code> text).</p><p>The newly-added <code>textarea</code> field might actually be
3.39 +presented in the application in its current state, despite the lack of any <code>options</code> or <code>comment</code>
3.40 +elements
3.41 manipulated by the
3.42 -application, and such template changes are actually quite safe to make.
3.43 -So, we must now do some additional work to add such <code>options</code>
3.44 -and <code>comment</code>
3.45 -elements in our application.</p>
3.46 -<p>One approach is to extend our transformation which adds the
3.47 -different type values so that these new elements are
3.48 -introduced as well. In the Web resource, we can make the following
3.49 -change:</p>
3.50 -<pre> transform_resources = {<br /> "types" : ["structure_multivalue_types.xsl", "structure_comments.xsl"]<br /> }</pre>
3.51 -<p>What this does is to state that when we carry out the <code>types</code>
3.52 -transformation, two stylesheets are employed, one before the other,
3.53 -such that the type values are first added using the first stylesheet
3.54 -(and the additional reference document containing the type values) and
3.55 -that the comments are then added using the second stylesheet.</p>
3.56 +application, due to the document initialisation mechanism employed by
3.57 +the application. However, what would be more interesting is the
3.58 +possibility of only showing the comment field if something else in the
3.59 +document had a certain value or state.</p>
3.60 +<p>Let us imagine that if the type of an item was set to "Personal",
3.61 +the comment field would appear and permit the recording of some text
3.62 +for that item. One approach that would make this possible is to
3.63 +add a transformation which checks the type values set for each of the
3.64 +items and removes the <code>options</code> and <code>comment</code> elements for items which do not qualify. In the Web resource, we make the following
3.65 +changes:</p>
3.66 +<pre> transform_resources = {<br /> "comments" : ["structure_comments.xsl"]<br /> }</pre>
3.67 +<p>What this does is to state that when we carry out the <code>comments</code>
3.68 +transformation, the specified stylesheet is employed, filtering out the
3.69 +comments for non-qualifying items and preserving them for qualifying
3.70 +items.</p><p>Further down in the code, we add a transformation:</p><pre> # After the document initialisation...<br /><br /> # Add the comments.<br /><br /> comments_xsl_list = self.prepare_transform("comments")<br /> structure = self.get_result(comments_xsl_list, structure)</pre>
3.71 <p>This new stylesheet works according to the following principles:</p>
3.72 <ol>
3.73 <li>Descend into the form data structure, copying all elements,
3.74 @@ -67,9 +58,8 @@
3.75 </ol>
3.76 </li>
3.77 </ol>
3.78 -<p>Since this stylesheet is used after the type value transformation,
3.79 -we may (and even must) take advantage of the results of that
3.80 -transformation, including noting that selected values on <code>type-enum</code>
3.81 +<p>Since this stylesheet is used after the document initialisation,
3.82 +we may (and even must) take advantage of the results of that activity, including noting that selected values on <code>type-enum</code>
3.83 elements are marked with the <code>value-is-set</code> attribute.</p>
3.84 <p>The stylesheet source code can be found in <code>examples/Common/VerySimple/Resources/structure_comments.xsl</code>.</p>
3.85 <h2>Limitations and Enhancements</h2>
3.86 @@ -90,9 +80,7 @@
3.87 can be added and removed, regardless of whether such a field existed
3.88 there before. The above template code needs modifying slightly to
3.89 permit this:</p>
3.90 -<pre> <span style="font-weight: bold;"><p template:element="options" template:id="comment-node" id="{template:this-element()}"></span><br
3.91 - style="font-weight: bold;" /><span style="font-weight: bold;"> <span template:element="comment"></span>Comment:<br /> <textarea template:attribute="value" name="{template:this-attribute()}" cols="40" rows="3"><br /> <span template:value="$this-value" template:effect="replace">Some comment</span><br /> </textarea><br /> <span
3.92 - style="font-weight: bold;"></span></span><br /> </p></pre>
3.93 +<pre> <span style="font-weight: bold;"><p template:element="options" template:id="comment-node" id="{template:this-element()}"></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <span template:element="comment"></span>Comment:<br /> <textarea template:attribute-area="value,insert" name="..." cols="40" rows="3"><br /> Some comment<br /> </textarea><br /> <span style="font-weight: bold;"></span></span><br /> </p></pre>
3.94 <p>Here, we have added this region definition to the paragraph
3.95 surrounding the comment field, annotating the paragraph with the
3.96 following attributes:</p>
3.97 @@ -119,21 +107,13 @@
3.98 <p>Since we rely on JavaScript support in the browser, the following
3.99 references to scripts must also be added to the template, as shown in
3.100 the following excerpt:</p>
3.101 -<pre><head><br /> <title>Example</title><br /> <span
3.102 - style="font-weight: bold;"><script type="text/javascript" src="scripts/sarissa.js"> </script></span><br
3.103 - style="font-weight: bold;" /><span style="font-weight: bold;"> <script type="text/javascript" src="scripts/XSLForms.js"> </script></span><br /></head></pre>
3.104 +<pre><head><br /> <title>Example</title><br /> <span style="font-weight: bold;"><script type="text/javascript" src="scripts/sarissa.js"> </script></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> <script type="text/javascript" src="scripts/XSLForms.js"> </script></span><br /></head></pre>
3.105 <p>These special script files can be found in <code>examples/Common/VerySimple/Resources/scripts</code>.</p>
3.106 <p>Now we can concentrate on adding the event which triggers an in-page
3.107 update. Since it is the type values that cause each comment field to be
3.108 added or removed, we add an event attribute on the form field
3.109 responsible for displaying the type values:</p>
3.110 -<pre> <p><br /> Item type:<br /> <select template:element="type" name="{template:list-attribute('type-enum', 'value')}" multiple="multiple"<br /> <span
3.111 - style="font-weight: bold;">onchange="requestUpdate(</span><br
3.112 - style="font-weight: bold;" /><span style="font-weight: bold;"> 'comments',</span><br
3.113 - style="font-weight: bold;" /><span style="font-weight: bold;"> '{template:list-attribute('type-enum', 'value')}',</span><br
3.114 - style="font-weight: bold;" /><span style="font-weight: bold;"> '{template:other-elements(../options)}',</span><br
3.115 - style="font-weight: bold;" /><span style="font-weight: bold;"> '{template:child-attribute('value', template:child-element('comment', 1, template:other-elements(../options)))}',</span><br
3.116 - style="font-weight: bold;" /><span style="font-weight: bold;"> '/structure/item/options')"</span>><br /> <option template:element="type-enum" template:expr="@value-is-set" template:expr-attr="selected"<br /> template:value="@value" value="{@value}" /><br /> </select><br /> </p></pre>
3.117 +<pre> <p><br /> Item type:<br /> <select template:multiple-choice-list-field="type,type-enum,value" name="..." multiple="multiple"<br /> <span style="font-weight: bold;">onchange="requestUpdate(</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> 'comments',</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> '{template:list-attribute('type-enum', 'value')}',</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> '{template:other-elements(../options)}',</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> '{template:child-attribute('value', template:child-element('comment', 1, template:other-elements(../options)))}',</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> '/structure/item/options')"</span>><br /> <option template:multiple-choice-list-value="type-enum,value,selected" value="..." /><br /> </select><br /> </p></pre>
3.118 <p>This complicated string calls a special update request JavaScript
3.119 function which triggers the in-page update, and it specifies the
3.120 following things:</p>
3.121 @@ -190,17 +170,10 @@
3.122 pages from our application. Some standard WebStack resources can be
3.123 used to help with this, and we add some imports at the top of our
3.124 source file:</p>
3.125 -<pre>#!/usr/bin/env python<br /><br />"A very simple example application."<br /><br />import WebStack.Generic<br />import XSLForms.Resources<br />import XSLForms.Utils<br />import os<br /><br /><span
3.126 - style="font-weight: bold;"># Site map imports.</span><br
3.127 - style="font-weight: bold;" /><br style="font-weight: bold;" /><span
3.128 - style="font-weight: bold;">from WebStack.Resources.ResourceMap import MapResource</span><br
3.129 - style="font-weight: bold;" /><span style="font-weight: bold;">from WebStack.Resources.Static import DirectoryResource</span></pre>
3.130 +<pre>#!/usr/bin/env python<br /><br />"A very simple example application."<br /><br />import WebStack.Generic<br />import XSLForms.Resources<br />import XSLForms.Utils<br />import os<br /><br /><span style="font-weight: bold;"># Site map imports.</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;">from WebStack.Resources.ResourceMap import MapResource</span><br style="font-weight: bold;" /><span style="font-weight: bold;">from WebStack.Resources.Static import DirectoryResource</span></pre>
3.131 <p>Then, we define the resource class as <a href="Web-resource.html">before</a>,
3.132 but with an additional attribute:</p>
3.133 -<pre># Resource classes.<br /><br />class VerySimpleResource(XSLForms.Resources.XSLFormsResource):<br /><br /> "A very simple resource providing a hierarchy of editable fields."<br /><br /> resource_dir = os.path.join(os.path.split(__file__)[0], "Resources")<br /> encoding = "utf-8"<br /> template_resources = {<br /> "structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl")<br /> }<br /> transform_resources = {<br /> "types" : ["structure_multivalue_types.xsl", "structure_comments.xsl"]<br /> }<br /> document_resources = {<br /> "types" : "structure_types.xml"<br /> }<br /><span
3.134 - style="font-weight: bold;"> in_page_resources = {</span><br
3.135 - style="font-weight: bold;" /><span style="font-weight: bold;"> "comments" : ("structure_output_comments.xsl", "comment-node")</span><br
3.136 - style="font-weight: bold;" /><span style="font-weight: bold;"> }</span></pre>
3.137 +<pre># Resource classes.<br /><br />class VerySimpleResource(XSLForms.Resources.XSLFormsResource):<br /><br /> "A very simple resource providing a hierarchy of editable fields."<br /><br /> resource_dir = os.path.join(os.path.split(__file__)[0], "Resources")<br /> encoding = "utf-8"<br /> template_resources = {<br /> "structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl")<br /> }<br /> init_resources = {<br /> "structure" : ("structure_multivalue_template.xhtml", "structure_input.xsl")<br /> }<br /> transform_resources = {<br /> "comments" : ["structure_comments.xsl"]<br /> }<br /> document_resources = {<br /> "types" : "structure_types.xml"<br /> }<br /><span style="font-weight: bold;"> in_page_resources = {</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> "comments" : ("structure_output_comments.xsl", "comment-node")</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> }</span></pre>
3.138 <p>This new attribute provides information about the in-page request to
3.139 retrieve comment regions of the Web form, and it consists of the
3.140 stylesheet filename that will be generated to produce the page
3.141 @@ -208,31 +181,17 @@
3.142 we defined above.</p>
3.143 <p>The <code>respond_to_form</code> method now also includes some
3.144 additional code:</p>
3.145 -<pre> def respond_to_form(self, trans, form):<br /><br /> """<br /> Respond to a request having the given transaction 'trans' and the given<br /> 'form' information.<br /> """<br /><br /> <span
3.146 - style="font-weight: bold;">in_page_resource = self.get_in_page_resource(trans)</span><br
3.147 - style="font-weight: bold;" /><span style="font-weight: bold;"> parameters = form.get_parameters()</span><br /> documents = form.get_documents()<br /></pre>
3.148 +<pre> def respond_to_form(self, trans, form):<br /><br /> """<br /> Respond to a request having the given transaction 'trans' and the given<br /> 'form' information.<br /> """<br /><br /> <span style="font-weight: bold;">in_page_resource = self.get_in_page_resource(trans)</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> parameters = form.get_parameters()</span><br /> documents = form.get_documents()<br /></pre>
3.149 <p>Here, we find out whether an in-page update is requested, along with
3.150 the raw parameters of the request, some of which will be used later on
3.151 in the method.</p>
3.152 <p>The discovery of the form data structure and the addition and
3.153 removal of elements happens as before, as does the merging of type
3.154 values and the comment field, if applicable:</p>
3.155 -<pre> # Ensure the presence of a document.<br /><br /> if documents.has_key("structure"):<br /> structure = documents["structure"]<br /> else:<br /> structure = form.new_instance("structure")<br /><br /> # Add and remove elements according to the selectors found.<br /><br /> selectors = form.get_selectors()<br /> XSLForms.Utils.remove_elements(selectors.get("remove2"))<br /> XSLForms.Utils.add_elements(selectors.get("add2"), "subitem")<br /> XSLForms.Utils.remove_elements(selectors.get("remove"))<br /> XSLForms.Utils.add_elements(selectors.get("add"), "item")<br /><br /> # Transform, adding enumerations/ranges.<br /><br /> types_xsl_list = self.prepare_transform("types")<br /> types_xml = self.prepare_document("types")<br /> structure = self.get_result(types_xsl_list, structure, references={"types" : types_xml})</pre>
3.156 +<pre> # Ensure the presence of a document.<br /><br /> if documents.has_key("structure"):<br /> structure = documents["structure"]<br /> else:<br /> structure = form.new_instance("structure")<br /><br /> # Add and remove elements according to the selectors found.<br /><br /> selectors = form.get_selectors()<br /> XSLForms.Utils.remove_elements(selectors.get("remove2"))<br /> XSLForms.Utils.add_elements(selectors.get("add2"), "subitem")<br /> XSLForms.Utils.remove_elements(selectors.get("remove"))<br /> XSLForms.Utils.add_elements(selectors.get("add"), "item")<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 /> # Add the comments.<br /><br /> comments_xsl_list = self.prepare_transform("comments")<br /> structure = self.get_result(comments_xsl_list, structure)<br /></pre>
3.157 <p>The significant changes begin when presenting the result of the
3.158 request processing:</p>
3.159 -<pre> # Start the response.<br /><br /> trans.set_content_type(WebStack.Generic.ContentType("application/xhtml+xml", self.encoding))<br /><br /><span
3.160 - style="font-weight: bold;"> # Define the stylesheet parameters.</span><br
3.161 - style="font-weight: bold;" /><br style="font-weight: bold;" /><span
3.162 - style="font-weight: bold;"> stylesheet_parameters = {}</span><br
3.163 - style="font-weight: bold;" /><br style="font-weight: bold;" /><span
3.164 - style="font-weight: bold;"> # Ensure that an output stylesheet exists.</span><br
3.165 - style="font-weight: bold;" /><br style="font-weight: bold;" /><span
3.166 - style="font-weight: bold;"> if in_page_resource in self.in_page_resources.keys():</span><br
3.167 - style="font-weight: bold;" /><span style="font-weight: bold;"> trans_xsl = self.prepare_fragment("structure", in_page_resource)</span><br
3.168 - style="font-weight: bold;" /><span style="font-weight: bold;"> element_path = parameters.get("element-path", [""])[0]</span><br
3.169 - style="font-weight: bold;" /><span style="font-weight: bold;"> stylesheet_parameters["element-path"] = element_path</span><br
3.170 - style="font-weight: bold;" /><span style="font-weight: bold;"> else:</span><br
3.171 - style="font-weight: bold;" /><span style="font-weight: bold;"> trans_xsl = self.prepare_output("structure")</span></pre>
3.172 +<pre> # Start the response.<br /><br /> trans.set_content_type(WebStack.Generic.ContentType("application/xhtml+xml", self.encoding))<br /><br /><span style="font-weight: bold;"> # Define the stylesheet parameters.</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> stylesheet_parameters = {}</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> # Ensure that an output stylesheet exists.</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> if in_page_resource in self.in_page_resources.keys():</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> trans_xsl = self.prepare_fragment("structure", in_page_resource)</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> element_path = parameters.get("element-path", [""])[0]</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> stylesheet_parameters["element-path"] = element_path</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> else:</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> trans_xsl = self.prepare_output("structure")</span></pre>
3.173 <p>Instead of just obtaining a stylesheet for the <code>structure</code>
3.174 document, we instead check to see if an in-page update is being
3.175 requested and, if so, prepare the stylesheet representing the fragment
3.176 @@ -242,33 +201,12 @@
3.177 stylesheet when making the final Web page output.</p>
3.178 <p>Finally, we send the output to the user but employing the additional
3.179 stylesheet parameters to configure the result:</p>
3.180 -<pre><span style="font-weight: bold;" /> # Complete the response.<br /><br /> self.send_output(trans, [trans_xsl], structure<span
3.181 - style="font-weight: bold;">, stylesheet_parameters</span>)</pre>
3.182 +<pre><span style="font-weight: bold;"> # Complete the response.<br /><br /> self.send_output(trans, [trans_xsl], structure<span style="font-weight: bold;">, stylesheet_parameters</span>)</span></pre>
3.183 <p>In order to introduce the infrastructure mentioned above which
3.184 separates requests for Web pages from requests for JavaScript files, we
3.185 need to provide a more sophisticated implementation of the <code>get_site</code>
3.186 function:</p>
3.187 -<pre><span style="font-weight: bold;"># Site map initialisation.</span><br
3.188 - style="font-weight: bold;" /><br style="font-weight: bold;" /><span
3.189 - style="font-weight: bold;">def get_site():</span><br
3.190 - style="font-weight: bold;" /><br style="font-weight: bold;" /><span
3.191 - style="font-weight: bold;"> "Return a simple Web site resource."</span><br
3.192 - style="font-weight: bold;" /><br style="font-weight: bold;" /><span
3.193 - style="font-weight: bold;"> # Get the main resource and the directory used by the application.</span><br
3.194 - style="font-weight: bold;" /><br style="font-weight: bold;" /><span
3.195 - style="font-weight: bold;"> very_simple_resource = VerySimpleResource()</span><br
3.196 - style="font-weight: bold;" /><span style="font-weight: bold;"> directory = very_simple_resource.resource_dir</span><br
3.197 - style="font-weight: bold;" /><br style="font-weight: bold;" /><span
3.198 - style="font-weight: bold;"> # Make a simple Web site.</span><br
3.199 - style="font-weight: bold;" /><br style="font-weight: bold;" /><span
3.200 - style="font-weight: bold;"> resource = MapResource({</span><br
3.201 - style="font-weight: bold;" /><span style="font-weight: bold;"> # Static resources:</span><br
3.202 - style="font-weight: bold;" /><span style="font-weight: bold;"> "scripts" : DirectoryResource(os.path.join(directory, "scripts"), {"js" : "text/javascript"}),</span><br
3.203 - style="font-weight: bold;" /><span style="font-weight: bold;"> # Main page and in-page resources:</span><br
3.204 - style="font-weight: bold;" /><span style="font-weight: bold;"> None : very_simple_resource</span><br
3.205 - style="font-weight: bold;" /><span style="font-weight: bold;"> })</span><br
3.206 - style="font-weight: bold;" /><br style="font-weight: bold;" /><span
3.207 - style="font-weight: bold;"> return resource</span></pre>
3.208 +<pre><span style="font-weight: bold;"># Site map initialisation.</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;">def get_site():</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> "Return a simple Web site resource."</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> # Get the main resource and the directory used by the application.</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> very_simple_resource = VerySimpleResource()</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> directory = very_simple_resource.resource_dir</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> # Make a simple Web site.</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> resource = MapResource({</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> # Static resources:</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> "scripts" : DirectoryResource(os.path.join(directory, "scripts"), {"js" : "text/javascript"}),</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> # Main page and in-page resources:</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> None : very_simple_resource</span><br style="font-weight: bold;" /><span style="font-weight: bold;"> })</span><br style="font-weight: bold;" /><br style="font-weight: bold;" /><span style="font-weight: bold;"> return resource</span></pre>
3.209 <p>What this does is to create a resource for the application, as
3.210 before, but then to place the resource into a special WebStack resource
3.211 which examines the path or URL on the incoming requests and directs
3.212 @@ -285,5 +223,4 @@
3.213 script file; otherwise it gets a Web page showing either all of the
3.214 form (if a normal request is received), or a part of the form (if an
3.215 in-page request is received).</p>
3.216 -</body>
3.217 -</html>
3.218 +</body></html>
3.219 \ No newline at end of file
4.1 --- a/docs/multiple.html Mon Oct 03 23:04:48 2005 +0000
4.2 +++ b/docs/multiple.html Mon Oct 03 23:05:27 2005 +0000
4.3 @@ -1,12 +1,9 @@
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 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
4.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
4.9 - <title>Creating Applications: Adding Multiple-Choice Fields and Values</title>
4.10 - <meta name="generator"
4.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.12 - <link href="styles.css" rel="stylesheet" type="text/css" />
4.13 -</head>
4.14 +
4.15 + <title>Creating Applications: Adding Multiple-Choice Fields and Values</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.16 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
4.17 <body>
4.18 <h1>Creating Applications: Adding Multiple-Choice Fields and Values</h1>
4.19 <p>Up to this point, we have only considered two kinds of Web form
4.20 @@ -22,33 +19,18 @@
4.21 or many values presented in a list or menu, we shall first consider the
4.22 case where only a single value can be chosen from such a selection.</p>
4.23 <form method="post" action="" name="single">
4.24 - <p>Some item: <input name="value" value="some value" /><input
4.25 - name="remove" value="Remove" type="submit" /></p>
4.26 + <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
4.27 <p>Item type:
4.28 - <select name="type">
4.29 - <option>(Not selected)</option>
4.30 - <option>Important</option>
4.31 - <option>Not important</option>
4.32 - <option>Personal</option>
4.33 - </select>
4.34 + <select name="type"><option>(Not selected)</option><option>Important</option><option>Not important</option><option>Personal</option></select>
4.35 </p>
4.36 <p>Itself containing more items:</p>
4.37 - <p>Sub-item: <input name="subvalue" value="some other value" /><input
4.38 - name="remove2" value="Remove" type="submit" /></p>
4.39 + <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p>
4.40 </form>
4.41 From the item type list only one value may be selected.
4.42 <p>Taking the example HTML code from before, we can add a
4.43 definition of this new list to the template to produce something
4.44 like this:</p>
4.45 -<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="value" name="{template:this-attribute()}" type="text" value="{$this-value}" /><br /> <input name="remove={template:this-element()}" type="submit" value="Remove" /><br /> </p><br /> <span
4.46 - style="font-weight: bold;"><p></span><br
4.47 - style="font-weight: bold;" /><span style="font-weight: bold;"> Item type:</span><br
4.48 - style="font-weight: bold;" /><span style="font-weight: bold;"> <select template:element="type" name="{template:new-attribute('value')}"></span><br
4.49 - style="font-weight: bold;" /><span style="font-weight: bold;"> <option template:element="type-enum" template:expr="@value = ../@value" template:expr-attr="selected"</span><br
4.50 - style="font-weight: bold;" /><span style="font-weight: bold;"> template:value="@value" value="{@value}" /></span><br
4.51 - style="font-weight: bold;" /><span style="font-weight: bold;"> </select></span><br
4.52 - 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="subvalue" name="{template:this-attribute()}" type="text" value="{$this-value}" /><br /> <input name="remove2={template:this-element()}" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="add2={template:this-element()}" type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="add={template:this-element()}" type="submit" value="Add item" /><br /></p><span
4.53 - style="font-weight: bold;"><br /><br /></span><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
4.54 +<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>
4.55 <p>There are a lot of details here that need to be explained. Here is
4.56 what was done:</p>
4.57 <ol>
4.58 @@ -57,15 +39,11 @@
4.59 <li>Inside the paragraph, next to the label text, an HTML <code>select</code>
4.60 element was added.</li>
4.61 <li>The <code>select</code> element is mapped onto the <code>type</code>
4.62 -element in the form data structure. However, HTML fields must produce
4.63 -values and it makes no sense to interpret a textual value as an
4.64 -element. Therefore, we indicate in the name of the <code>select</code>
4.65 -element that the value submitted maps onto the <code>value</code>
4.66 -attribute of the <code>type</code> element in the form data
4.67 -structure.</li>
4.68 +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>
4.69 +element will contain any chosen value from the list of values displayed in the page.</li>
4.70 <li>Inside the <code>select</code> element, we include an <code>option</code>
4.71 element which defines the values which will be presented to users
4.72 -of the form. Note that the <code>option</code> element maps onto
4.73 +of the form. Here, the special <code>template:multiple-choice-value</code> attribute indicates that the <code>option</code> element maps onto
4.74 a <code>type-enum</code> element which is not mentioned in our
4.75 revised form data structure above; this will be discussed below.</li>
4.76 </ol>
4.77 @@ -83,28 +61,17 @@
4.78 using a number of special annotations which make more sense when
4.79 considering the above output structure:</p>
4.80 <ul>
4.81 - <li>The <code>template:element</code> annotation states that the
4.82 + <li>The <code>template:multiple-choice-value</code> annotation states that the
4.83 <code>option</code> element maps into the <code>type-enum</code>
4.84 element, meaning that each <code>type-enum</code> element will be
4.85 reproduced as an option inside the list or menu presented in the Web
4.86 form.</li>
4.87 - <li>The <code>template:value</code> annotation states that the
4.88 + <li>The <code>template:multiple-choice-value</code> annotation also states that the
4.89 contents of the <code>option</code> element will correspond to
4.90 the value of the <code>type-enum</code> element's <code>value</code>
4.91 -attribute - the notation employed here actually belongs to XSL.</li>
4.92 - <li>The <code>template:expr</code> and <code>template:expr-attr</code>
4.93 -annotations work together and state that...<br />
4.94 - <ol>
4.95 - <li>When the expression in <code>template:expr</code> is true...</li>
4.96 - <li>The attribute in <code>template:expr-attr</code> will be
4.97 -added to the <code>option</code> element with a value identical to its
4.98 -name.</li>
4.99 - </ol>
4.100 - </li>
4.101 - <li>The <code>value</code> attribute is defined to reproduce
4.102 -the <code>value</code> attribute from the <code>type-enum</code>
4.103 -element - the notation employed here belongs, once again, to XSL.</li>
4.104 -</ul>
4.105 +attribute.</li>
4.106 + <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.
4.107 + </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>
4.108 <p>The result of this is that the <code>type</code> element in the
4.109 this example structure fragment...</p>
4.110 <pre><type value="2"><br /> <type-enum value="1"/><br /> <type-enum value="2"/><br /> <type-enum value="3"/><br /></type></pre>
4.111 @@ -118,70 +85,41 @@
4.112 will
4.113 need to find a way of merging the range of allowed values into the
4.114 user-edited form data before presenting that data using our template.</p>
4.115 -<h2>Merging Values into the Form Data</h2>
4.116 +<h2>Document Initialisation</h2>
4.117 <p>There are many possible ways of inserting extra XML elements into an
4.118 -existing XML document, but we shall concentrate on using an XSL
4.119 -stylesheet to perform this merge operation. First, let us define a
4.120 +existing XML document, but XSLForms provides an easy way of defining
4.121 +lists of values that will be included in the way we desire. First, let
4.122 +us define a
4.123 document containing all the possible values for the type field:</p>
4.124 -<pre><?xml version="1.0"?><br /><types><br /> <type-enum value="(Not selected)"/><br /> <type-enum value="Important"/><br /> <type-enum value="Not important"/><br /> <type-enum value="Personal"/><br /></types></pre>
4.125 +<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>
4.126 <p>We shall refer to this document when inserting the different <code>type-enum</code>
4.127 elements into our input form data structure to produce the output
4.128 -structure described above. The stylesheet which performs this task is
4.129 -quite scary for those not familiar with XSL, but it works on the
4.130 -following principles:</p>
4.131 -<ol>
4.132 - <li>Descend into the form data structure, copying all elements,
4.133 -attributes and text that the stylesheet is not programmed to recognise.</li>
4.134 - <li>When encountering an <code>item</code> element (which the
4.135 -stylesheet is programmed to recognise), do the following:<br />
4.136 - <ol>
4.137 - <li>Copy the element "skeleton" and its attributes so that
4.138 -the <code>value</code> attribute is retained.</li>
4.139 - <li>Make a <code>type</code> element inside the <code>item</code>
4.140 -element and process it.</li>
4.141 - </ol>
4.142 - </li>
4.143 - <li>When processing a new <code>type</code> element, do the
4.144 -following:<br />
4.145 - <ol>
4.146 - <li>Copy the attributes of any existing <code>type</code>
4.147 -element so that
4.148 -the <code>value</code> attribute is retained.</li>
4.149 - <li>Add the <code>type-enum</code> elements from the
4.150 -document defined above.</li>
4.151 - </ol>
4.152 - </li>
4.153 -</ol>
4.154 -<p>The stylesheet source code can be found in <code>examples/Common/VerySimple/Resources/structure_types.xsl</code>,
4.155 -whereas the document defined above which contains the values can be
4.156 +structure described above; it can be
4.157 found in <code>examples/Common/VerySimple/Resources/structure_types.xml</code>.</p>
4.158 -<h3>Performing the Merge</h3>
4.159 -<p>To take advantage of these new documents, it is necessary to
4.160 -introduce some code into the Web resource to perform the merge
4.161 -operation. The special WebStack resource that we <a
4.162 - href="Web-resource.html">subclassed earlier</a> provides some
4.163 -convenient mechanisms for introducing XSL-based transformations, and we
4.164 +<h3>Amending the Resource</h3>
4.165 +<p>To take advantage of this new information, it is necessary to
4.166 +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
4.167 +convenient mechanisms for introducing XML documents and initialisations, and we
4.168 shall add a few extra attributes to our resource class in order to take
4.169 advantage of them:</p>
4.170 -<pre> # Under template_resources...<br /><br /> transform_resources = {<br /> "types" : ["structure_types.xsl"]<br /> }<br /> document_resources = {<br /> "types" : "structure_types.xml"<br /> }</pre>
4.171 +<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>
4.172 <p>These attributes define the following things:</p>
4.173 <ol>
4.174 - <li>A transformation called <code>types</code> which uses
4.175 -the <code>structure_types.xsl</code> stylesheet file.</li>
4.176 + <li>A initialisation called <code>structure</code> which links
4.177 +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>
4.178 <li>A document referred to by the name <code>types</code> which
4.179 is provided by the <code>structure_types.xml</code> file.</li>
4.180 </ol>
4.181 -<p>To actually perform the merge operation, we need to add a few extra
4.182 +<p>To actually perform the initalisation or merge operation, we need to add a few extra
4.183 lines of code after the addition and deletion operations in the <code>respond_to_form</code>
4.184 method:</p>
4.185 -<pre> # Under the addition and deletion operations...<br /><br /> # Transform, adding enumerations/ranges.<br /><br /> types_xsl_list = self.prepare_transform("types")<br /> types_xml = self.prepare_document("types")<br /> structure = self.get_result(types_xsl_list, structure, references={"types" : types_xml})<br /><br /> # Start the response.</pre>
4.186 +<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>
4.187 <p>These lines do the following things:</p>
4.188 <ol>
4.189 - <li>Obtain the stylesheets for the <code>types</code>
4.190 -transformation.</li>
4.191 + <li>Obtain the stylesheet for the <code>structure</code> initialisation.</li>
4.192 <li>Obtain the <code>types</code> document containing the
4.193 values to be merged into the form data.</li>
4.194 - <li>Take the stylesheets and apply them to the form data, <code>structure</code>,
4.195 + <li>Take the stylesheet and apply it to the form data, <code>structure</code>,
4.196 using a reference to the <code>types</code> document containing
4.197 the values.</li>
4.198 </ol>
4.199 @@ -190,9 +128,7 @@
4.200 element in that document.</p>
4.201 <h2>Other Multiple-Choice Data</h2>
4.202 <p>We have now added a simple, single-valued multiple-choice field to
4.203 -the application. However, many applications often need to obtain <a
4.204 - href="multivalue.html">multivalued multiple-choice data</a>, and this
4.205 +the application. However, many applications often need to obtain <a href="multivalue.html">multivalued multiple-choice data</a>, and this
4.206 kind of information is investigated in the next part of the development
4.207 <a href="overview.html">process</a>.</p>
4.208 -</body>
4.209 -</html>
4.210 +</body></html>
4.211 \ No newline at end of file
5.1 --- a/docs/multivalue.html Mon Oct 03 23:04:48 2005 +0000
5.2 +++ b/docs/multivalue.html Mon Oct 03 23:05:27 2005 +0000
5.3 @@ -1,12 +1,10 @@
5.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5.5 -<html xmlns="http://www.w3.org/1999/xhtml">
5.6 -<head>
5.7 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
5.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
5.9 - <title>Creating Applications: Adding Multivalued Fields</title>
5.10 - <meta name="generator"
5.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
5.12 - <link href="styles.css" rel="stylesheet" type="text/css" />
5.13 -</head>
5.14 +
5.15 + <title>Creating Applications: Adding Multivalued Fields</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
5.16 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
5.17 +
5.18 <body>
5.19 <h1>Creating Applications: Adding Multivalued Fields</h1>
5.20 <p>Although some applications only require multiple-choice fields where
5.21 @@ -26,49 +24,32 @@
5.22 users to select one
5.23 or many values presented in a list or menu.</p>
5.24 <form method="post" action="" name="single">
5.25 - <p>Some item: <input name="value" value="some value" /><input
5.26 - name="remove" value="Remove" type="submit" /></p>
5.27 + <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
5.28 <p>Item type:
5.29 - <select multiple="multiple" name="type">
5.30 - <option>(Not selected)</option>
5.31 - <option>Important</option>
5.32 - <option>Not important</option>
5.33 - <option>Personal</option>
5.34 - </select>
5.35 + <select multiple="multiple" name="type"><option>(Not selected)</option><option>Important</option><option>Not important</option><option>Personal</option></select>
5.36 </p>
5.37 <p>Itself containing more items:</p>
5.38 - <p>Sub-item: <input name="subvalue" value="some other value" /><input
5.39 - name="remove2" value="Remove" type="submit" /></p>
5.40 + <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p>
5.41 </form>
5.42 From the item type list many value may now be selected.
5.43 <p>Taking the example HTML code from before, we can add a
5.44 definition of this new list to the template to produce something
5.45 like this:</p>
5.46 -<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="value" name="{template:this-attribute()}" type="text" value="{$this-value}" /><br /> <input name="remove={template:this-element()}" type="submit" value="Remove" /><br /> </p><br /> <span
5.47 - style="font-weight: bold;"><p></span><br /> Item type:<br /> <select template:element="type" name="<span
5.48 - style="font-weight: bold;">{template:list-attribute('type-enum', 'value')}</span>" <span
5.49 - style="font-weight: bold;">multiple="multiple"</span>><br /> <option template:element="type-enum" template:expr="<span
5.50 - style="font-weight: bold;">@value-is-set</span>" template:expr-attr="selected"<br /> template:value="@value" value="{@value}" /><br /> </select><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:this-attribute()}" type="text" value="{$this-value}" /><br /> <input name="remove2={template:this-element()}" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="add2={template:this-element()}" type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="add={template:this-element()}" type="submit" value="Add item" /><br /></p><span
5.51 - style="font-weight: bold;"><br /><br /></span><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
5.52 +<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 /> <p><br /> Item type:<br /> <select name="..." <span style="font-weight: bold;">template:multiple-choice-list-field="type,type-enum,value"</span> <span style="font-weight: bold;">multiple="multiple"</span>><br /> <option <span style="font-weight: bold;"><span style="font-family: monospace;">template:multiple-choice-list-value="type-enum,value,selected"</span></span> value="..." /><br /> </select><br /> </p><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>
5.53 <p>From the previous <a href="multiple.html">single-valued case</a>,
5.54 some crucial changes have been made:</p>
5.55 <ol>
5.56 <li>The <code>select</code> element remains mapped onto the <code>type</code>
5.57 -element in the form data structure. However, we indicate in the name of
5.58 -the <code>select</code>
5.59 -element that the value submitted maps onto a special kind of attribute.
5.60 -Instead of mapping onto a single attribute on a single element, the
5.61 -value maps onto a single attribute on a single element <span
5.62 - style="font-style: italic;">for each value submitted</span>. So for
5.63 -each value selected in the list or menu, a <code>type-enum</code>
5.64 -element is created (inside the <code>type</code> element) with a <code>value</code>
5.65 -attribute containing that value.</li>
5.66 +element in the form data structure. However, we use a different attribute, <code>template:multiple-choice-list-field</code>, to indicate that a <code>type</code>
5.67 +element is created when the form data is submitted, but instead of a single value being added to the <code>value</code> attribute of that one element, a separate <code>type-enum</code>
5.68 +element is created within the <code>type</code>
5.69 +element with a value in its <code>value</code> attribute <span style="font-style: italic;">for each value submitted</span>. This means that many <code>type-enum</code>
5.70 +elements may be created within the <code>type</code>
5.71 +element, and each one of them will have a different <code>value</code> attribute.</li>
5.72 <li>Of course, the <code>select</code> element now has a <code>multiple</code>
5.73 attribute defined to permit multiple value selections.</li>
5.74 <li>Inside the <code>select</code> element, the <code>option</code>
5.75 -element mapping onto
5.76 -a <code>type-enum</code> element using a different <code>template:expr</code>
5.77 -condition than was used before.</li>
5.78 +element now employs the <code>template:multiple-choice-list-value</code> annotation.</li>
5.79 </ol>
5.80 <h2>Output Structures</h2>
5.81 <p>Unlike in the single-valued case, the revised the form data
5.82 @@ -89,73 +70,17 @@
5.83 <pre><type><br /> <type-enum value="1"/><br /> <type-enum value="2" value-is-set="true"/><br /> <type-enum value="3" value-is-set="true"/><br /></type><br /></pre>
5.84 <p>...is transformed into something resembling this HTML code:</p>
5.85 <pre><select name="..." multiple="multiple"><br /> <option value="1">1</option><br /> <option value="2" selected="selected">2</option><br /> <option value="3" selected="selected">3</option><br /></select><br /></pre>
5.86 -<p>One principal issue arises when considering the above
5.87 -transformation: where does the special <code>value-is-set</code>
5.88 -attribute
5.89 -come from?</p>
5.90 +<p>Above, the special <code>value-is-set</code>
5.91 +attribute is an XSLForms mechanism to remember which values were set.
5.92 +Fortunately, the document initialisation mechanism automatically
5.93 +distinguishes between different multiple-choice field types and
5.94 +understands where the above approach needs to be employed.</p>
5.95 <ul>
5.96 -</ul>
5.97 -Here, we have to do two things: to include the full range of possible
5.98 -values so that the user may select from that range, and yet we must
5.99 -remember which values were previously selected. If we just merged
5.100 -the <code>type-enum</code> elements into the <code>type</code>
5.101 -element, we would lose track of which values were selected. Therefore,
5.102 -we need to employ a different strategy in remembering those values than
5.103 -that of assuming that those <code>type-enum</code> elements which
5.104 -are present are those which are selected.
5.105 -<h2>Merging and Collecting Values</h2>
5.106 -<p>As in the single-valued case, we need to insert the permitted values
5.107 -into the form data so that the template may visit the <code>type-enum</code>
5.108 -elements and extract those values. However, we have now introduced
5.109 -another task to this activity: to mark the selected values in the
5.110 -entire list of <code>type-enum</code> elements in order to
5.111 -distinguish them from the values which are not selected. In other
5.112 -words, we want to turn
5.113 -something like this...</p>
5.114 -<pre><type><br /> <type-enum value="2"/><br /> <type-enum value="3"/><br /></type><br /></pre>
5.115 -<p>...into something like this:</p>
5.116 -<pre><type><br /> <type-enum value="1"/><br /> <type-enum value="2" value-is-set="true"/><br /> <type-enum value="3" value-is-set="true"/><br /></type><br /></pre>
5.117 -Using the same document containing all the permitted values as our
5.118 -source of information to be merged into the form data, we can now
5.119 -develop a stylesheet which performs the above transformation; this
5.120 -stylesheet needs to work on the
5.121 -following principles:
5.122 -<ol>
5.123 - <li>Descend into the form data structure, copying all elements,
5.124 -attributes and text that the stylesheet is not programmed to recognise.</li>
5.125 - <li>When encountering an <code>item</code> element (which the
5.126 -stylesheet is programmed to recognise), do the following:<br />
5.127 - <ol>
5.128 - <li>Copy the element "skeleton" and its attributes so that
5.129 -the <code>value</code> attribute is retained.</li>
5.130 - <li>Produce a new <code>type</code> element and process it.</li>
5.131 - </ol>
5.132 - </li>
5.133 - <li>When processing a new <code>type</code> element, do the
5.134 -following:<br />
5.135 - <ol>
5.136 - <li>Inside this new <code>type</code> element, add the <code>type-enum</code>
5.137 -elements from the
5.138 -values document, and if any <code>type-enum</code>
5.139 -elements were found within an existing <code>type</code> element from
5.140 -the form data, specify
5.141 -these for the activity.</li>
5.142 - </ol>
5.143 - </li>
5.144 - <li>When adding the <code>type-enum</code> elements, if any of
5.145 -them have a <code>value</code> attribute which matches any of the <code>value</code>
5.146 -attributes of the found <code>type-enum</code> elements, set the
5.147 -special <code>value-is-set</code> attribute on that <code>type-enum</code>
5.148 -element.</li>
5.149 -</ol>
5.150 -<p>The stylesheet source code can be found in <code>examples/Common/VerySimple/Resources/structure_multivalue_types.xsl</code>,
5.151 -whereas the document defined above which contains the values can be
5.152 -found in <code>examples/Common/VerySimple/Resources/structure_types.xml</code>.</p>
5.153 -<h3>Updating the Web Resource</h3>
5.154 +</ul><h3>Updating the Web Resource</h3>
5.155 <p>To update the special WebStack resource, we
5.156 now need to modify a few of the class attributes and to add a few
5.157 others:</p>
5.158 -<pre> template_resources = {<br /> "structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl")<br /> }<br /> transform_resources = {<br /> "types" : ["structure_multivalue_types.xsl"]<br /> }<br /></pre>
5.159 +<pre> template_resources = {<br /> "structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl")<br /> }<br /></pre>
5.160 <p>With these adjustments, it should now be possible to manipulate the
5.161 items and subitems whilst specifying multiple type values on each item.
5.162 Note that it may be necessary to remove the old stylesheet for
5.163 @@ -165,5 +90,4 @@
5.164 <p>Now that we have designed and implemented a simple application, it
5.165 may be worth reading some <a href="advice.html">recommendations</a>
5.166 about developing your own applications.</p>
5.167 -</body>
5.168 -</html>
5.169 +</body></html>
5.170 \ No newline at end of file
6.1 --- a/docs/selectors.html Mon Oct 03 23:04:48 2005 +0000
6.2 +++ b/docs/selectors.html Mon Oct 03 23:05:27 2005 +0000
6.3 @@ -1,12 +1,9 @@
6.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6.5 -<html xmlns="http://www.w3.org/1999/xhtml">
6.6 -<head>
6.7 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
6.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
6.9 - <title>Creating Applications: Add Selectors</title>
6.10 - <meta name="generator"
6.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
6.12 - <link href="styles.css" rel="stylesheet" type="text/css" />
6.13 -</head>
6.14 +
6.15 + <title>Creating Applications: Add Selectors</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
6.16 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
6.17 <body>
6.18 <h1>Creating Applications: Add Selectors</h1>
6.19 <p>In the previous activity we annotated the template
6.20 @@ -29,23 +26,19 @@
6.21 <p>Taking the example HTML code from before, we add some of these
6.22 selector annotations to the template to produce something
6.23 like this:</p>
6.24 -<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="value" name="{template:this-attribute()}" type="text" value="{$this-value}" /><br /> <input name="<span
6.25 - style="font-weight: bold;">remove={template:this-element()}</span>" 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:this-attribute()}" type="text" value="{$this-value}" /><br /> <input name="<span
6.26 - style="font-weight: bold;">remove2={template:this-element()}</span>" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="<span
6.27 - style="font-weight: bold;">add2={template:this-element()}</span>" type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="<span
6.28 - style="font-weight: bold;">add={template:this-element()}</span>" type="submit" value="Add item" /><br /></p><span
6.29 - style="font-weight: bold;" /><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
6.30 +<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="..." <span style="font-weight: bold;">template:selector-field="remove"</span> 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:this-attribute()}" type="text" value="{$this-value}" /><br /> <input name="..." <span style="font-weight: bold;">template:selector-field="remove2"</span> type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="..." <span style="font-weight: bold;">template:selector-field="add2,subitem"</span> type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="..." <span style="font-weight: bold;">template:selector-field="add,item"</span> type="submit" value="Add item" /><br /></p><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
6.31 <h3>The Remove Buttons</h3>
6.32 <p>Some of the attributes in the previous HTML code have been
6.33 changed:</p>
6.34 <ul>
6.35 <li>The <code>input</code> element for the
6.36 -first <code>Remove</code> button has a modified <code>name</code>
6.37 -attribute,
6.38 -containing a special value.</li>
6.39 +first <code>Remove</code> button has a new <code>template:selector-field</code> attribute (and a modified <code>name</code>
6.40 +attribute
6.41 +containing a value that will be replaced).</li>
6.42 <li>The <code>input</code> element for the second <code>Remove</code>
6.43 -button has a modified <code>name</code>
6.44 -attribute, containing a special value.</li>
6.45 +button has a new <code>template:selector-field</code> attribute (and a modified <code>name</code>
6.46 +attribute
6.47 +containing a value that will be replaced).</li>
6.48 </ul>
6.49 <p>What these amendments provide is a means for the XSLForms
6.50 framework
6.51 @@ -69,12 +62,13 @@
6.52 code:</p>
6.53 <ul>
6.54 <li>The <code>input</code> element for the
6.55 -first <code>Add</code> button has a modified <code>name</code>
6.56 -attribute,
6.57 -containing a special value.</li>
6.58 +first <code>Add</code> button has a new <code>template:selector-field</code> attribute (and a modified <code>name</code>
6.59 +attribute
6.60 +containing a value that will be replaced).</li>
6.61 <li>The <code>input</code> element for the second <code>Add</code>
6.62 -button has a modified <code>name</code>
6.63 -attribute, containing a special value.</li>
6.64 +button has a new <code>template:selector-field</code> attribute (and a modified <code>name</code>
6.65 +attribute
6.66 +containing a value that will be replaced).</li>
6.67 </ul>
6.68 <ul>
6.69 </ul>
6.70 @@ -100,11 +94,8 @@
6.71 </ul>
6.72 <p>We define the names of the selectors in the above cases to be <code>add2</code>
6.73 and <code>add</code> respectively, since the special values begin with
6.74 -these identifiers.</p>
6.75 +these identifiers. Moreover, we mention that the selectors are intended to add <code>subitem</code> and <code>item</code> elements respectively - this has certain implications for the behaviour of the application that will be <a href="advice.html">considered later</a>.</p>
6.76 <p>We should now have a template that is sufficiently complete to be
6.77 -used in a real application, and the writing of the <a
6.78 - href="Web-resource.html">application code</a> itself will be
6.79 -investigated in the next activity in the development <a
6.80 - href="overview.html">process</a>.</p>
6.81 -</body>
6.82 -</html>
6.83 +used in a real application, and the writing of the <a href="Web-resource.html">application code</a> itself will be
6.84 +investigated in the next activity in the development <a href="overview.html">process</a>.</p>
6.85 +</body></html>
6.86 \ No newline at end of file
7.1 --- a/docs/structure.html Mon Oct 03 23:04:48 2005 +0000
7.2 +++ b/docs/structure.html Mon Oct 03 23:05:27 2005 +0000
7.3 @@ -1,12 +1,10 @@
7.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
7.5 -<html xmlns="http://www.w3.org/1999/xhtml">
7.6 -<head>
7.7 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
7.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
7.9 - <title>Creating Applications: Add Structure</title>
7.10 - <meta name="generator"
7.11 - content="amaya 8.1a, see http://www.w3.org/Amaya/" />
7.12 - <link href="styles.css" rel="stylesheet" type="text/css" />
7.13 -</head>
7.14 +
7.15 + <title>Creating Applications: Add Structure</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
7.16 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
7.17 +
7.18 <body>
7.19 <h1>Creating Applications: Add Structure</h1>
7.20 <p>Earlier, we defined the <a href="data.html">structure of the form
7.21 @@ -19,15 +17,7 @@
7.22 adding special attributes to the HTML code.</p>
7.23 <p> Consider the interesting parts of the template side by side with
7.24 the structure information:</p>
7.25 -<pre style=""><structure> <span
7.26 - style="font-weight: bold;"><body><br /><br /></span> <item <span
7.27 - style="font-weight: bold;"><div></span><br /> <p><br /> value="some value"> Some item: <span
7.28 - style="font-weight: bold;"><input name="value" type="text" value="some value" /></span><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <subitem <span
7.29 - style="font-weight: bold;"><p><br /> </span> subvalue="some other value"/> Sub-item: <span
7.30 - style="font-weight: bold;"><input name="subvalue" type="text" value="some other value" /></span><br /> <input name="remove2" type="submit" value="Remove" /><br /> <span
7.31 - style="font-weight: bold;"></p></span><br /> <p><br /> <input name="add2" type="submit" value="Add subitem" /><br /> </p><br /> </item> <span
7.32 - style="font-weight: bold;"></div></span><br /> <p><br /> <input name="add" type="submit" value="Add item" /><br /> </p><br /><br /></structure> <span
7.33 - style="font-weight: bold;"></body></span></pre>
7.34 +<pre style=""><structure> <span style="font-weight: bold;"><body><br /><br /></span> <item <span style="font-weight: bold;"><div></span><br /> <p><br /> value="some value"> Some item: <span style="font-weight: bold;"><input name="value" type="text" value="some value" /></span><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <subitem <span style="font-weight: bold;"><p><br /> </span> subvalue="some other value"/> Sub-item: <span style="font-weight: bold;"><input name="subvalue" type="text" value="some other value" /></span><br /> <input name="remove2" type="submit" value="Remove" /><br /> <span style="font-weight: bold;"></p></span><br /> <p><br /> <input name="add2" type="submit" value="Add subitem" /><br /> </p><br /> </item> <span style="font-weight: bold;"></div></span><br /> <p><br /> <input name="add" type="submit" value="Add item" /><br /> </p><br /><br /></structure> <span style="font-weight: bold;"></body></span></pre>
7.35 <p>To make such connections, we will annotate the HTML code using
7.36 special attributes and values.</p>
7.37 <ul>
7.38 @@ -35,44 +25,24 @@
7.39 <h2>Annotating the Template</h2>
7.40 <p>Taking the template extract from above, we add special annotations
7.41 to produce something like this:</p>
7.42 -<pre style=""><structure> <body <span
7.43 - style="font-weight: bold;">template:element="structure"</span>><br /><br /> <item <div <span
7.44 - style="font-weight: bold;">template:element="item"</span>><br /> <p><br /> value="some value"> Some item: <input <span
7.45 - style="font-weight: bold;">template:attribute="value"</span> name="<span
7.46 - style="font-weight: bold;">{template:this-attribute()}</span>" type="text" value="<span
7.47 - style="font-weight: bold;">{$this-value}</span>" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <subitem <p <span
7.48 - style="font-weight: bold;">template:element="subitem"</span>><br /> subvalue="some other value"/> Sub-item: <input <span
7.49 - style="font-weight: bold;">template:attribute="subvalue"</span> name="<span
7.50 - style="font-weight: bold;">{template:this-attribute()}</span>" type="text" value="<span
7.51 - style="font-weight: bold;">{$this-value}</span>" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="add2" type="submit" value="Add subitem" /><br /> </p><br /> </item> </div><br /> <p><br /> <input name="add" type="submit" value="Add item" /><br /> </p><br /><br /></structure> </body></pre>
7.52 +<pre style=""><structure> <body <span style="font-weight: bold;">template:element="structure"</span>><br /><br /> <item <div <span style="font-weight: bold;">template:element="item"</span>><br /> <p><br /> value="some value"> Some item: <input <span style="font-weight: bold;">template:attribute-field="value"</span> name="<span style="font-weight: bold;">...</span>" type="text" value="<span style="font-weight: bold;">...</span>" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <subitem <p <span style="font-weight: bold;">template:element="subitem"</span>><br /> subvalue="some other value"/> Sub-item: <input <span style="font-weight: bold;">template:attribute-field="subvalue"</span> name="<span style="font-weight: bold;">...</span>" type="text" value="<span style="font-weight: bold;">...</span>" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="add2" type="submit" value="Add subitem" /><br /> </p><br /> </item> </div><br /> <p><br /> <input name="add" type="submit" value="Add item" /><br /> </p><br /><br /></structure> </body></pre>
7.53 <p style="">
7.54 The following annotations have been added:</p>
7.55 <ul>
7.56 <li>For elements in the structure, <code>template:element</code>
7.57 attributes have been added to the corresponding HTML elements in the
7.58 template.</li>
7.59 - <li>For attributes in the structure, <code>template:attribute</code>
7.60 -attributes have been added to the corresponding HTML <code>elements
7.61 -in the template.</code></li>
7.62 + <li>For attributes in the structure, <code>template:attribute-field</code>
7.63 +attributes have been added to the corresponding HTML elements
7.64 +in the template.</li>
7.65 </ul>
7.66 -<p>In addition, some of the attributes in the original HTML code have
7.67 -been changed:</p>
7.68 -<ul>
7.69 - <li>The <code>input</code> elements' <code>name</code>
7.70 -attributes have been redefined to use the special <code>{template:this-attribute()}</code>
7.71 -value.</li>
7.72 - <li>The <code>input</code> elements' <code>value</code>
7.73 -attributes have been redefined to use the special <code>{$this-value}</code>
7.74 -value.</li>
7.75 -</ul>
7.76 -<p>Whereas the first set of annotations reproduce the desired
7.77 -structure, the latter modifications are really housekeeping measures to
7.78 -make sure that the final output contains the correct names and values
7.79 -for each of the form fields shown to the user.</p>
7.80 +<p>Note how the <code>name</code> and <code>value</code> attributes have had their contents replaced with <code>...</code>;
7.81 +we do this to keep Web page editors happy, and in the final output
7.82 +these attributes will be replaced with those which model the underlying
7.83 +document correctly.</p>
7.84 <h2>Completing the Template</h2>
7.85 <p>The template in full should now look something like this:</p>
7.86 -<pre><?xml version="1.0"?><br /><html xmlns="http://www.w3.org/1999/xhtml"<br /> <span
7.87 - style="font-weight: bold;">xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"</span>><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="value" name="{template:this-attribute()}" 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:this-attribute()}" type="text" value="{$this-value}" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="add2" type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="add" type="submit" value="Add item" /><br /></p><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
7.88 +<pre><?xml version="1.0"?><br /><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 /><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="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-field="subvalue" name="..." type="text" value="..." /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <input name="add2" type="submit" value="Add subitem" /><br /> </p><br /></div><br /><p><br /> <input name="add" type="submit" value="Add item" /><br /></p><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></form><br /></body><br /></html></pre>
7.89 <p>Note also that a namespace declaration is required for the <code>template</code>
7.90 attributes, and it is usually best to put this declaration on the
7.91 top-level <code>html</code> element in the template, as shown in
7.92 @@ -83,5 +53,4 @@
7.93 yet fully modelled in the template. These things will be added to the
7.94 template as <a href="selectors.html">selectors</a> as part of the
7.95 next activity in the development <a href="overview.html">process</a>.</p>
7.96 -</body>
7.97 -</html>
7.98 +</body></html>
7.99 \ No newline at end of file
8.1 --- a/docs/what.html Mon Oct 03 23:04:48 2005 +0000
8.2 +++ b/docs/what.html Mon Oct 03 23:05:27 2005 +0000
8.3 @@ -1,6 +1,5 @@
8.4 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
8.5 -<html xmlns="http://www.w3.org/1999/xhtml">
8.6 -<head>
8.7 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
8.8
8.9
8.10
8.11 @@ -17,17 +16,15 @@
8.12
8.13
8.14
8.15 - <title>What are XSLTools and XSLForms?</title>
8.16 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
8.17 +
8.18 + <title>What are XSLTools and XSLForms?</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
8.19
8.20
8.21
8.22
8.23
8.24
8.25 - <link href="styles.css" rel="stylesheet" type="text/css" />
8.26 -</head>
8.27 -
8.28 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
8.29
8.30 <body>
8.31
8.32 @@ -41,7 +38,7 @@
8.33 <ul>
8.34 <li>The XSLForms
8.35 framework for developing forms-based Web applications using XML and XSL stylesheets and transformations.</li>
8.36 - <li>The XSLOutput module for producing XML output from XML documents and XSL stylesheets.</li>
8.37 + <li>The XSLTools package for producing XML output.</li>
8.38 </ul>
8.39 <p>The relationship between these two technologies is summarised in the diagram below:</p>
8.40 <table style="width: 80%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="5" cellspacing="0">
8.41 @@ -55,14 +52,13 @@
8.42 <td align="undefined" valign="undefined"><span class="explanation">This is a solution which models Web form data as XML documents, presenting such documents using presentation templates.</span></td>
8.43 </tr>
8.44 <tr>
8.45 - <th style="background-color: rgb(102, 203, 255); text-align: center; vertical-align: middle;">XSLOutput</th>
8.46 + <th style="background-color: rgb(102, 203, 255); text-align: center; vertical-align: middle;">XSLTools</th>
8.47 <td align="undefined" valign="undefined"><span class="explanation">This provides the presentation support, producing Web pages from XML documents and XSL stylesheets.</span></td>
8.48 </tr>
8.49 </tbody>
8.50 </table>
8.51 <p>XSLForms employs presentation templates which are converted to XSL
8.52 stylesheets, permitting the framework to take advantage of that
8.53 -particular standardised and well-supported technology using XSLOutput
8.54 +particular standardised and well-supported technology using XSLTools (specifically XSLOutput)
8.55 and, in turn, libxslt.</p>
8.56 -</body>
8.57 -</html>
8.58 +</body></html>
8.59 \ No newline at end of file