1.1 --- a/docs/JavaScript-reference.html Sat Sep 08 16:53:18 2007 +0000
1.2 +++ b/docs/JavaScript-reference.html Sat Sep 08 16:53:34 2007 +0000
1.3 @@ -1,8 +1,25 @@
1.4 +<?xml version="1.0" encoding="iso-8859-1"?>
1.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
1.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.8 -
1.9 - <title>JavaScript Function Reference</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.10 + <title>JavaScript Function Reference</title>
1.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.12 <body>
1.13 -<h1>JavaScript Function References</h1><p>The following JavaScript functions are available for the triggering of in-page updates:</p><h2>requestUpdateArea</h2><p>Parameters:</p><dl><dt><code>url</code></dt><dd>The URL (which may be relative to the current page or resource) to which the update shall be sent. For example:<br /><pre>'platforms'</pre>The above example causes an update to be sent to the location <code>platforms</code> relative to the current page.</dd><dt><code>sourceAreasStr</code></dt><dd>A comma-separated list of regions in the form data which affect the outcome of the update. For example:<br /><pre>'/package$1/platforms$1'</pre>Typically, one would use an <a href="../apidocs/public/XSLForms.Output-module.html">template extension function</a> to provide such information. For example:<br /><pre>'{template:other-elements(..)}'</pre>Selector fields may be specified in addition to regions:<br /><pre>'{template:selector-name('remove_platform', .)}'</pre>The above example causes the <code>remove_platform</code> selector field to be included in the update.</dd><dt><code>targetName</code></dt><dd>The element identifier (specified by an HTML or XML <code>id</code> attribute) within which the outcome of the update shall appear.</dd><dt><code>targetAreasStr</code></dt><dd>A comma-separated list of regions in the form data which are affected by the update. See the <code>sourceAreasStr</code> parameter for more details.</dd><dt><code>elementPath</code></dt><dd>A simple path into the form data, defining the scope of the update.</dd></dl><h2>requestUpdate</h2><p>Parameters:</p><dl><dt><code>url</code></dt><dd>The URL (which may be relative to the current page or resource) to which the update shall be sent. See the description of the <code>url</code> parameter for the <code>requestUpdateArea</code> function for more details.</dd><dt><code>fieldNamesStr</code></dt><dd>A comma-separated list of fields in the form data which affect the outcome of the update. For example:<br /><pre>'/package$1/name'</pre>Typically, one would use an <a href="../apidocs/public/XSLForms.Output-module.html">template extension function</a> to provide such information. For example:<br /><pre>'{template:other-attributes('name', .)}'</pre>The above example causes the field associated with the <code>name</code> attribute on the current element to be included in the update.</dd><dt><code>targetName</code></dt><dd>The element identifier (specified by an HTML or XML <code>id</code> attribute) within which the outcome of the update shall appear.</dd><dt><code>targetFieldNamesStr</code></dt><dd>A comma-separated list of fields in the form data which are affected by the update. See the <code>fieldNamesStr</code> parameter for more details.</dd><dt><code>elementPath</code></dt><dd>A simple path into the form data, defining the scope of the update.</dd></dl></body></html>
1.14 \ No newline at end of file
1.15 +<h1>JavaScript Function References</h1>
1.16 +<p>The following JavaScript functions are available for the triggering of in-page updates:</p>
1.17 +<h2>requestUpdateArea</h2>
1.18 +<p>Parameters:</p><dl><dt><code>url</code></dt><dd>The URL (which may be relative to the current page or resource) to which the update shall be sent. For example:<br />
1.19 +<pre>'platforms'</pre>
1.20 +The above example causes an update to be sent to the location <code>platforms</code> relative to the current page.</dd><dt><code>sourceAreasStr</code></dt><dd>A comma-separated list of regions in the form data which affect the outcome of the update. For example:<br />
1.21 +<pre>'/package$1/platforms$1'</pre>
1.22 +Typically, one would use an <a href="../apidocs/public/XSLForms.Output-module.html">template extension function</a> to provide such information. For example:<br />
1.23 +<pre>'{template:other-elements(..)}'</pre>
1.24 +Selector fields may be specified in addition to regions:<br />
1.25 +<pre>'{template:selector-name('remove_platform', .)}'</pre>
1.26 +The above example causes the <code>remove_platform</code> selector field to be included in the update.</dd><dt><code>targetName</code></dt><dd>The element identifier (specified by an HTML or XML <code>id</code> attribute) within which the outcome of the update shall appear.</dd><dt><code>targetAreasStr</code></dt><dd>A comma-separated list of regions in the form data which are affected by the update. See the <code>sourceAreasStr</code> parameter for more details.</dd><dt><code>elementPath</code></dt><dd>A simple path into the form data, defining the scope of the update.</dd></dl>
1.27 +<h2>requestUpdate</h2>
1.28 +<p>Parameters:</p><dl><dt><code>url</code></dt><dd>The URL (which may be relative to the current page or resource) to which the update shall be sent. See the description of the <code>url</code> parameter for the <code>requestUpdateArea</code> function for more details.</dd><dt><code>fieldNamesStr</code></dt><dd>A comma-separated list of fields in the form data which affect the outcome of the update. For example:<br />
1.29 +<pre>'/package$1/name'</pre>
1.30 +Typically, one would use an <a href="../apidocs/public/XSLForms.Output-module.html">template extension function</a> to provide such information. For example:<br />
1.31 +<pre>'{template:other-attributes('name', .)}'</pre>
1.32 +The above example causes the field associated with the <code>name</code> attribute on the current element to be included in the update.</dd><dt><code>targetName</code></dt><dd>The element identifier (specified by an HTML or XML <code>id</code> attribute) within which the outcome of the update shall appear.</dd><dt><code>targetFieldNamesStr</code></dt><dd>A comma-separated list of fields in the form data which are affected by the update. See the <code>fieldNamesStr</code> parameter for more details.</dd><dt><code>elementPath</code></dt><dd>A simple path into the form data, defining the scope of the update.</dd></dl></body></html>
2.1 --- a/docs/Web-resource.html Sat Sep 08 16:53:18 2007 +0000
2.2 +++ b/docs/Web-resource.html Sat Sep 08 16:53:34 2007 +0000
2.3 @@ -1,8 +1,8 @@
2.4 +<?xml version="1.0" encoding="iso-8859-1"?>
2.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
2.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
2.8 -
2.9 - <title>Creating Applications: Write a Web Resource</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.10 + <title>Creating Applications: Write a Web Resource</title>
2.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
2.12 <body>
2.13 <h1>Creating Applications: Write a Web Resource</h1>
2.14 @@ -17,7 +17,7 @@
2.15 WebStack application around our form template.</p>
2.16 <h2>XSLForms Meets WebStack </h2>
2.17 <p>In the <a href="directory.html">directory structure</a> created
2.18 -earlier, we now want to edit the <code>__init__.py</code> file and
2.19 +earlier, we now want to edit the <code>__init__.py</code> file and
2.20 add code which will do most of the work of the form-editing
2.21 application. Here is the start of this code:</p>
2.22 <pre>#!/usr/bin/env python<br /><br />"A very simple example application."<br /><br />import WebStack.Generic<br />import XSLForms.Resources.WebResources<br />import XSLForms.Utils<br />import os<br /><br /># Resource classes.<br /><br />class VerySimpleResource(XSLForms.Resources.WebResources.XSLFormsResource):<br /><br /> # To be continued.</pre>
2.23 @@ -30,51 +30,51 @@
2.24 <pre>class VerySimpleResource(XSLForms.Resources.WebResources.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_template.xhtml", "structure_output.xsl")<br /> }<br /><br /> 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 /> # To be continued.</pre>
2.25 <p>The class is started with some attribute definitions:</p>
2.26 <ul>
2.27 - <li>The <code>resource_dir</code> attribute is used to locate
2.28 + <li>The <code>resource_dir</code> attribute is used to locate
2.29 the template, stylesheet and other non-Python resources. We calculate
2.30 this attribute by taking the location of the Python package itself and
2.31 -finding the <code>Resources</code> subdirectory, just as described
2.32 +finding the <code>Resources</code> subdirectory, just as described
2.33 in the <a href="directory.html">directory structure</a> document.</li>
2.34 - <li>The <code>encoding</code> attribute is not strictly
2.35 + <li>The <code>encoding</code> attribute is not strictly
2.36 necessary, but it states which character encoding will be used in the
2.37 Web pages generated by the template, and UTF-8 is a safe choice in most
2.38 situations.</li>
2.39 - <li>The <code>template_resources</code> attribute is a
2.40 + <li>The <code>template_resources</code> attribute is a
2.41 dictionary mapping a name onto details about our template and the
2.42 stylesheet that will actually produce the Web pages for each form being
2.43 edited.<br />
2.44 <ol>
2.45 <li>For the key, we choose a name that can easily be remembered
2.46 -and associated with our template: <code>structure</code> (since
2.47 -the root element of the form data is always <code>structure</code>)</li>
2.48 - <li>Then, we specify the filename of our template in the <code>Resources</code>
2.49 -directory: <code>structure_template.xhtml</code> (if the suggested
2.50 +and associated with our template: <code>structure</code> (since
2.51 +the root element of the form data is always <code>structure</code>)</li>
2.52 + <li>Then, we specify the filename of our template in the <code>Resources</code>
2.53 +directory: <code>structure_template.xhtml</code> (if the suggested
2.54 name was used)</li>
2.55 <li>Finally, we choose a filename for the stylesheet. Since this
2.56 is automatically produced from the template, we only need to choose a
2.57 name which is not already in use by another file, and for clarity a
2.58 -name similar to that of the template is recommended: <code>structure_output.xsl</code></li>
2.59 +name similar to that of the template is recommended: <code>structure_output.xsl</code></li>
2.60 </ol></li></ul>
2.61 -<p>The class also has a method which resembles the typical <code>respond</code>
2.62 +<p>The class also has a method which resembles the typical <code>respond</code>
2.63 method of normal <a href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>
2.64 -resources: the <code>respond_to_form</code> method is, in fact, a
2.65 +resources: the <code>respond_to_form</code> method is, in fact, a
2.66 special version of that method providing ready-to-use information about
2.67 the form (or forms) being edited.</p>
2.68 <p>We may now add to the above method definition by considering what
2.69 the resource needs to do when being sent a request by a user of the
2.70 application.</p>
2.71 <h3>Defining the Method</h3>
2.72 -<p>First of all, we need to inspect the <code>form</code> object
2.73 +<p>First of all, we need to inspect the <code>form</code> object
2.74 to see if any form data is available. Since the data is provided
2.75 -throughout XSLForms as XML documents, we call the <code>get_documents</code>
2.76 -method on the <code>form</code> object:</p>
2.77 +throughout XSLForms as XML documents, we call the <code>get_documents</code>
2.78 +method on the <code>form</code> object:</p>
2.79 <pre> documents = form.get_documents()</pre>
2.80 <p>As a result of this method, we should now have a dictionary mapping
2.81 form names to XML documents containing form data. However, it is not
2.82 -guaranteed that the form data for our chosen form, <code>structure</code>,
2.83 +guaranteed that the form data for our chosen form, <code>structure</code>,
2.84 even exists since a user may be visiting the resource for the first
2.85 time.</p>
2.86 -<p>Therefore, we test to see if the <code>structure</code>
2.87 +<p>Therefore, we test to see if the <code>structure</code>
2.88 document exists, creating a new document if it did not:</p>
2.89 <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 /></pre>
2.90 <p>Now we should have a document containing the data for the form being
2.91 @@ -82,11 +82,11 @@
2.92 whether we have created a new one for that purpose.</p>
2.93 <p>It may be the case that a user pressed a button in order to add or
2.94 remove items or subitems from the form. We must respond to such things
2.95 -by examining the selector information to see which parts of the <code>structure</code>
2.96 +by examining the selector information to see which parts of the <code>structure</code>
2.97 document are affected:</p>
2.98 <pre> # Add and remove elements according to the selectors found.<br /><br /> selectors = form.get_selectors()<br /></pre>
2.99 <p>The result of <code>get_selectors</code> is a dictionary mapping
2.100 -selector names to lists of nodes affected by each particular
2.101 +selector names to lists of nodes affected by each particular
2.102 selector. In the <a href="selectors.html">selector annotation</a>
2.103 process, we defined selectors for the addition and removal of items and
2.104 subitems, and for convenience we pass the results for each selector to
2.105 @@ -97,12 +97,12 @@
2.106 with our chosen character encoding:</p>
2.107 <pre> # Start the response.<br /><br /> trans.set_content_type(WebStack.Generic.ContentType("application/xhtml+xml", self.encoding))<br /></pre>
2.108 <p>Then, we ensure that our template is ready to use by calling the
2.109 -superclass's <code>prepare_output</code> method with the name of
2.110 +superclass's <code>prepare_output</code> method with the name of
2.111 the form:</p>
2.112 <pre> # Ensure that an output stylesheet exists.<br /><br /> trans_xsl = self.prepare_output("structure")<br /></pre>
2.113 -<p>This prepares the stylesheet whose file is named in the <code>template_resources</code>
2.114 +<p>This prepares the stylesheet whose file is named in the <code>template_resources</code>
2.115 attribute entry, and this stylesheet is then sent to the
2.116 -superclass's <code>send_output</code> method as part of a list of
2.117 +superclass's <code>send_output</code> method as part of a list of
2.118 stylesheets (although we only use a single stylesheet in this example)
2.119 along with the form data itself:</p>
2.120 <pre> # Complete the response.<br /><br /> self.send_output(trans, [trans_xsl], structure)</pre>
2.121 @@ -117,19 +117,19 @@
2.122 <p>To actually deploy the application, we could choose one of many
2.123 server environments supported by WebStack. For clarity, we choose here
2.124 to write the following separate program which we can save under the
2.125 -name <code>VerySimpleApp.py</code> (for example):</p>
2.126 +name <code>VerySimpleApp.py</code> (for example):</p>
2.127 <pre>#!/usr/bin/env python<br /><br />from WebStack.Adapters.BaseHTTPRequestHandler import deploy<br />import VerySimple<br /><br /># Get a simple Web site.<br /><br />resource = VerySimple.get_site()<br /><br /># Special magic incantation.<br /><br />print "Serving..."<br />deploy(resource, handle_errors=0)</pre>
2.128 <p>Ensuring that the example application's package (which we
2.129 -called <code>VerySimple</code> in the directory structure
2.130 +called <code>VerySimple</code> in the directory structure
2.131 document), WebStack, libxml2dom and XSLForms are available to the above
2.132 program, we may now run this program:</p>
2.133 <pre>python VerySimpleApp.py</pre>
2.134 -<p>It should then be possible to visit the URL <code>http://localhost:8080/</code>
2.135 +<p>It should then be possible to visit the URL <code>http://localhost:8080/</code>
2.136 and edit the form in your Web browser.<br />
2.137 </p>
2.138 <h2>Further Enhancements</h2>
2.139 <p>We should now have an application which can be deployed and tested
2.140 using the usual WebStack techniques. However, more advanced templates
2.141 can be designed, and we shall consider <a href="multiple.html">multiple-choice
2.142 -fields</a> in the next activity in the development <a href="overview.html">process</a>.</p>
2.143 +fields</a> in the next activity in the development <a href="overview.html">process</a>.</p>
2.144 </body></html>
3.1 --- a/docs/XSLForms-resource.html Sat Sep 08 16:53:18 2007 +0000
3.2 +++ b/docs/XSLForms-resource.html Sat Sep 08 16:53:34 2007 +0000
3.3 @@ -1,17 +1,17 @@
3.4 +<?xml version="1.0" encoding="iso-8859-1"?>
3.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
3.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
3.8 -
3.9 - <title>Using the XSLFormsResource API</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.10 + <title>Using the XSLFormsResource API</title>
3.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
3.12 <body>
3.13 <h1>Using the XSLFormsResource API</h1>
3.14 -<p>The XSLForms toolkit provides a special WebStack resource class (described in the <a href="Web-resource.html">"Creating Applications: Write a Web Resource"</a>
3.15 -document), and
3.16 -from this class, <code>XSLFormsResource</code>,
3.17 +<p>The XSLForms toolkit provides a special WebStack resource class (described in the <a href="Web-resource.html">"Creating Applications: Write a Web Resource"</a>
3.18 +document), and
3.19 +from this class, <code>XSLFormsResource</code>,
3.20 you can derive your own application-specific resources and use the
3.21 class's API to obtain, manipulate and present form data. Although the
3.22 -supplied <a href="../apidocs/index.html">API documentation</a> provides details of the class's API, specifically in the <code><a href="../apidocs/public/XSLForms.Resources.WebResources-module.html">XSLForms.Resources.WebResources</a></code><a href="../apidocs/public/XSLForms.Resources.WebResources-module.html"></a> module, this document attempts to explain how the API is used in practice.</p><h2>Resource Structure</h2><p>The structure of a Web resource derived from <code>XSLFormsResource</code> should look like this:</p><pre>class MyResource(XSLForms.Resources.WebResources.XSLFormsResource):<br /><br /> [Resource definitions]<br /><br /> def respond_to_form(self, trans, form):<br /> [Examine the form data, see if the user has added or removed anything.]<br /> [Perform additional processing and initialise the form data.]<br /> [Produce some kind of response to show the user the updated form data.]</pre><p>Since <code>XSLFormsResource</code> builds on WebStack's resource mechanisms, we do have the transaction object, <code>trans</code>, available. However, most of the information we need to access and manipulate is generally available through the <code>form</code> object.</p><h2>Defining Resources</h2><p>Classes derived from <code>XSLFormsResource</code>
3.23 +supplied <a href="../apidocs/index.html">API documentation</a> provides details of the class's API, specifically in the <code><a href="../apidocs/public/XSLForms.Resources.WebResources-module.html">XSLForms.Resources.WebResources</a></code><a href="../apidocs/public/XSLForms.Resources.WebResources-module.html"></a> module, this document attempts to explain how the API is used in practice.</p><h2>Resource Structure</h2><p>The structure of a Web resource derived from <code>XSLFormsResource</code> should look like this:</p><pre>class MyResource(XSLForms.Resources.WebResources.XSLFormsResource):<br /><br /> [Resource definitions]<br /><br /> def respond_to_form(self, trans, form):<br /> [Examine the form data, see if the user has added or removed anything.]<br /> [Perform additional processing and initialise the form data.]<br /> [Produce some kind of response to show the user the updated form data.]</pre><p>Since <code>XSLFormsResource</code> builds on WebStack's resource mechanisms, we do have the transaction object, <code>trans</code>, available. However, most of the information we need to access and manipulate is generally available through the <code>form</code> object.</p><h2>Defining Resources</h2><p>Classes derived from <code>XSLFormsResource</code>
3.24 support the concept of resources which are used to produce output,
3.25 support processing and to provide access to useful information. At the
3.26 class level it is essential to define at least some of these resources
3.27 @@ -22,8 +22,8 @@
3.28 a Directory"</a> document). Consequently, it is the convention that all resource classes define such information as follows:</p><pre>class ConfiguratorResource(XSLForms.Resources.WebResources.XSLFormsResource):<br /><br /> resource_dir = os.path.join(os.path.split(__file__)[0], "Resources")</pre><p>All
3.29 filenames, defined in the various resource sections (as described
3.30 below) must be stated without leading path information - in other
3.31 -words, as "leafnames" rather than "pathnames". Thus, an example of
3.32 -an incorrect filename would be <code>/home/paulb/templates/my_template.xhtml</code>, whereas an example of a correct filename would be just <code>my_template.xhtml</code> when correcting the incorrect example.<br /></p><h3>Character Encoding</h3><p>It
3.33 +words, as "leafnames" rather than "pathnames". Thus, an example of
3.34 +an incorrect filename would be <code>/home/paulb/templates/my_template.xhtml</code>, whereas an example of a correct filename would be just <code>my_template.xhtml</code> when correcting the incorrect example.<br /></p><h3>Character Encoding</h3><p>It
3.35 is also the convention to define the character encoding of the output
3.36 produced by an application and the way ambiguous or
3.37 insufficiently-specified input should be interpreted; this is done as
3.38 @@ -32,13 +32,13 @@
3.39 visual representation of a form. Therefore, we need to define templates
3.40 (as described in the <a href="design.html">"Creating Applications: Design a Template"</a>
3.41 document) to express the representation of each kind of form, along
3.42 -with any intermediate files that may be produced. A special
3.43 -class-level <code>template_resources</code> dictionary is used to hold such definitions.</p><p>To
3.44 +with any intermediate files that may be produced. A special
3.45 +class-level <code>template_resources</code> dictionary is used to hold such definitions.</p><p>To
3.46 define a template resource, we first choose a name (which need not have
3.47 -any special significance); we then associate with that name a
3.48 -template filename and an output filename. Finally, we make an
3.49 +any special significance); we then associate with that name a
3.50 +template filename and an output filename. Finally, we make an
3.51 entry for the name and its associated details in the special
3.52 -class-level <code>template_resources</code> dictionary as follows:</p><pre> # Continuing from above...<br /><br /> template_resources = {<br /> "configuration" : ("config_template.xhtml", "config_output.xsl"),<br /> # More entries go here...<br /> }</pre><p>The purpose
3.53 +class-level <code>template_resources</code> dictionary as follows:</p><pre> # Continuing from above...<br /><br /> template_resources = {<br /> "configuration" : ("config_template.xhtml", "config_output.xsl"),<br /> # More entries go here...<br /> }</pre><p>The purpose
3.54 of the output filename is to define where the intermediate
3.55 output-producing stylesheet is to be written, since the template itself
3.56 is not actually used to produce output, but knowing where the
3.57 @@ -60,20 +60,20 @@
3.58 the input filename provides firm information about the location of the
3.59 stylesheet which actually performs the initialisation process.</p><h3>Document Resources</h3><p>Since
3.60 it is the XSLForms convention to access files using a simple name, any
3.61 -other document resources should be defined in the <code>document_resources</code>
3.62 +other document resources should be defined in the <code>document_resources</code>
3.63 dictionary at the class level. Such document resources may be used in
3.64 the initialisation process or in other transformations (as described
3.65 below), and are defined as entries mapping names to filenames such as
3.66 in the following example:</p><pre> # Continuing from above...<br /><br /> document_resources = {<br /> "accessories" : "config_accessories.xml",<br /> "base-system" : "config_base_system.xml",<br /> # More entries go here...<br /> }</pre><p>There is no particular limitation on the types of files which can be referenced in the <code>document_resources</code>
3.67 dictionary, nor any insistence in the XSLForms toolkit to define such
3.68 files as resources - the dictionary is merely a convenience for
3.69 -accessing files in the resources directory.</p><h3>Transform Resources</h3><p>It is sometimes the case that initialisation of a document
3.70 +accessing files in the resources directory.</p><h3>Transform Resources</h3><p>It is sometimes the case that initialisation of a document
3.71 is not sufficient and that additional processing needs to be done.
3.72 Whilst various techniques exist for the processing of XML-based
3.73 information, since XSLForms is part of a wider toolkit based on XSL
3.74 transformations, it seems reasonable to provide certain facilities for
3.75 the usage of such transformations. Thus, stylesheet processing
3.76 -pipelines may be defined at the class level in the <code>transform_resources</code> dictionary.</p><p>Entries in the <code>transform_resources</code>
3.77 +pipelines may be defined at the class level in the <code>transform_resources</code> dictionary.</p><p>Entries in the <code>transform_resources</code>
3.78 dictionary map simple names (which need not have any special
3.79 significance) to collections of stylesheet filenames as in the
3.80 following example:</p><pre> # Continuing from above...<br /><br /> transform_resources = {<br /> "filter" : ["filter.xsl"],<br /> # More entries go here...<br /> }</pre><p>Where
3.81 @@ -91,7 +91,7 @@
3.82 part of the Web page to generate as output. Consequently, the
3.83 application has to have some kind of record of the different kinds of
3.84 updates and the corresponding parts of the whole page template to use,
3.85 -and this information is recorded in the class-level <code>in_page_resources</code> dictionary.</p><p>The form of an entry in the <code>in_page_resources</code>
3.86 +and this information is recorded in the class-level <code>in_page_resources</code> dictionary.</p><p>The form of an entry in the <code>in_page_resources</code>
3.87 dictionary is that of a mapping from a name identifying the kind of
3.88 update to the details of the part of the template to be employed in
3.89 producing the final output for the update: an intermediate filename
3.90 @@ -100,16 +100,16 @@
3.91 template. Here is an example of an in-page resource definition:</p><pre> # Continuing from above...<br /><br /> in_page_resources = {<br /> "cpu" : ("config_output_cpu.xsl", "cpu-node"),<br /> # More entries go here...<br /> }</pre><h4>Update Names</h4><p>It
3.92 is important to note that, unlike other resources, the name identifying
3.93 the kind of update is significant: consider an application available at
3.94 -the following location:</p><pre>http://localhost/configurator/</pre><p>An in-page update called <code>cpu</code> would be accessed through the following location:</p><pre>http://localhost/configurator/cpu</pre><p>Thus,
3.95 +the following location:</p><pre>http://localhost/configurator/</pre><p>An in-page update called <code>cpu</code> would be accessed through the following location:</p><pre>http://localhost/configurator/cpu</pre><p>Thus,
3.96 the availability of such an update "service" depends on the proper
3.97 configuration of the Web application to let such updates be handled by
3.98 the resource.</p><h4>Update Nodes</h4><p>The node identifier mentioned
3.99 in an in-page update resource definition must be a valid node
3.100 identifier in the whole page template document. Thus, if we wished to
3.101 -use the identifier in the above example together with <code>config_template.xhtml</code>, we would have to ensure that the identifier appeared as a value of an <code>id</code>
3.102 +use the identifier in the above example together with <code>config_template.xhtml</code>, we would have to ensure that the identifier appeared as a value of an <code>id</code>
3.103 node in that template document. Note that the choice of template
3.104 document is not defined here, but is instead made when handling an
3.105 -in-page update request.</p><h2>Examining the Form Data</h2><p>The form data is available through the <code>form</code> object which exposes the <code><a href="../apidocs/public/XSLForms.Fields.Form-class.html">XSLForms.Fields.Form</a></code> API. The most interesting operations are as follows:</p><h3>Obtain the Form Data Documents</h3><p>Since
3.106 +in-page update request.</p><h2>Examining the Form Data</h2><p>The form data is available through the <code>form</code> object which exposes the <code><a href="../apidocs/public/XSLForms.Fields.Form-class.html">XSLForms.Fields.Form</a></code> API. The most interesting operations are as follows:</p><h3>Obtain the Form Data Documents</h3><p>Since
3.107 XSLForms is an XML-based toolkit, the form data is available as XML
3.108 documents which can be accessed and manipulated using a DOM-style API.
3.109 Upon receiving submitted form data, XSLForms converts the data to such
3.110 @@ -122,46 +122,46 @@
3.111 it is likely that we will want to work with such a document regardless
3.112 of whether one existed before - we must after all prepare such a
3.113 document in the first place in order to show it to the user and have it
3.114 -submitted back to us - we really want to create it if it does not exist:</p><pre>if documents.has_key("items"):<br /> items = documents["items"]<br />else:<br /> items = form.new_document("items")</pre><p>The resulting <code>items</code> object is a genuine DOM-style document containing the form data.</p><h3>Obtain the Form Data Selectors</h3><p>As described in the <a href="selectors.html">"Creating Applications: Add Selectors"</a>
3.115 +submitted back to us - we really want to create it if it does not exist:</p><pre>if documents.has_key("items"):<br /> items = documents["items"]<br />else:<br /> items = form.new_document("items")</pre><p>The resulting <code>items</code> object is a genuine DOM-style document containing the form data.</p><h3>Obtain the Form Data Selectors</h3><p>As described in the <a href="selectors.html">"Creating Applications: Add Selectors"</a>
3.116 document, XSLForms templates may define selectors - special form fields
3.117 which select parts of the form data documents and make those parts
3.118 available to applications; such selector information can be obtained as
3.119 -follows:</p><pre>selectors = form.get_selectors()</pre><p>If a selector was defined with the name <code>remove</code>, then any selected elements that are associated with this selector may be obtained as follows:</p><pre>removed_elements = selectors.get("remove") # which will return None if no such selector was defined</pre><p>Since
3.120 +follows:</p><pre>selectors = form.get_selectors()</pre><p>If a selector was defined with the name <code>remove</code>, then any selected elements that are associated with this selector may be obtained as follows:</p><pre>removed_elements = selectors.get("remove") # which will return None if no such selector was defined</pre><p>Since
3.121 the collection contains DOM-style elements, various XML libraries and
3.122 tools may be used to manipulate the data. However, XSLForms also
3.123 provides convenience functions to add and remove elements.</p><h3>Obtaining Other Parameters</h3><p>Sometimes,
3.124 there is a need to obtain the "raw" request parameters submitted by the
3.125 Web client or browser which sent the form data in to the application.
3.126 -Such parameters could be obtained using the <code>trans</code> object, but it is also possible to use the following approach:</p><pre>parameters = form.get_parameters()<br />some_parameter = parameters.get("something") # which returns None if no such parameter exists; a list otherwise<br />another_parameter = parameters.get("another", [""])[0] # which will always return a string, empty if no such parameter was found</pre><h2>Performing Additional Processing</h2><p>Additional
3.127 +Such parameters could be obtained using the <code>trans</code> object, but it is also possible to use the following approach:</p><pre>parameters = form.get_parameters()<br />some_parameter = parameters.get("something") # which returns None if no such parameter exists; a list otherwise<br />another_parameter = parameters.get("another", [""])[0] # which will always return a string, empty if no such parameter was found</pre><h2>Performing Additional Processing</h2><p>Additional
3.128 processing of the form data can be performed in many different ways,
3.129 limited only by the DOM-style API exposed by the data and the XSL
3.130 -transformation features available in the XSLForms toolkit.</p><h3>Transformations</h3><p>To take advantage of the defined <code>transform_resources</code>, we can call a method on the resource itself to prepare such resources:</p><pre>filter_stylesheets = self.prepare_transform("filter")</pre><p>Then,
3.131 +transformation features available in the XSLForms toolkit.</p><h3>Transformations</h3><p>To take advantage of the defined <code>transform_resources</code>, we can call a method on the resource itself to prepare such resources:</p><pre>filter_stylesheets = self.prepare_transform("filter")</pre><p>Then,
3.132 with the result of this call (a list of stylesheet filenames), we can
3.133 then perform a transformation on a document, producing a new document
3.134 -from the results:</p><pre>configuration_document = self.get_result(filter_stylesheets, configuration_document)</pre><p>This new document is different from the document supplied to the <code>get_result</code>
3.135 +from the results:</p><pre>configuration_document = self.get_result(filter_stylesheets, configuration_document)</pre><p>This new document is different from the document supplied to the <code>get_result</code>
3.136 method. It should therefore be noted that any references to elements in
3.137 the old document will not affect the new document; thus selectors
3.138 -previously obtained from the <code>form</code> object will not refer to elements in the new document. However, by setting the new document in the <code>form</code> object, new selectors may be obtained referring to elements in the new document:</p><pre>form.set_document("configuration", configuration_document)<br />selectors = form.get_selectors()</pre><p>Care
3.139 +previously obtained from the <code>form</code> object will not refer to elements in the new document. However, by setting the new document in the <code>form</code> object, new selectors may be obtained referring to elements in the new document:</p><pre>form.set_document("configuration", configuration_document)<br />selectors = form.get_selectors()</pre><p>Care
3.140 must be taken doing this, however, since the selectors may now not
3.141 refer to valid elements - the transformation may have removed or moved
3.142 -elements previously referred to by the selectors.</p><p>The <code>get_result</code>
3.143 +elements previously referred to by the selectors.</p><p>The <code>get_result</code>
3.144 method also supports stylesheet parameters, document references and
3.145 stylesheet expressions; these are described in the "Additional
3.146 Stylesheet Parameters" section below.</p><h3>Using Selectors to Modify the Data</h3><p>As
3.147 described above in "Obtain the Form Data Selectors", if the user of an
3.148 application requested changes to the form data using a selector field
3.149 (typically represented by a button or checkbox in a Web page), a list
3.150 -of selected elements will be available to the resource through the <code>form</code> object. Given a selector which is associated with a <code>remove</code>
3.151 +of selected elements will be available to the resource through the <code>form</code> object. Given a selector which is associated with a <code>remove</code>
3.152 operation, we could use the DOM-style API exposed by the contents of
3.153 the selectors to perform such an operation in the resource using our
3.154 own code. However, the XSLForms toolkit provides some useful
3.155 -convenience functions to assist in the removal or addition of elements:</p><pre># After doing this:<br /># import XSLForms.Utils<br /><br /># Removing elements...<br /><br />removed_elements = selectors.get("remove") # this may return None<br />XSLForms.Utils.remove_elements(removed_elements) # this can handle None, realising that no elements are to be removed<br /><br /># Adding elements...<br /><br />places_to_add_elements = selectors.get("add")<br />XSLForms.Utils.add_elements(places_to_add_elements, "element")</pre><p>See the <code><a href="../apidocs/public/XSLForms.Utils-module.html">XSLForms.Utils</a></code><a href="../apidocs/public/XSLForms.Utils-module.html"></a> documentation for more information on these functions.<br /></p><h2>Document Initialisation</h2><p>The initialisation of a document, using information defined in the <code>init_resources</code>
3.156 +convenience functions to assist in the removal or addition of elements:</p><pre># After doing this:<br /># import XSLForms.Utils<br /><br /># Removing elements...<br /><br />removed_elements = selectors.get("remove") # this may return None<br />XSLForms.Utils.remove_elements(removed_elements) # this can handle None, realising that no elements are to be removed<br /><br /># Adding elements...<br /><br />places_to_add_elements = selectors.get("add")<br />XSLForms.Utils.add_elements(places_to_add_elements, "element")</pre><p>See the <code><a href="../apidocs/public/XSLForms.Utils-module.html">XSLForms.Utils</a></code><a href="../apidocs/public/XSLForms.Utils-module.html"></a> documentation for more information on these functions.<br /></p><h2>Document Initialisation</h2><p>The initialisation of a document, using information defined in the <code>init_resources</code>
3.157 attribute, is similar to the transformation of a document as described
3.158 above. First, we obtain a reference to an initialisation stylesheet:</p><pre>init_stylesheet = self.prepare_initialiser("configuration")</pre><p>Note
3.159 that only a single stylesheet is returned. With the result of the call,
3.160 we then perform a transformation similar to the above activity,
3.161 although we have to supply the returned stylesheet in a list to be
3.162 -compatible with the <code>get_result</code> method:</p><pre>configuration_document = self.get_result([init_stylesheet], configuration_document)</pre><p>In practice, the above call will probably not suffice: if <a href="multiple.html">multiple-choice fields</a>
3.163 +compatible with the <code>get_result</code> method:</p><pre>configuration_document = self.get_result([init_stylesheet], configuration_document)</pre><p>In practice, the above call will probably not suffice: if <a href="multiple.html">multiple-choice fields</a>
3.164 are used in the template, there will be a need to initialise such
3.165 elements using references to other documents containing the values of
3.166 such fields; for example:</p><pre>configuration_document = self.get_result([init_stylesheet], configuration_document,<br /> references={<br /> "cpu" : self.prepare_document("cpu")<br /> })</pre><p>The
3.167 @@ -170,27 +170,27 @@
3.168 the examples supplied with XSLTools, the content type is generally
3.169 defined as that of XHTML, meaning that the resulting output should be
3.170 accessible to most modern Web browsers. When writing resources based
3.171 -on <code>XSLFormsResource</code>, we can just use the WebStack API to set the content type:</p><pre>trans.set_content_type(WebStack.Generic.ContentType("application/xhtml+xml", self.encoding))</pre><p>Note that the <code>encoding</code> attribute is used here to make the character encoding clear to the user's Web browser or client.</p><h3>Defining an Output Stylesheet</h3><p>In most cases, the output stylesheet can be chosen by selecting a template name and invoking a method on the resource:</p><pre>output_stylesheet = self.prepare_output("configuration")</pre><p>However,
3.172 +on <code>XSLFormsResource</code>, we can just use the WebStack API to set the content type:</p><pre>trans.set_content_type(WebStack.Generic.ContentType("application/xhtml+xml", self.encoding))</pre><p>Note that the <code>encoding</code> attribute is used here to make the character encoding clear to the user's Web browser or client.</p><h3>Defining an Output Stylesheet</h3><p>In most cases, the output stylesheet can be chosen by selecting a template name and invoking a method on the resource:</p><pre>output_stylesheet = self.prepare_output("configuration")</pre><p>However,
3.173 where in-page updates are handled, we may need to check to see if we
3.174 should be sending a fragment of the whole page instead. First, we must
3.175 -check to see if an in-page update is being requested:</p><pre>in_page_resource = self.get_in_page_resource(trans)</pre><p>The
3.176 +check to see if an in-page update is being requested:</p><pre>in_page_resource = self.get_in_page_resource(trans)</pre><p>The
3.177 result of calling the above method should be a string identifying an
3.178 "in-page resource" - that is, a kind of in-page update related to part
3.179 -of the whole page - if such a "resource" is actually being
3.180 +of the whole page - if such a "resource" is actually being
3.181 requested. We can thus check to see if such a request is taking place:</p><pre>if in_page_resource in self.in_page_resources.keys():<br /> [Handle the in-page update request]</pre><p>If
3.182 so, instead of getting a stylesheet which produces output for the whole
3.183 page, we get a "fragment" which produces output only for the part of
3.184 the page being updated:</p><pre> # Continued from above...<br /><br /> output_stylesheet = self.prepare_fragment("configuration", in_page_resource)<br /> stylesheet_parameters = self.prepare_parameters(parameters) # from form.get_parameters()</pre><p>An
3.185 additional step when handling in-page updates is the usage of
3.186 stylesheet parameters to send in some required information about the
3.187 -location of the update in the page. The <code>prepare_parameters</code>
3.188 +location of the update in the page. The <code>prepare_parameters</code>
3.189 method on the resource is used to discover this information and return
3.190 it as a dictionary to be passed to the final output generation activity.</p><h3>Sending the Output to the User</h3><p>Given
3.191 an output stylesheet reference and possibly some parameters, the output
3.192 is sent to the user with a single call to a method on the resource
3.193 -object:</p><pre>self.send_output(trans, [output_stylesheet], configuration_document, stylesheet_parameters)</pre><p>This method should, using the <code>encoding</code>
3.194 +object:</p><pre>self.send_output(trans, [output_stylesheet], configuration_document, stylesheet_parameters)</pre><p>This method should, using the <code>encoding</code>
3.195 attribute on the resource class, ensure that the generated output is
3.196 -correct and consistent for the user's Web browser or client.</p><h2>Additional Stylesheet Parameters</h2><p>In addition to a collection of stylesheets and a document to process, the <code>get_result</code> and <code>send_output</code> methods can accept a number of possible sources of information:</p><ul><li>Stylesheet parameters</li><li>Document references</li><li>Stylesheet expressions</li></ul><p>Generally,
3.197 +correct and consistent for the user's Web browser or client.</p><h2>Additional Stylesheet Parameters</h2><p>In addition to a collection of stylesheets and a document to process, the <code>get_result</code> and <code>send_output</code> methods can accept a number of possible sources of information:</p><ul><li>Stylesheet parameters</li><li>Document references</li><li>Stylesheet expressions</li></ul><p>Generally,
3.198 stylesheet parameters are used to configure the output in some way,
3.199 whilst document references and stylesheet expressions typically offer a
3.200 means of accessing additional information that is to be merged in or
3.201 @@ -199,7 +199,7 @@
3.202 consider the list of values given in the <a href="multiple.html">"Creating Applications: Adding Multiple-Choice Fields and Values"</a> document:</p><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><p>Such
3.203 information needs to reside somewhere and then be referenced in order
3.204 to be included in the processing operation being performed, which would
3.205 -either be a document initialisation or just a normal transformation.</p><h3>Document References</h3><p>To refer to an externally-defined information, we define the document resource as described above:</p><pre> # At class attribute level...<br /><br /> document_resources = {<br /> "types" : "types.xml",<br /> # Other documents...<br /> }</pre><p>Then, we access the resource, getting a reference to the document:</p><pre>types_xml = self.prepare_document("types")</pre><p>To bring this document into the processing operation, we add an entry to a dictionary passed as the <code>references</code> parameter to <code>get_result</code> (or <code>send_output</code>, if appropriate). In the above example, the information is referenced as follows in the template document:</p><pre> <select template:multiple-choice-field="type,value" name="..."><br /> <option template:multiple-choice-value="type-enum,value,selected" value="..." /><br /> </select></pre><p>Therefore, we take the element name, <code>type</code>, from the field and use it to refer to the external document in the dictionary of references:</p><pre>structure = self.get_result([structure_xsl], structure, references={"type" : types_xml})</pre><p>This should result in the stylesheet incorporating the information from the types document into the transformation.</p><h3>Stylesheet Expressions</h3><p>In
3.206 +either be a document initialisation or just a normal transformation.</p><h3>Document References</h3><p>To refer to an externally-defined information, we define the document resource as described above:</p><pre> # At class attribute level...<br /><br /> document_resources = {<br /> "types" : "types.xml",<br /> # Other documents...<br /> }</pre><p>Then, we access the resource, getting a reference to the document:</p><pre>types_xml = self.prepare_document("types")</pre><p>To bring this document into the processing operation, we add an entry to a dictionary passed as the <code>references</code> parameter to <code>get_result</code> (or <code>send_output</code>, if appropriate). In the above example, the information is referenced as follows in the template document:</p><pre> <select template:multiple-choice-field="type,value" name="..."><br /> <option template:multiple-choice-value="type-enum,value,selected" value="..." /><br /> </select></pre><p>Therefore, we take the element name, <code>type</code>, from the field and use it to refer to the external document in the dictionary of references:</p><pre>structure = self.get_result([structure_xsl], structure, references={"type" : types_xml})</pre><p>This should result in the stylesheet incorporating the information from the types document into the transformation.</p><h3>Stylesheet Expressions</h3><p>In
3.207 more advanced cases, referencing external documents does not provide
3.208 enough flexibility when introducing additional information into a
3.209 transformation. An alternative approach involves copying data into the
4.1 --- a/docs/advanced.html Sat Sep 08 16:53:18 2007 +0000
4.2 +++ b/docs/advanced.html Sat Sep 08 16:53:34 2007 +0000
4.3 @@ -1,8 +1,8 @@
4.4 +<?xml version="1.0" encoding="iso-8859-1"?>
4.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
4.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
4.8 -
4.9 - <title>Advanced Template Design</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.10 + <title>Advanced Template Design</title>
4.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
4.12 <body>
4.13 <h1>Advanced Template Design</h1>
4.14 @@ -11,60 +11,47 @@
4.15 data documents (or just general XML documents with no special
4.16 connection to Web forms). However, since XSLForms templates build upon
4.17 XSL transformations, it is also possible to employ certain XSL
4.18 -techniques to present the information in various different ways.</p><h2>Templates and Transformations</h2><p>When prepared, XSLForms templates are converted to XSL stylesheets, and
4.19 -when form data is displayed, such XSL stylesheets are used to
4.20 +techniques to present the information in various different ways.</p><h2>Templates and Transformations</h2><p>When prepared, XSLForms templates are converted to XSL stylesheets, and
4.21 +when form data is displayed, such XSL stylesheets are used to
4.22 transform the form data to a representation which looks like the
4.23 original template, but with different parts of the template populated
4.24 -with the form data. The process can be illustrated as
4.25 -follows:</p><table style="text-align: left; width: 80%;" align="center" border="0" cellpadding="5" cellspacing="5">
4.26 -
4.27 +with the form data. The process can be illustrated as
4.28 +follows:</p>
4.29 +<table style="text-align: left; width: 80%;" align="center" border="0" cellpadding="5" cellspacing="5">
4.30 <tbody>
4.31 -
4.32 <tr>
4.33 -
4.34 -
4.35 -
4.36 <th style="border: 1px solid rgb(0, 0, 0); background-color: rgb(193, 255, 102); text-align: center; vertical-align: top;">Template<br />
4.37 -
4.38 <span class="method">A template presents the general form of the final output.</span></th>
4.39 -
4.40 <th style="border-style: solid; border-width: 1px; text-align: center; vertical-align: top;">Stylesheet<br />
4.41 -
4.42 <span class="method">Templates are converted to stylesheets, which are like programs specially designed to present XML information.</span></th>
4.43 -
4.44 <th style="border: 1px solid rgb(0, 0, 0); background-color: rgb(255, 204, 255); text-align: center; vertical-align: top;">Output<br />
4.45 -
4.46 <span class="method">The final output is produced when a stylesheet is combined with an XML document.</span></th>
4.47 -
4.48 </tr>
4.49 -
4.50 -
4.51 -
4.52 -
4.53 </tbody>
4.54 -</table><p>Since the stylesheet is based on XSL, which is a rich
4.55 +</table>
4.56 +<p>Since the stylesheet is based on XSL, which is a rich
4.57 language in its own right, advanced template design techniques can
4.58 involve some of the features of XSL - at least those which do not
4.59 affect the simplicity or general structure of our templates.</p><h2>Template Extension Functions and Variables</h2><p>One
4.60 area where XSL features are already employed to affect the final output
4.61 -in XSLForms is in the toolkit's use of template extension
4.62 +in XSLForms is in the toolkit's use of template extension
4.63 functions and special variables - the latter being used in the output
4.64 production process. For example, we might decide to use the lower level
4.65 -template functions to present the value of an attribute:</p><pre><span template:attribute="some-attribute" template:value="$this-value">xxx</span></pre><p>In the above example, we reference the special variable <code>$this-value</code> which refers to the value of <code>some-attribute</code>. An example of template functions in use looks like this:</p><pre><span id="{template:this-element()}">xxx</span></pre><p>In the above example, we invoke the template function <code>template:this-element</code>
4.66 +template functions to present the value of an attribute:</p><pre><span template:attribute="some-attribute" template:value="$this-value">xxx</span></pre><p>In the above example, we reference the special variable <code>$this-value</code> which refers to the value of <code>some-attribute</code>. An example of template functions in use looks like this:</p><pre><span id="{template:this-element()}">xxx</span></pre><p>In the above example, we invoke the template function <code>template:this-element</code>
4.67 in order to create a unique identifier in the final output. Since we
4.68 -use the function inside an attribute which is not prefixed with <code>template</code>, we must enclose the expression between <code>{</code> and <code>}</code> characters.</p><h2>Beyond Template Extension Functions</h2><p>Since
4.69 +use the function inside an attribute which is not prefixed with <code>template</code>, we must enclose the expression between <code>{</code> and <code>}</code> characters.</p><h2>Beyond Template Extension Functions</h2><p>Since
4.70 the above template extension functions and variables are merely special in the
4.71 sense that XSLForms provides them to produce its output, and since they
4.72 are accessed in the stylesheet using normal XSL-based mechanisms, there
4.73 is no technical barrier to using other kinds of valid XSL (or more
4.74 precisely, XPath) expressions in cases such as those given above. The
4.75 -rules for using such expressions in attributes are straightforward:</p><ul><li>Attributes prefixed with <code>template</code> can contain expressions as one would write them normally.</li><li>Other attributes must have their expressions enclosed between <code>{</code> and <code>}</code> characters so that the expression is evaluated and replaced with the result in the final output.</li></ul><p>Here is a trivial example of the usage of an XPath expression, based on one of the above examples:</p><pre><span template:attribute="some-attribute" template:value="string-length($this-value)">xxx</span></pre><p>In the above example, we invoke the standard XPath function <code>string-length</code> in order to produce within the <code>span</code> element the length of the value of <code>some-attribute</code> (instead of the actual value).</p><p>More
4.76 +rules for using such expressions in attributes are straightforward:</p><ul><li>Attributes prefixed with <code>template</code> can contain expressions as one would write them normally.</li><li>Other attributes must have their expressions enclosed between <code>{</code> and <code>}</code> characters so that the expression is evaluated and replaced with the result in the final output.</li></ul><p>Here is a trivial example of the usage of an XPath expression, based on one of the above examples:</p><pre><span template:attribute="some-attribute" template:value="string-length($this-value)">xxx</span></pre><p>In the above example, we invoke the standard XPath function <code>string-length</code> in order to produce within the <code>span</code> element the length of the value of <code>some-attribute</code> (instead of the actual value).</p><p>More
4.77 interesting applications of XPath expressions and non-XSLForms
4.78 functions arise when using more of the potential of XPath to select
4.79 arbitrary elements and attributes and to perform calculations on the
4.80 selected nodes. The following example originates from the Configurator
4.81 -example application:</p><pre><span template:value="sum(/configuration//*[@value-is-set]/@price) + sum(/configuration//*[@value = ../@value]/@price)"></span></pre><p>This complicated expression, to be inserted within the <code>span</code> element, finds all elements in the system configuration having the <code>value-is-set</code>
4.82 +example application:</p><pre><span template:value="sum(/configuration//*[@value-is-set]/@price) + sum(/configuration//*[@value = ../@value]/@price)"></span></pre><p>This complicated expression, to be inserted within the <code>span</code> element, finds all elements in the system configuration having the <code>value-is-set</code>
4.83 attribute and adds their prices together; this total is combined with
4.84 the sum of the prices from all elements marked as selected in their
4.85 respective lists. In other words, it gets the total of all selected
4.86 -components and inserts it into the final output.</p></body></html>
4.87 \ No newline at end of file
4.88 +components and inserts it into the final output.</p></body></html>
5.1 --- a/docs/advice.html Sat Sep 08 16:53:18 2007 +0000
5.2 +++ b/docs/advice.html Sat Sep 08 16:53:34 2007 +0000
5.3 @@ -1,8 +1,8 @@
5.4 +<?xml version="1.0" encoding="iso-8859-1"?>
5.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
5.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
5.8 -
5.9 - <title>Creating Applications: Recommendations and Advice</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
5.10 + <title>Creating Applications: Recommendations and Advice</title>
5.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
5.12 <body>
5.13 <h1>Creating Applications: Recommendations and Advice</h1>
5.14 @@ -15,14 +15,14 @@
5.15 multiple-choice elements like this:</p>
5.16 <pre><multi><br /> <multi-enum value="1"/><br /> <multi-enum value="2"/><br /> <multi-enum value="3"/><br /> <nested value="x"/><br /></multi></pre>
5.17 <p>The reason for this is that the number of multiple-choice values may
5.18 -vary within your application, and the nested elements will appear
5.19 +vary within your application, and the nested elements will appear
5.20 at a different position depending on how many such values have been
5.21 inserted. Whilst this might not affect some applications, at least not
5.22 to begin with, the usage of more advanced features (<a href="in-page-updates.html">in-page updates</a>, for example) will
5.23 probably expose
5.24 problems due to the way XSLForms reconstructs the XML document data
5.25 -from the input form data.</p><p>We can avoid the above mistake by specifying the first parameter in the <code>template:multiple-choice-field</code> and <code>template:multiple-choice-list-field</code> annotations. For example:</p><pre><select name="..." template:multiple-choice-field="multi,multi-enum,value"><br /> <option value="..." template:multiple-choice-value="multi-enum,value,selected"></option><br /></select></pre>
5.26 -<p>This effectively prevents us from inserting the <code>nested</code> element inside the <code>multi</code> element.<br /></p><h2>Beware of Adding Elements into Mixtures of Elements</h2>
5.27 +from the input form data.</p><p>We can avoid the above mistake by specifying the first parameter in the <code>template:multiple-choice-field</code> and <code>template:multiple-choice-list-field</code> annotations. For example:</p><pre><select name="..." template:multiple-choice-field="multi,multi-enum,value"><br /> <option value="..." template:multiple-choice-value="multi-enum,value,selected"></option><br /></select></pre>
5.28 +<p>This effectively prevents us from inserting the <code>nested</code> element inside the <code>multi</code> element.<br /></p><h2>Beware of Adding Elements into Mixtures of Elements</h2>
5.29 <p>Although we ignore this rule with the example in this documentation,
5.30 it is necessary to be aware of problems with adding and removing
5.31 elements where other elements may reside. Consider part of our form
5.32 @@ -30,12 +30,12 @@
5.33 <pre><item value="a"><br /> <type><br /> <type-enum value="1"/><br /> </type><br /> <subitem value="x"/><br /></item></pre>
5.34 <p>Provided that we control the process of adding and removing the
5.35 elements, making sure that they always reside at the end of the element
5.36 -collection inside the <code>item</code> element, and that they
5.37 +collection inside the <code>item</code> element, and that they
5.38 always follow a known number of elements, we can avoid issues with more
5.39 advanced features (<a href="in-page-updates.html">in-page updates</a>,
5.40 -for example), although using such features on the <code>subitem</code>
5.41 +for example), although using such features on the <code>subitem</code>
5.42 elements themselves may cause problems that may only be resolved by
5.43 -moving the <code>subitem</code> elements into a container element
5.44 +moving the <code>subitem</code> elements into a container element
5.45 of their own:</p>
5.46 <pre><item value="a"><br /> <type><br /> <type-enum value="1"/><br /> </type><br /> <subitems><br /> <subitem value="x"/><br /> </subitems><br /></item></pre>
5.47 <h2>Make Sure the Output Structure Agrees with the Template</h2>
5.48 @@ -51,14 +51,14 @@
5.49 page gives the user the opportunity to specify data that is missing.
5.50 Consider this section of an example template:</p>
5.51 <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>
5.52 -<p>Here, if the <code>author</code> element is not found in the
5.53 +<p>Here, if the <code>author</code> element is not found in the
5.54 output structure, no field will be produced in the Web page, no
5.55 opportunity will be given for an author to be specified, and no author
5.56 information will subsequently be editable. One solution is to introduce
5.57 -the <code>author</code> element into the XML document when
5.58 -creating the <code>package</code> element - this should then
5.59 +the <code>author</code> element into the XML document when
5.60 +creating the <code>package</code> element - this should then
5.61 "bootstrap" the process and ensure that the author details will remain
5.62 -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#DocumentInitialisation">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>
5.63 +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#DocumentInitialisation">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>
5.64 elements would still be impossible to create in the user interface. The
5.65 document initialisation mechanism distinguishes between these two cases
5.66 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>
5.67 @@ -69,11 +69,11 @@
5.68 if such information is to be used with such updated data, noting that
5.69 any changes in the structure of the such data will cause the selectors
5.70 to refer to the wrong parts of documents. To make updated documents
5.71 -available to XSLForms, the following call can be made on the <code>form</code> object (the third parameter in the <code>respond_to_form</code> method):</p><pre>form.set_document(document_name, updated_document)</pre><p>The updated selectors can then be obtained as usual:</p><pre>selectors = form.get_selectors()</pre><p>Typically,
5.72 +available to XSLForms, the following call can be made on the <code>form</code> object (the third parameter in the <code>respond_to_form</code> method):</p><pre>form.set_document(document_name, updated_document)</pre><p>The updated selectors can then be obtained as usual:</p><pre>selectors = form.get_selectors()</pre><p>Typically,
5.73 selectors should be accessed and used before initialisation since they
5.74 -refer to information that must already exist and can therefore be
5.75 +refer to information that must already exist and can therefore be
5.76 manipulated without preparatory work being done on the documents
5.77 involved.</p>
5.78 <ol>
5.79 </ol>
5.80 -</body></html>
5.81 \ No newline at end of file
5.82 +</body></html>
6.1 --- a/docs/data.html Sat Sep 08 16:53:18 2007 +0000
6.2 +++ b/docs/data.html Sat Sep 08 16:53:34 2007 +0000
6.3 @@ -1,9 +1,9 @@
6.4 +<?xml version="1.0" encoding="iso-8859-1"?>
6.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6.6 <html xmlns="http://www.w3.org/1999/xhtml">
6.7 <head>
6.8 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
6.9 <title>Creating Applications: Design the Structure of the Form Data</title>
6.10 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
6.11 <link href="styles.css" rel="stylesheet" type="text/css" />
6.12 </head>
6.13 <body>
6.14 @@ -15,7 +15,7 @@
6.15 consider the following hierarchical structure:</p>
6.16
6.17 <ul>
6.18 - <li>A list of items, each containing...<br />
6.19 + <li>A list of items, each containing...<br />
6.20 <ul>
6.21 <li>An editable value.</li>
6.22 <li>A list of subitems, each containing...<br />
7.1 --- a/docs/design.html Sat Sep 08 16:53:18 2007 +0000
7.2 +++ b/docs/design.html Sat Sep 08 16:53:34 2007 +0000
7.3 @@ -1,8 +1,8 @@
7.4 +<?xml version="1.0" encoding="iso-8859-1"?>
7.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
7.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
7.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
7.8 -
7.9 - <title>Creating Applications: Design a Template</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
7.10 + <title>Creating Applications: Design a Template</title>
7.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
7.12 <body>
7.13 <h1>Creating Applications: Design
7.14 @@ -33,7 +33,7 @@
7.15 ill-formed HTML, where start and end tags need not match, will <span style="font-style: italic;">not</span> work with XSL transformations
7.16 and will therefore <span style="font-style: italic;">not</span> work
7.17 with XSLForms.</li>
7.18 - <li>We add a <code>form</code> element to the outline so that
7.19 + <li>We add a <code>form</code> element to the outline so that
7.20 the form fields added later actually perform some function when testing
7.21 our application.</li>
7.22 </ul>
7.23 @@ -49,8 +49,8 @@
7.24 <p>The HTML code which produces this representation might look like
7.25 this:</p>
7.26 <pre><div><br /> <p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /></div></pre>
7.27 -<p>Although we have given names to the different <code>input</code>
7.28 -elements, it
7.29 +<p>Although we have given names to the different <code>input</code>
7.30 +elements, it
7.31 is actually not that important to use the correct names at this stage
7.32 in the development process - the actual names will be added later.</p>
7.33 <p><span style="font-weight: bold;">One important thing to note</span>
7.34 @@ -63,18 +63,18 @@
7.35 similar label, field and button arrangement for each of the subitems.
7.36 For example:</p>
7.37
7.38 - <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
7.39 + <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
7.40 <p>Itself containing more items:</p>
7.41 <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p>
7.42
7.43 <p>This representation might be expressed in HTML as follows:</p>
7.44 <pre><div><br /> <p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /></div><br /></pre>
7.45 -<p>In the above example, the <code>div</code> element encloses the
7.46 +<p>In the above example, the <code>div</code> element encloses the
7.47 outer list item. Meanwhile, the inner list item is itself enclosed
7.48 -within a <code>p</code> element in the same way as the original
7.49 +within a <code>p</code> element in the same way as the original
7.50 example enclosed its simple list item.</p>
7.51 <p><span style="font-weight: bold;">It should be noted</span> that
7.52 -the item and subitem are each defined within single enclosing
7.53 +the item and subitem are each defined within single enclosing
7.54 HTML elements - as noted above, the motivation for this will become
7.55 clear later on.</p>
7.56 <h2>Adding Items and Subitems</h2>
7.57 @@ -84,7 +84,7 @@
7.58 details. For example:
7.59 </p>
7.60
7.61 - <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
7.62 + <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
7.63 <p>Itself containing more items:</p>
7.64 <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p>
7.65 <p><input name="add2" value="Add subitem" type="submit" /></p>
7.66 @@ -94,11 +94,11 @@
7.67 <pre><div><br /> <p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> <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 /></pre>
7.68 <p>In the above example, the new buttons have been added alongside the
7.69 elements which define the subitem and item regions of the template.
7.70 -Thus, the <code>input</code> field called <code>add2</code>
7.71 -which adds subitems is alongside, not inside, the <code>p</code>
7.72 +Thus, the <code>input</code> field called <code>add2</code>
7.73 +which adds subitems is alongside, not inside, the <code>p</code>
7.74 element which defines the subitem region of the template. Likewise,
7.75 -the <code>input</code> field called <code>add</code> which
7.76 -adds items is alongside, not inside, the <code>div</code> element
7.77 +the <code>input</code> field called <code>add</code> which
7.78 +adds items is alongside, not inside, the <code>div</code> element
7.79 which defines the item region of the template.</p>
7.80 <h2>Saving the Template</h2>
7.81 <p>Adding the above modifications to the outline, we end up with the
7.82 @@ -106,7 +106,7 @@
7.83 <pre><?xml version="1.0"?><br /><html xmlns="http://www.w3.org/1999/xhtml"><br /><head><br /> <title>Example</title><br /></head><br /><body><br /><form action="" method="post"><br /><br /><!-- Template text between the start and the interesting part. --><br /><br /><div><br /> <p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /> <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.84 <p>Once you are happy with the
7.85 design of the page, save it to the <a href="directory.html">directory</a>
7.86 -created earlier (perhaps choosing the name <code>structure_template.xhtml</code>),
7.87 -then proceed to <a href="structure.html">adding
7.88 +created earlier (perhaps choosing the name <code>structure_template.xhtml</code>),
7.89 +then proceed to <a href="structure.html">adding
7.90 structure information</a> in the next stage of the <a href="overview.html">process</a>.</p>
7.91 -</body></html>
7.92 \ No newline at end of file
7.93 +</body></html>
8.1 --- a/docs/directory.html Sat Sep 08 16:53:18 2007 +0000
8.2 +++ b/docs/directory.html Sat Sep 08 16:53:34 2007 +0000
8.3 @@ -1,8 +1,8 @@
8.4 +<?xml version="1.0" encoding="iso-8859-1"?>
8.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
8.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
8.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
8.8 -
8.9 - <title>Creating Applications: Create a Directory</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
8.10 + <title>Creating Applications: Create a Directory</title>
8.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
8.12 <body>
8.13 <h1>Creating Applications: Create
8.14 @@ -14,10 +14,7 @@
8.15 <tbody>
8.16 <tr>
8.17 <td width="60%"></td>
8.18 - <th style="text-align: left;" colspan="2" width="40%">Example
8.19 -Directory
8.20 -Structure<br />
8.21 - </th>
8.22 + <th style="text-align: left;" colspan="2" width="40%">Example Directory Structure</th>
8.23 </tr>
8.24 <tr>
8.25 <th style="text-align: right;">A
8.26 @@ -27,7 +24,7 @@
8.27 <td></td>
8.28 </tr>
8.29 <tr>
8.30 - <th style="text-align: right;">A subdirectory
8.31 + <th style="text-align: right;">A subdirectory
8.32 containing non-code resources for the
8.33 application</th>
8.34 <td style="background-color: rgb(204, 204, 255); border-left-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-width: 1px; border-right-width: 1px; border-bottom-width: 1px;"><br />
8.35 @@ -38,10 +35,10 @@
8.36 </tbody>
8.37 </table>
8.38 <p>For the above example, the
8.39 -directory structure would be created using UNIX-style commands
8.40 +directory structure would be created using UNIX-style commands
8.41 as follows:</p>
8.42 <pre>mkdir VerySimple<br />mkdir VerySimple/Resources<br />touch VerySimple/__init__.py</pre>
8.43 <p>It is in the <code>Resources</code>
8.44 subdirectory that we will save
8.45 our template files. First, however, we must undertake some <a href="data.html">data definition</a> as the next activity in the application development <a href="overview.html">process</a>.</p>
8.46 -</body></html>
8.47 \ No newline at end of file
8.48 +</body></html>
9.1 --- a/docs/in-page-updates.html Sat Sep 08 16:53:18 2007 +0000
9.2 +++ b/docs/in-page-updates.html Sat Sep 08 16:53:34 2007 +0000
9.3 @@ -1,8 +1,8 @@
9.4 +<?xml version="1.0" encoding="iso-8859-1"?>
9.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
9.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
9.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
9.8 -
9.9 - <title>Creating Applications: In-Page Updates</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
9.10 + <title>Creating Applications: In-Page Updates</title>
9.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
9.12 <body>
9.13 <h1>Creating Applications: In-Page Updates</h1>
9.14 @@ -14,8 +14,8 @@
9.15 <p>Consider the addition of a comment field to our application. Here is
9.16 how the HTML code might look:</p>
9.17 <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>
9.18 -<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
9.19 -presented in the application in its current state, despite the lack of any <code>options</code> or <code>comment</code>
9.20 +<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
9.21 +presented in the application in its current state, despite the lack of any <code>options</code> or <code>comment</code>
9.22 elements
9.23 manipulated by the
9.24 application, due to the document initialisation mechanism employed by
9.25 @@ -24,9 +24,9 @@
9.26 document had a certain value or state.</p>
9.27 <p>Let us imagine that if the type of an item was set to "Personal",
9.28 the comment field would appear and permit the recording of some text
9.29 -for that item. One approach that would make this possible is to
9.30 +for that item. One approach that would make this possible is to
9.31 add a transformation which checks the type values set for each of the
9.32 -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
9.33 +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
9.34 changes:</p>
9.35 <pre> transform_resources = {<br /> "comments" : ["structure_comments.xsl"]<br /> }</pre>
9.36 <p>What this does is to state that when we carry out the <code>comments</code>
9.37 @@ -37,11 +37,11 @@
9.38 <ol>
9.39 <li>Descend into the form data structure, copying all elements,
9.40 attributes and text that the stylesheet is not programmed to recognise.</li>
9.41 - <li>When encountering an <code>item</code> element (which the
9.42 + <li>When encountering an <code>item</code> element (which the
9.43 stylesheet is programmed to recognise), do the following:<br />
9.44 <ol>
9.45 - <li>Copy the element "skeleton" and its attributes so that
9.46 -the <code>value</code> attribute is retained.</li>
9.47 + <li>Copy the element "skeleton" and its attributes so that
9.48 +the <code>value</code> attribute is retained.</li>
9.49 <li>Produce a new <code>options</code> element and process it.</li>
9.50 </ol>
9.51 </li>
9.52 @@ -49,9 +49,9 @@
9.53 following:<br />
9.54 <ol>
9.55 <li>Inside this new <code>options</code> element, investigate
9.56 -the values associated with the <code>type</code> element.</li>
9.57 +the values associated with the <code>type</code> element.</li>
9.58 <li>If any of the selected type values represents the "Personal" category, make a new <code>comment</code>
9.59 -element, then add any attributes that may be found on
9.60 +element, then add any attributes that may be found on
9.61 existing <code>comment</code> elements within the current <code>type</code>
9.62 element.</li>
9.63 </ol>
9.64 @@ -60,7 +60,7 @@
9.65 <p>Since this stylesheet is used after the document initialisation,
9.66 we may (and even must) take advantage of the results of that activity, including noting that selected values on <code>type-enum</code>
9.67 elements are marked with the <code>value-is-set</code> attribute.</p>
9.68 -<p>The stylesheet source code can be found in <code>examples/Common/VerySimple/Resources/structure_comments.xsl</code>.</p>
9.69 +<p>The stylesheet source code can be found in <code>examples/Common/VerySimple/Resources/structure_comments.xsl</code>.</p>
9.70 <h2>Limitations and Enhancements</h2>
9.71 <p>Whilst the above modifications adds a comment field for each item
9.72 with a type of "Personal", and whilst the comment field will appear and
9.73 @@ -68,7 +68,7 @@
9.74 when items and subitems are added and removed. We could add an update
9.75 button to the page which performs an explicit refresh of the page
9.76 without adding or removing anything, and for the sake of usability, we
9.77 -probably should add such a button (just below the <code>Add item</code>
9.78 +probably should add such a button (just below the <code>Add item</code>
9.79 button):</p>
9.80 <pre><p><br /> <input name="update" type="submit" value="Update" /><br /></p></pre>
9.81 <p>However, we could also add an in-page update to make each comments
9.82 @@ -84,21 +84,21 @@
9.83 surrounding the comment field, annotating the paragraph with the
9.84 following attributes:</p>
9.85 <ul>
9.86 - <li>The <code>template:id</code> attribute is used to define a
9.87 + <li>The <code>template:id</code> attribute is used to define a
9.88 template fragment used only to prepare the updated part of the Web
9.89 page. Here we define the fragment or region as being just this
9.90 paragraph.</li>
9.91 - <li>The standard HTML <code>id</code> attribute is used to
9.92 + <li>The standard HTML <code>id</code> attribute is used to
9.93 define which part of the active Web page will be replaced when
9.94 performing an in-page update. This attribute needs to have a unique
9.95 value, but the easiest basis for such a value is a selector-style
9.96 -reference to the <code>options</code> element within which the <code>comment</code>
9.97 +reference to the <code>options</code> element within which the <code>comment</code>
9.98 element resides.</li>
9.99 </ul>
9.100 -<p>Another change has been to put the <code>template:element</code>
9.101 +<p>Another change has been to put the <code>template:element</code>
9.102 annotation inside the above fragment or region annotations. Had we not
9.103 -done this, the lack of a <code>comment</code> element in the form
9.104 -data could have prevented the <code>id</code> attribute from
9.105 +done this, the lack of a <code>comment</code> element in the form
9.106 +data could have prevented the <code>id</code> attribute from
9.107 appearing in the Web page, this preventing any hope of an in-page
9.108 update since there would be no way of knowing where such an update
9.109 should be applied.</p>
9.110 @@ -107,7 +107,7 @@
9.111 references to scripts must also be added to the template, as shown in
9.112 the following excerpt:</p>
9.113 <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>
9.114 -<p>These special script files can be found in <code>examples/Common/VerySimple/Resources/scripts</code>.</p>
9.115 +<p>These special script files can be found in <code>examples/Common/VerySimple/Resources/scripts</code>.</p>
9.116 <p>Now we can concentrate on adding the event which triggers an in-page
9.117 update. Since it is the type values that cause each comment field to be
9.118 added or removed, we add an event attribute on the form field
9.119 @@ -128,15 +128,15 @@
9.120 'value')}'</span></dt>
9.121 <dd>The fields which are going to be used in the processing of the
9.122 update. Since the presence of the comment field depends on a
9.123 -specific <code>type</code> element and its <code>type-enum</code>
9.124 -elements' <code>value</code> attributes, we specify the names of
9.125 +specific <code>type</code> element and its <code>type-enum</code>
9.126 +elements' <code>value</code> attributes, we specify the names of
9.127 the fields which yield these values.</dd>
9.128 <dt><span style="font-weight: bold;">'{template:other-elements(../options)}'</span></dt>
9.129 <dd>The region which is to be updated. Here, we recall that we
9.130 defined the region using a special reference to the <code>options</code>
9.131 -element holding <code>comment</code> element. Thus, we use a
9.132 +element holding <code>comment</code> element. Thus, we use a
9.133 special value which also refers to that element from the context of
9.134 -the <code>type</code> element.</dd>
9.135 +the <code>type</code> element.</dd>
9.136 <dt><span style="font-weight: bold;">'{template:child-attribute('value',
9.137 template:child-element('comment', 1,
9.138 template:other-elements(../options)))}'</span></dt>
9.139 @@ -178,7 +178,7 @@
9.140 stylesheet filename that will be generated to produce the page
9.141 fragments for such comment regions, along with the region marker that
9.142 we defined above.</p>
9.143 -<p>The <code>respond_to_form</code> method now also includes some
9.144 +<p>The <code>respond_to_form</code> method now also includes some
9.145 additional code:</p>
9.146 <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>
9.147 <p>Here, we find out whether an in-page update is requested, along with
9.148 @@ -191,7 +191,7 @@
9.149 <p>The significant changes begin when presenting the result of the
9.150 request processing:</p>
9.151 <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;"></span><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(in_page_resource)</span><span style="font-weight: bold;"></span><br style="font-weight: bold;" /><span style="font-weight: bold;"> stylesheet_parameters = self.prepare_parameters(parameters)</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")<br /></span> <span style="font-weight: bold;"></span><span style="font-weight: bold;"> stylesheet_parameters = {}</span></pre>
9.152 -<p>Instead of just obtaining a stylesheet for the <code>structure</code>
9.153 +<p>Instead of just obtaining a stylesheet for the <code>structure</code>
9.154 document, we instead check to see if an in-page update is being
9.155 requested and, if so, prepare the stylesheet representing the fragment
9.156 of the Web form to be presented. Additionally, we obtain special
9.157 @@ -203,7 +203,7 @@
9.158 <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>
9.159 <p>In order to introduce the infrastructure mentioned above which
9.160 separates requests for Web pages from requests for JavaScript files, we
9.161 -need to provide a more sophisticated implementation of the <code>get_site</code>
9.162 +need to provide a more sophisticated implementation of the <code>get_site</code>
9.163 function:</p>
9.164 <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>
9.165 <p>What this does is to create a resource for the application, as
9.166 @@ -211,9 +211,9 @@
9.167 which examines the path or URL on the incoming requests and directs
9.168 such requests according to the following scheme:</p>
9.169 <ul>
9.170 - <li>If the request mentions something under <code>scripts</code>
9.171 + <li>If the request mentions something under <code>scripts</code>
9.172 in its URL, we employ the WebStack <code>DirectoryResource</code> to
9.173 -send the file from the <code>scripts</code> subdirectory of the
9.174 +send the file from the <code>scripts</code> subdirectory of the
9.175 application's <code>Resources</code> directory.</li>
9.176 <li>Otherwise, we pass the request on to our application resource in
9.177 order to produce a Web page for the user.</li>
9.178 @@ -222,4 +222,4 @@
9.179 script file; otherwise it gets a Web page showing either all of the
9.180 form (if a normal request is received), or a part of the form (if an
9.181 in-page request is received).</p>
9.182 -</body></html>
9.183 \ No newline at end of file
9.184 +</body></html>
10.1 --- a/docs/index.html Sat Sep 08 16:53:18 2007 +0000
10.2 +++ b/docs/index.html Sat Sep 08 16:53:34 2007 +0000
10.3 @@ -1,7 +1,8 @@
10.4 +<?xml version="1.0" encoding="iso-8859-1"?>
10.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
10.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
10.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
10.8 - <title>Developing Web Applications with XSLTools</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
10.9 + <title>Developing Web Applications with XSLTools</title>
10.10 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
10.11 <body>
10.12 <h1>Developing Web Applications with XSLTools</h1>
10.13 @@ -10,26 +11,26 @@
10.14 libxml2, libxslt and (optionally) <a href="http://www.boddie.org.uk/python/WebStack.html">WebStack</a>.</p>
10.15 <h2>Setting Up</h2>
10.16 <p>First of all, let us assume that the XSLTools distribution has been
10.17 -unpacked and now sits in the <code>XSLTools-0.4.6</code> directory.</p>
10.18 +unpacked and now sits in the <code>XSLTools-0.4.7</code> directory.</p>
10.19 <p>Before we begin, we must make sure that the XSLTools package is
10.20 available
10.21 -to Python. The easiest way to do this is to change into the <code>XSLTools-0.4.6</code> directory and to run the <code>setup.py</code>
10.22 +to Python. The easiest way to do this is to change into the <code>XSLTools-0.4.7</code> directory and to run the <code>setup.py</code>
10.23 script provided with the version of Python you are going to be using
10.24 (possibly as a privileged user like <code>root</code>):</p>
10.25 -<pre>cd XSLTools-0.4.6<br />python setup.py install</pre>
10.26 +<pre>cd XSLTools-0.4.7<br />python setup.py install</pre>
10.27 <p>If you don't want to install XSLTools in this way, or if you can't
10.28 do so
10.29 because you don't have <code>root</code> privileges, you can just make
10.30 sure
10.31 -that the <code>XSLTools-0.4.6</code> directory sits on your
10.32 +that the <code>XSLTools-0.4.7</code> directory sits on your
10.33 <code>PYTHONPATH</code>.</p>
10.34 <h2>Viewing the API Documentation</h2>
10.35 <p>The API documentation for use in conjunction with this
10.36 -guide can be found inside the <a href="../apidocs/index.html"><code>apidocs</code></a>
10.37 -directory within the <code>XSLTools-0.4.6</code> directory. Of course,
10.38 +guide can be found inside the <a href="../apidocs/index.html"><code>apidocs</code></a>
10.39 +directory within the <code>XSLTools-0.4.7</code> directory. Of course,
10.40 it is always possible to view the API documentation
10.41 within Python by importing modules (such as <a href="../apidocs/public/XSLTools.XSLOutput-module.html"><code>XSLTools.XSLOutput</code></a>)
10.42 -and using Python's built-in <code>help</code> function.</p>
10.43 +and using Python's built-in <code>help</code> function.</p>
10.44 <h2>About XSLForms Applications</h2>
10.45 <ul>
10.46 <li><a href="what.html">What are XSLTools and XSLForms?</a></li>
11.1 --- a/docs/internationalisation.html Sat Sep 08 16:53:18 2007 +0000
11.2 +++ b/docs/internationalisation.html Sat Sep 08 16:53:34 2007 +0000
11.3 @@ -1,8 +1,8 @@
11.4 +<?xml version="1.0" encoding="iso-8859-1"?>
11.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
11.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
11.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
11.8 -
11.9 - <title>Internationalisation</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
11.10 + <title>Internationalisation</title>
11.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
11.12 <body>
11.13 <h1>Internationalisation</h1>
11.14 @@ -10,28 +10,28 @@
11.15 document: the usage of different texts, labels or phrases chosen
11.16 according to the languages understood by users of an application. The
11.17 XSLForms toolkit provides two mechanisms for the use of translations
11.18 -and translated phrases:</p><ul><li>The <a href="reference.html#i18n"><code>template:i18n</code></a> attribute, as described in the <a href="reference.html">"Template Attribute Reference"</a> document.</li><li>The <a href="../apidocs/public/XSLForms.Output-module.html#i18n"><code>template:i18n</code></a> extension function, as described in the <a href="../apidocs/public/XSLForms.Output-module.html">extension function API documentation</a>.</li></ul><span style="font-family: sans-serif;"><span style="font-weight: bold;"></span></span><p>Each
11.19 -of the above mechanisms has its own specific purpose in template
11.20 +and translated phrases:</p><ul><li>The <a href="reference.html#i18n"><code>template:i18n</code></a> attribute, as described in the <a href="reference.html">"Template Attribute Reference"</a> document.</li><li>The <a href="../apidocs/public/XSLForms.Output-module.html#i18n"><code>template:i18n</code></a> extension function, as described in the <a href="../apidocs/public/XSLForms.Output-module.html">extension function API documentation</a>.</li></ul><span style="font-family: sans-serif;"><span style="font-weight: bold;"></span></span><p>Each
11.21 +of the above mechanisms has its own specific purpose in template
11.22 documents, and these purposes are described below, along with the
11.23 necessary procedures for initialising and invoking the translation
11.24 mechanisms in an XSLForms application.<br /></p><h2><a name="TranslatingElementContent"></a>Translating Element Content</h2><p>Consider the following document fragment:</p><pre><h1>System Configurator</h1></pre><p>In
11.25 order to translate this to a different language, according to that
11.26 preferred by the user, we must annotate the element containing the text
11.27 -as follows:</p><pre><h1 template:i18n="-">System Configurator</h1></pre><p>Here, we state that the contents on the <code>h1</code> element (the exact text <code>System Configurator</code>)
11.28 +as follows:</p><pre><h1 template:i18n="-">System Configurator</h1></pre><p>Here, we state that the contents on the <code>h1</code> element (the exact text <code>System Configurator</code>)
11.29 will be used to find a suitable translation in a translation dictionary
11.30 (as described below). The anticipated result of applying the annotation
11.31 -would resemble the following output document fragment:</p><pre><h1>Systemkonfigurasjon</h1></pre><p>Consequently,
11.32 -a translation has been inserted in place of the original text. In
11.33 +would resemble the following output document fragment:</p><pre><h1>Systemkonfigurasjon</h1></pre><p>Consequently,
11.34 +a translation has been inserted in place of the original text. In
11.35 cases where no translation could be found, the original contents of the
11.36 element would be preserved.</p><h3>Named Translations</h3><p>It is also possible to employ a
11.37 specific translation as opposed to the text which just happen to reside
11.38 -inside an element; for example:</p><pre><h1 template:i18n="sysconfig">System Configurator</h1></pre><p>Here, instead of taking the exact text <code>System Configurator</code> as the "token" to be used to find a translation, we instead use the token with the name <code>sysconfig</code>. The effect, providing that the translation of <code>sysconfig</code> is <code>Systemkonfigurasjon</code>, would be the same as the result given above.</p><h3>Value Translations</h3><p>In cases where the value being translated is not known before a document is to be displayed, one can either use the <code>template:i18n</code> extension function (as described below), special features of other annotations (such as <code>template:multiple-choice-value</code>), or expression-based translations, where an XPath expression is supplied within the annotation.</p><p>Here is an example for translating a multiple-choice field's values:</p><pre><select template:multiple-choice-field="-,type" name="..." value="..."><br /> <option template:multiple-choice-value="type-enum,type,selected,template:i18n(@type)" value="..."/><br /></select></pre><p>Note that this actually uses the <code>template:i18n</code> extension function in conjunction with the annotation's support for separate labels.</p><p>Here is how this might be done using an expression-based translation:</p><pre><select template:multiple-choice-field="-,type" name="..." value="..."><br /> <option template:i18n="{@type}" template:multiple-choice-value="type-enum,type,selected" value="..."/><br /></select></pre><p>In the above multiple-choice field definition, a range of values are presented that originates from <code>type</code> attributes on a number of <code>type-enum</code>
11.39 +inside an element; for example:</p><pre><h1 template:i18n="sysconfig">System Configurator</h1></pre><p>Here, instead of taking the exact text <code>System Configurator</code> as the "token" to be used to find a translation, we instead use the token with the name <code>sysconfig</code>. The effect, providing that the translation of <code>sysconfig</code> is <code>Systemkonfigurasjon</code>, would be the same as the result given above.</p><h3>Value Translations</h3><p>In cases where the value being translated is not known before a document is to be displayed, one can either use the <code>template:i18n</code> extension function (as described below), special features of other annotations (such as <code>template:multiple-choice-value</code>), or expression-based translations, where an XPath expression is supplied within the annotation.</p><p>Here is an example for translating a multiple-choice field's values:</p><pre><select template:multiple-choice-field="-,type" name="..." value="..."><br /> <option template:multiple-choice-value="type-enum,type,selected,template:i18n(@type)" value="..."/><br /></select></pre><p>Note that this actually uses the <code>template:i18n</code> extension function in conjunction with the annotation's support for separate labels.</p><p>Here is how this might be done using an expression-based translation:</p><pre><select template:multiple-choice-field="-,type" name="..." value="..."><br /> <option template:i18n="{@type}" template:multiple-choice-value="type-enum,type,selected" value="..."/><br /></select></pre><p>In the above multiple-choice field definition, a range of values are presented that originates from <code>type</code> attributes on a number of <code>type-enum</code>
11.40 elements. Instead of just presenting the raw values as the labels for
11.41 the resulting pull-down menu, it is possible to override the
11.42 -underlying <code>template:value</code> mechanism and provide a translation instead.</p><p>See the <a href="reference.html#i18n"><code>template:i18n</code></a> section of the <a href="reference.html">"Template Attribute Reference"</a> document for details of this annotation.</p><h2><a name="TranslatingAttributes"></a>Translating Attributes</h2><p>Consider the following document fragment:</p><pre><input type="submit" name="update" value="Update!"/></pre><p>In order to translate the label of this particular form control to another language, we must modify the <code>value</code> attribute as follows:</p><pre><input type="submit" name="update" value="{template:i18n('Update!')}"/></pre><p>Here,
11.43 +underlying <code>template:value</code> mechanism and provide a translation instead.</p><p>See the <a href="reference.html#i18n"><code>template:i18n</code></a> section of the <a href="reference.html">"Template Attribute Reference"</a> document for details of this annotation.</p><h2><a name="TranslatingAttributes"></a>Translating Attributes</h2><p>Consider the following document fragment:</p><pre><input type="submit" name="update" value="Update!"/></pre><p>In order to translate the label of this particular form control to another language, we must modify the <code>value</code> attribute as follows:</p><pre><input type="submit" name="update" value="{template:i18n('Update!')}"/></pre><p>Here,
11.44 we insert an expression inside the attribute whose result will be
11.45 -inserted in place of the expression. Note that for non-template
11.46 -attributes, the expression must reside between <code>{</code> and <code>}</code> characters for the evaluation to take place. The anticipated result might resemble something like the following:</p><pre><input type="submit" name="update" value="Oppdatér"/></pre><p>Where
11.47 +inserted in place of the expression. Note that for non-template
11.48 +attributes, the expression must reside between <code>{</code> and <code>}</code> characters for the evaluation to take place. The anticipated result might resemble something like the following:</p><pre><input type="submit" name="update" value="Oppdatér"/></pre><p>Where
11.49 no suitable translation can be found for the text passed to the
11.50 function, the submitted text is returned as a result, producing
11.51 something resembling the original, non-translated document fragment.</p><p>See the <a href="../apidocs/public/XSLForms.Output-module.html#i18n"><code>template:i18n</code></a> extension function description in the <a href="../apidocs/public/XSLForms.Output-module.html">extension function API documentation</a> for more details.</p><h2>Initialising and Invoking Translations</h2><p>To
11.52 @@ -41,17 +41,17 @@
11.53 are typically stored in an XML file alongside other resources such as
11.54 templates and documents containing data which are also used to prepare
11.55 the final user-viewable output from an application. For example, one
11.56 -can define a file with the name <code>translations.xml</code> and then insert the following contents into it:</p><pre><?xml version="1.0" encoding="iso-8859-1"?><br /><translations><br /> <locale><br /> <code value="en_GB"/><br /> <code value="en"/><br /> </locale><br /> <locale><br /> <code value="nb_NO"/><br /> <code value="nb"/><br /> <translation value="System Configurator">Systemkonfigurasjon</translation><br /> <translation value="Update!">Oppdatér!</translation><br /> <translation value="Export!">Eksportér!</translation><br /> </locale><br /></translations></pre><p>The structure of any such translations file must resemble the above:</p><ol><li>A top-level <code>translations</code> element containing...</li><li>A number of <code>locale</code> sections, each containing...</li><li>One or more <code>code</code> elements identifying the locale, together with...</li><li>A number of <code>translation</code> elements, each providing a translation for each token.</li></ol><p>In the above example, the locale for <code>en</code> and <code>en_GB</code> have no translations defined; as a result, for any requests for translations in this locale the
11.57 -text already found in the document will be preserved.</p><p>Conversely, in the above example, the locale for <code>nb</code> and <code>nb_NO</code>
11.58 +can define a file with the name <code>translations.xml</code> and then insert the following contents into it:</p><pre><?xml version="1.0" encoding="iso-8859-1"?><br /><translations><br /> <locale><br /> <code value="en_GB"/><br /> <code value="en"/><br /> </locale><br /> <locale><br /> <code value="nb_NO"/><br /> <code value="nb"/><br /> <translation value="System Configurator">Systemkonfigurasjon</translation><br /> <translation value="Update!">Oppdatér!</translation><br /> <translation value="Export!">Eksportér!</translation><br /> </locale><br /></translations></pre><p>The structure of any such translations file must resemble the above:</p><ol><li>A top-level <code>translations</code> element containing...</li><li>A number of <code>locale</code> sections, each containing...</li><li>One or more <code>code</code> elements identifying the locale, together with...</li><li>A number of <code>translation</code> elements, each providing a translation for each token.</li></ol><p>In the above example, the locale for <code>en</code> and <code>en_GB</code> have no translations defined; as a result, for any requests for translations in this locale the
11.59 +text already found in the document will be preserved.</p><p>Conversely, in the above example, the locale for <code>nb</code> and <code>nb_NO</code>
11.60 has some translations defined; as a result, requests for translations
11.61 in this locale will result in the specified translations being
11.62 -returned, provided the token is defined in a <code>value</code> attribute of a <code>translation</code> element; otherwise, the default translation will be employed.</p><p>Note that the default translation, <strong>in contrast to earlier versions of XSLTools</strong>, is defined by the first <code>locale</code> section.
11.63 +returned, provided the token is defined in a <code>value</code> attribute of a <code>translation</code> element; otherwise, the default translation will be employed.</p><p>Note that the default translation, <strong>in contrast to earlier versions of XSLTools</strong>, is defined by the first <code>locale</code> section.
11.64 Thus, in the above example, other locales not mentioned in the
11.65 -translations file will employ the translations associated with the <code>en</code> and <code>en_GB</code> locales.
11.66 +translations file will employ the translations associated with the <code>en</code> and <code>en_GB</code> locales.
11.67 In this case, the text already found in the document will be preserved
11.68 since no translations are explicitly given for that locale.</p><h4>Summary of Selection Algorithm</h4><p>The following algorithm summarises the above description:</p><ol><li>For a requested locale, look for a matching <code>locale</code> section.</li><li>For a matching section, find a translation for a text value; if a translation is found, return it.</li><li>Where
11.69 no matching section or translation is found, find a translation in the
11.70 -first, default section; if a translation is found, return it.</li><li>Where no matching default translation is found, return the original text value.</li></ol><h3><a name="UsingTheTranslations"></a>Using the Translations</h3><p>To make use of such a translation file, the file must first be registered in an application. As described in the <a href="Web-resource.html">"Creating Applications: Write a Web Resource"</a> and <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> documents, we may add the above example to a resource in the <code>document_resources</code> attribute:</p><pre>document_resources = {<br /> "translations" : "translations.xml"<br /> # Other resources are defined here.<br /> }</pre><p>When
11.71 +first, default section; if a translation is found, return it.</li><li>Where no matching default translation is found, return the original text value.</li></ol><h3><a name="UsingTheTranslations"></a>Using the Translations</h3><p>To make use of such a translation file, the file must first be registered in an application. As described in the <a href="Web-resource.html">"Creating Applications: Write a Web Resource"</a> and <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> documents, we may add the above example to a resource in the <code>document_resources</code> attribute:</p><pre>document_resources = {<br /> "translations" : "translations.xml"<br /> # Other resources are defined here.<br /> }</pre><p>When
11.72 producing output for a template which uses internationalisation
11.73 features, we must first obtain a reference to the above document:</p><pre># In the respond_to_form method of an XSLFormsResource...<br />translations_xml = self.prepare_document("translations")</pre><p>Then,
11.74 we must decide which language or locale the output will employ. One way
11.75 @@ -60,8 +60,8 @@
11.76 with the above information in hand, we may now modify the output
11.77 production by adding a document reference (thus permitting the output
11.78 stylesheet to access the translations document) and by specifying the
11.79 -chosen locale with the <code>locale</code> stylesheet parameter:</p><pre># Use the transaction, output stylesheet, form data document, stylesheet parameters<br /># as well as the document reference.<br />self.send_output(trans, [output_xsl], doc, {"locale" : language},<br /> references={"translations" : translations_xml})</pre><p>This
11.80 +chosen locale with the <code>locale</code> stylesheet parameter:</p><pre># Use the transaction, output stylesheet, form data document, stylesheet parameters<br /># as well as the document reference.<br />self.send_output(trans, [output_xsl], doc, {"locale" : language},<br /> references={"translations" : translations_xml})</pre><p>This
11.81 should produce an output document which uses the registered
11.82 translations as much as is possible for the selected language.
11.83 Obviously, a more complicated approach could be used to choose the most
11.84 -appropriate language in the <code>languages</code> list, but such algorithms are not covered here.</p></body></html>
11.85 \ No newline at end of file
11.86 +appropriate language in the <code>languages</code> list, but such algorithms are not covered here.</p></body></html>
12.1 --- a/docs/labels.html Sat Sep 08 16:53:18 2007 +0000
12.2 +++ b/docs/labels.html Sat Sep 08 16:53:34 2007 +0000
12.3 @@ -1,50 +1,50 @@
12.4 +<?xml version="1.0" encoding="iso-8859-1"?>
12.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
12.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
12.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
12.8 -
12.9 - <title>Creating Applications: Labelling Multiple-Choice Values</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
12.10 + <title>Creating Applications: Labelling Multiple-Choice Values</title>
12.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
12.12 <body>
12.13 <h1>Creating Applications: Labelling Multiple-Choice Values</h1>
12.14 <p>When introducing the item type multiple-choice field into the application, we defined the following values:</p><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><p>For
12.15 simple applications with a limited audience, it is often acceptable to
12.16 -use values which are then presented unchanged such that the value <code>Personal</code> is known both inside the application and is also shown to the user as the textual string <code>Personal</code>. However, for other applications there may be good reasons not to show values directly in this way:</p><ol><li>There may be a special internal value which is not descriptive; for example <code>123</code> representing the same concept as <code>Personal</code>.</li><li>The value might be understandable not be understandable to some users; for example, the text <code>Personal</code> may not be understood by users who do not speak or otherwise use the English language.</li></ol><p>We
12.17 +use values which are then presented unchanged such that the value <code>Personal</code> is known both inside the application and is also shown to the user as the textual string <code>Personal</code>. However, for other applications there may be good reasons not to show values directly in this way:</p><ol><li>There may be a special internal value which is not descriptive; for example <code>123</code> representing the same concept as <code>Personal</code>.</li><li>The value might be understandable not be understandable to some users; for example, the text <code>Personal</code> may not be understood by users who do not speak or otherwise use the English language.</li></ol><p>We
12.18 must therefore consider introducing additional label information in
12.19 order to remedy the first case, at least. Consequently, we may modify
12.20 the defined values as follows:</p><pre>?xml version="1.0"?><br /><type><br /> <type-enum value="0">(Not selected)</type-enum><br /> <type-enum value="I">Important</type-enum><br /> <type-enum value="N">Not important</type-enum><br /> <type-enum value="P">Personal</type-enum><br /></type></pre><p>Here,
12.21 we have provided user-visible labels which can now be used by the
12.22 template. A single change to the item type choices list is required to
12.23 include these labels as the visible text in that particular form
12.24 -control whilst maintaining the usage of the internal values:</p><pre> <p><br /> Item type:<br /> <select template:multiple-choice-list-field="type,type-enum,value" name="..." multiple="multiple"<br /> onchange="requestUpdate(<br /> 'comments',<br /> '{template:list-attribute('type-enum', 'value')}',<br /> '{template:other-elements(../options)}',<br /> '{template:child-attribute('value', template:child-element('comment', 1, template:other-elements(../options)))}',<br /> '/structure/item/options')"><br /> <option template:multiple-choice-list-value="type-enum,value,selected<span style="font-weight: bold;">,text()</span>" value="..." /><br /> </select><br /> </p></pre><p>The addition, as described in the <a href="reference.html#multiple-choice-value"><code>template:multiple-choice-value</code></a> and <a href="reference.html#multiple-choice-list-value"><code>template:multiple-choice-list-value</code></a> sections of the <a href="reference.html">"Template Attribute Reference"</a> document, selects the text inside the appropriate <code>type-enum</code> elements and inserts it as a label into each choice in the item type list.</p><ul>
12.25 +control whilst maintaining the usage of the internal values:</p><pre> <p><br /> Item type:<br /> <select template:multiple-choice-list-field="type,type-enum,value" name="..." multiple="multiple"<br /> onchange="requestUpdate(<br /> 'comments',<br /> '{template:list-attribute('type-enum', 'value')}',<br /> '{template:other-elements(../options)}',<br /> '{template:child-attribute('value', template:child-element('comment', 1, template:other-elements(../options)))}',<br /> '/structure/item/options')"><br /> <option template:multiple-choice-list-value="type-enum,value,selected<span style="font-weight: bold;">,text()</span>" value="..." /><br /> </select><br /> </p></pre><p>The addition, as described in the <a href="reference.html#multiple-choice-value"><code>template:multiple-choice-value</code></a> and <a href="reference.html#multiple-choice-list-value"><code>template:multiple-choice-list-value</code></a> sections of the <a href="reference.html">"Template Attribute Reference"</a> document, selects the text inside the appropriate <code>type-enum</code> elements and inserts it as a label into each choice in the item type list.</p><ul>
12.26 </ul><h3>Updating the Web Resource</h3>
12.27 -<p>To update the special WebStack resource, we
12.28 +<p>To update the special WebStack resource, we
12.29 now need to modify a few of the class attributes:</p>
12.30 <pre> template_resources = {<br /> "structure" : ("structure_multivalue_label_template.xhtml", "structure_output.xsl")<br /> }<br /> init_resources = {<br /> "structure" : ("structure_multivalue_label_template.xhtml", "structure_input.xsl")<br /> }<br /> document_resources = {<br /> "types" : "structure_types_label.xml"<br /> }<br /></pre>
12.31 <p>With these adjustments, it should now be possible to see the
12.32 original labels and yet have the application manipulate a separate set
12.33 of internal values.
12.34 Note that it may be necessary to remove the old stylesheet for
12.35 -producing output, <code>structure_output.xsl</code>, so that the updated version of the template is taken into use.</p><h3>Translating Labels</h3><p>Whilst
12.36 +producing output, <code>structure_output.xsl</code>, so that the updated version of the template is taken into use.</p><h3>Translating Labels</h3><p>Whilst
12.37 the above work made it possible to satisfy the first motivation of the
12.38 use of labels - to hide internal values - it did not permit us to
12.39 provide translations for different languages. In fact, there are at
12.40 -least two approaches which could provide labels in multiple languages:</p><ol><li>Define a file containing the <code>types</code> and <code>type-enum</code> elements for each language.</li><li>Use the internationalisation support in XSLForms to translate the labels.</li></ol><p>The
12.41 +least two approaches which could provide labels in multiple languages:</p><ol><li>Define a file containing the <code>types</code> and <code>type-enum</code> elements for each language.</li><li>Use the internationalisation support in XSLForms to translate the labels.</li></ol><p>The
12.42 former approach might work in situations where multiple-choice values
12.43 are obtained from a repository, such as a database, which contains the
12.44 labels for items in each supported language. One can envisage a product
12.45 database, for example, containing product descriptions for each
12.46 language or market, and such information could be extracted in such a
12.47 way that it could be convenient to use many different data files (or to
12.48 -extract the information dynamically, insert it into the form data
12.49 +extract the information dynamically, insert it into the form data
12.50 document, and to provide a reference to the form data document as a
12.51 source of value information).</p><p>Let us concentrate, however, on the
12.52 latter, more convenient approach for our example application. In order
12.53 -to produce translated labels, we must first define a <a href="internationalisation.html#PreparingTheTranslations">translations file</a> as described in the <a href="internationalisation.html">"Internationalisation"</a> document; this file can be saved alongside our other resources with the name <code>translations.xml</code>, and its contents can be defined as follows:</p><pre><?xml version="1.0" encoding="iso-8859-1"?><br /><translations><br /> <locale><br /> <code value="nb"/><br /> <code value="nb_NO"/><br /> <translation value="(Not selected)">(Ikke valgt)</translation><br /> <translation value="Important">Viktig</translation><br /> <translation value="Not important">Ikke viktig</translation><br /> <translation value="Personal">Personlig</translation><br /> </locale><br /></translations></pre><p>To make use of this file, we must add additional references in the Web resource's attributes:</p><pre> document_resources = {<br /> "types" : "structure_types_label.xml",<br /> <span style="font-weight: bold;">"translations" : "translations.xml"</span><br /> }</pre><p>And to introduce the translation mechanisms into the output production, we must modify the resource further:</p><pre> # Complete the response.<br /><br /> <span style="font-weight: bold;">stylesheet_parameters["locale"] = trans.get_content_languages()[0]</span><br /> self.send_output(trans, [trans_xsl], structure, stylesheet_parameters,<br /> <span style="font-weight: bold;">references={"translations" : self.prepare_document("translations")}</span>)</pre><p>Here, we define a <code>locale</code>
12.54 +to produce translated labels, we must first define a <a href="internationalisation.html#PreparingTheTranslations">translations file</a> as described in the <a href="internationalisation.html">"Internationalisation"</a> document; this file can be saved alongside our other resources with the name <code>translations.xml</code>, and its contents can be defined as follows:</p><pre><?xml version="1.0" encoding="iso-8859-1"?><br /><translations><br /> <locale><br /> <code value="nb"/><br /> <code value="nb_NO"/><br /> <translation value="(Not selected)">(Ikke valgt)</translation><br /> <translation value="Important">Viktig</translation><br /> <translation value="Not important">Ikke viktig</translation><br /> <translation value="Personal">Personlig</translation><br /> </locale><br /></translations></pre><p>To make use of this file, we must add additional references in the Web resource's attributes:</p><pre> document_resources = {<br /> "types" : "structure_types_label.xml",<br /> <span style="font-weight: bold;">"translations" : "translations.xml"</span><br /> }</pre><p>And to introduce the translation mechanisms into the output production, we must modify the resource further:</p><pre> # Complete the response.<br /><br /> <span style="font-weight: bold;">stylesheet_parameters["locale"] = trans.get_content_languages()[0]</span><br /> self.send_output(trans, [trans_xsl], structure, stylesheet_parameters,<br /> <span style="font-weight: bold;">references={"translations" : self.prepare_document("translations")}</span>)</pre><p>Here, we define a <code>locale</code>
12.55 parameter for the output stylesheet using the first language specified
12.56 in each user's browser's language preferences. Then, we add a reference
12.57 -to the translations document specified above.</p><p>Finally, we have to change the template to make use of the translations:</p><pre> <p><br /> Item type:<br /> <select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple"><br /> <option template:multiple-choice-list-value="type-enum,value,selected<span style="font-weight: bold;">,template:i18n(text())</span>" value="..." /><br /> </select><br /> </p></pre><p>Note that we use the <a href="../apidocs/public/XSLForms.Output-module.html#i18n"><code>template:i18n</code></a> extension function to modify the text found in each <code>type-enum</code> element in the types document. The usage of this function is described in the <a href="../apidocs/public/XSLForms.Output-module.html">extension function API documentation</a>.</p><p>Now, upon adding items in the application, if the browser is set up appropriately - in this case using <code>Norwegian Bokmål [nb]</code> as the first choice of language - the item types will appear translated in the final output.</p>
12.58 +to the translations document specified above.</p><p>Finally, we have to change the template to make use of the translations:</p><pre> <p><br /> Item type:<br /> <select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple"><br /> <option template:multiple-choice-list-value="type-enum,value,selected<span style="font-weight: bold;">,template:i18n(text())</span>" value="..." /><br /> </select><br /> </p></pre><p>Note that we use the <a href="../apidocs/public/XSLForms.Output-module.html#i18n"><code>template:i18n</code></a> extension function to modify the text found in each <code>type-enum</code> element in the types document. The usage of this function is described in the <a href="../apidocs/public/XSLForms.Output-module.html">extension function API documentation</a>.</p><p>Now, upon adding items in the application, if the browser is set up appropriately - in this case using <code>Norwegian Bokmål [nb]</code> as the first choice of language - the item types will appear translated in the final output.</p>
12.59 <h2>Further Reading</h2>
12.60 <p>Now that we have designed and implemented a simple application, it
12.61 may be worth reading some <a href="advice.html">recommendations</a>
12.62 about developing your own applications.</p>
12.63 -</body></html>
12.64 \ No newline at end of file
12.65 +</body></html>
13.1 --- a/docs/model.html Sat Sep 08 16:53:18 2007 +0000
13.2 +++ b/docs/model.html Sat Sep 08 16:53:34 2007 +0000
13.3 @@ -1,91 +1,44 @@
13.4 +<?xml version="1.0" encoding="iso-8859-1"?>
13.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
13.6 <html xmlns="http://www.w3.org/1999/xhtml">
13.7 <head>
13.8 -
13.9 -
13.10 -
13.11 -
13.12 -
13.13 -
13.14 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
13.15 -
13.16 -
13.17 -
13.18 -
13.19 -
13.20 -
13.21 -
13.22 -
13.23 -
13.24 <title>The XSLForms Conceptual Model</title>
13.25 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
13.26 -
13.27 -
13.28 -
13.29 -
13.30 -
13.31 -
13.32 <link href="styles.css" rel="stylesheet" type="text/css" />
13.33 </head>
13.34 -
13.35 -
13.36 <body>
13.37
13.38 <h1>The XSLForms Conceptual Model</h1>
13.39
13.40 -
13.41 -<p>In applications based on XSLForms, form data is modelled and processed as XML documents as shown in the following diagram:</p>
13.42 +<p>In applications based on XSLForms, form data is modelled and processed as XML documents as shown in the following diagram:</p>
13.43
13.44 <table style="text-align: left; width: 80%;" align="center" border="0" cellpadding="5" cellspacing="5">
13.45 -
13.46 <tbody>
13.47 -
13.48 <tr>
13.49 -
13.50 <td align="undefined" valign="undefined"></td>
13.51 -
13.52 <th style="border: 1px solid rgb(0, 0, 0); background-color: rgb(193, 255, 102); text-align: center; vertical-align: top;">Application<br />
13.53 -
13.54 <span class="method">Starting with an initial XML document...</span></th>
13.55 -
13.56 <th style="text-align: center; vertical-align: top;">XSLForms<br />
13.57 -
13.58 <span class="method">A template is used together with the XML document to produce a Web page...</span></th>
13.59 -
13.60 <th style="border: 1px solid rgb(0, 0, 0); background-color: rgb(255, 204, 255); text-align: center; vertical-align: top;">Browser<br />
13.61 -
13.62 <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>
13.63 -
13.64 </tr>
13.65 -
13.66 <tr>
13.67 -
13.68 <th style="text-align: center; vertical-align: top;">XSLForms<br />
13.69 -
13.70 <span class="method">The incoming form data is converted to an XML document...</span></th>
13.71 -
13.72 <th style="border: 1px solid rgb(0, 0, 0); background-color: rgb(193, 255, 102); text-align: center; vertical-align: top;">Application<br />
13.73 -
13.74 <span class="method">The incoming XML document is processed, validated, and so on...</span></th>
13.75 -
13.76 <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>
13.77 -
13.78 <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>
13.79 -
13.80 </tr>
13.81 -
13.82 -
13.83 </tbody>
13.84 </table>
13.85
13.86 <p>The XSLForms framework therefore performs two main functions:</p>
13.87
13.88 <ul>
13.89 -
13.90 <li>To present XML documents as Web pages containing forms.</li>
13.91 -
13.92 <li>To interpret submitted Web form information and to convert that information to XML.</li>
13.93 -
13.94 </ul>
13.95
13.96 </body>
14.1 --- a/docs/multiple.html Sat Sep 08 16:53:18 2007 +0000
14.2 +++ b/docs/multiple.html Sat Sep 08 16:53:34 2007 +0000
14.3 @@ -1,8 +1,8 @@
14.4 +<?xml version="1.0" encoding="iso-8859-1"?>
14.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
14.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
14.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
14.8 -
14.9 - <title>Creating Applications: Adding Multiple-Choice Fields and Values</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
14.10 + <title>Creating Applications: Adding Multiple-Choice Fields and Values</title>
14.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
14.12 <body>
14.13 <h1>Creating Applications: Adding Multiple-Choice Fields and Values</h1>
14.14 @@ -19,15 +19,15 @@
14.15 or many values presented in a list or menu, we shall first consider the
14.16 case where only a single value can be chosen from such a selection.</p>
14.17 <form method="post" action="" name="single">
14.18 - <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
14.19 + <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
14.20 <p>Item type:
14.21 <select name="type"><option>(Not selected)</option><option>Important</option><option>Not important</option><option>Personal</option></select>
14.22 </p>
14.23 <p>Itself containing more items:</p>
14.24 <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p>
14.25 </form>
14.26 -From the item type list only one value may be selected.
14.27 -<p>Taking the example HTML code from before, we can add a
14.28 +From the item type list only one value may be selected.
14.29 +<p>Taking the example HTML code from before, we can add a
14.30 definition of this new list to the template to produce something
14.31 like this:</p>
14.32 <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>
14.33 @@ -36,15 +36,15 @@
14.34 <ol>
14.35 <li>A paragraph was added to provide some space on the page for the
14.36 field.</li>
14.37 - <li>Inside the paragraph, next to the label text, an HTML <code>select</code>
14.38 + <li>Inside the paragraph, next to the label text, an HTML <code>select</code>
14.39 element was added.</li>
14.40 - <li>The <code>select</code> element is mapped onto the <code>type</code>
14.41 -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>
14.42 + <li>The <code>select</code> element is mapped onto the <code>type</code>
14.43 +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>
14.44 element will contain any chosen value from the list of values displayed in the page.</li>
14.45 - <li>Inside the <code>select</code> element, we include an <code>option</code>
14.46 -element which defines the values which will be presented to users
14.47 -of the form. Here, the special <code>template:multiple-choice-value</code> attribute indicates that the <code>option</code> element maps onto
14.48 -a <code>type-enum</code> element which is not mentioned in our
14.49 + <li>Inside the <code>select</code> element, we include an <code>option</code>
14.50 +element which defines the values which will be presented to users
14.51 +of the form. Here, the special <code>template:multiple-choice-value</code> attribute indicates that the <code>option</code> element maps onto
14.52 +a <code>type-enum</code> element which is not mentioned in our
14.53 revised form data structure above; this will be discussed below.</li>
14.54 </ol>
14.55 <h2>Output Structures</h2>
14.56 @@ -57,23 +57,23 @@
14.57 follows:</p>
14.58 <pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <type value="some type"><br /> <type-enum value="choice #n"/><br /> </type><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre>
14.59 <h3>Presenting the Extra Values</h3>
14.60 -<p>In the template, the <code>option</code> element is presented
14.61 +<p>In the template, the <code>option</code> element is presented
14.62 using a number of special annotations which make more sense when
14.63 considering the above output structure:</p>
14.64 <ul>
14.65 - <li>The <code>template:multiple-choice-value</code> annotation states that the
14.66 - <code>option</code> element maps into the <code>type-enum</code>
14.67 -element, meaning that each <code>type-enum</code> element will be
14.68 + <li>The <code>template:multiple-choice-value</code> annotation states that the
14.69 + <code>option</code> element maps into the <code>type-enum</code>
14.70 +element, meaning that each <code>type-enum</code> element will be
14.71 reproduced as an option inside the list or menu presented in the Web
14.72 form.</li>
14.73 - <li>The <code>template:multiple-choice-value</code> annotation also states that the
14.74 -contents of the <code>option</code> element will correspond to
14.75 -the value of the <code>type-enum</code> element's <code>value</code>
14.76 + <li>The <code>template:multiple-choice-value</code> annotation also states that the
14.77 +contents of the <code>option</code> element will correspond to
14.78 +the value of the <code>type-enum</code> element's <code>value</code>
14.79 attribute.</li>
14.80 - <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.
14.81 + <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.
14.82 </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>
14.83 -<p>The result of this is that the <code>type</code> element in the
14.84 -this example structure fragment...</p>
14.85 +<p>The result of this is that the <code>type</code> element in the
14.86 +this example structure fragment...</p>
14.87 <pre><type value="2"><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>
14.88 <p>...is transformed into something resembling this HTML code:</p>
14.89 <pre><select name="..."><br /> <option value="(Not selected)">(Not selected)</option><br /> <option value="Important" selected="selected">Important</option><br /> <option value="Not important">Not important</option><br /> <option value="Personal">Personal</option><br /></select></pre>
14.90 @@ -92,7 +92,7 @@
14.91 us define a
14.92 document containing all the possible values for the type field:</p>
14.93 <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>
14.94 -<p>We shall refer to this document when inserting the different <code>type-enum</code>
14.95 +<p>We shall refer to this document when inserting the different <code>type-enum</code>
14.96 elements into our input form data structure to produce the output
14.97 structure described above; it can be
14.98 found in <code>examples/Common/VerySimple/Resources/structure_types.xml</code>.</p>
14.99 @@ -106,29 +106,29 @@
14.100 <p>These attributes define the following things:</p>
14.101 <ol>
14.102 <li>A initialisation called <code>structure</code> which links
14.103 -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>
14.104 - <li>A document referred to by the name <code>types</code> which
14.105 -is provided by the <code>structure_types.xml</code> file.</li>
14.106 +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>
14.107 + <li>A document referred to by the name <code>types</code> which
14.108 +is provided by the <code>structure_types.xml</code> file.</li>
14.109 </ol>
14.110 <p>To actually perform the initalisation or merge operation, we need to add a few extra
14.111 -lines of code after the addition and deletion operations in the <code>respond_to_form</code>
14.112 +lines of code after the addition and deletion operations in the <code>respond_to_form</code>
14.113 method:</p>
14.114 <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>
14.115 <p>These lines do the following things:</p>
14.116 <ol>
14.117 - <li>Obtain the stylesheet for the <code>structure</code> initialisation.</li>
14.118 - <li>Obtain the <code>types</code> document containing the
14.119 + <li>Obtain the stylesheet for the <code>structure</code> initialisation.</li>
14.120 + <li>Obtain the <code>types</code> document containing the
14.121 values to be merged into the form data.</li>
14.122 - <li>Take the stylesheet and apply it to the form data, <code>structure</code>,
14.123 -using a reference to the <code>types</code> document containing
14.124 + <li>Take the stylesheet and apply it to the form data, <code>structure</code>,
14.125 +using a reference to the <code>types</code> document containing
14.126 the values.</li>
14.127 </ol>
14.128 -<p>The result of this should be a processed <code>structure</code>
14.129 -document containing the type values for each <code>type</code>
14.130 +<p>The result of this should be a processed <code>structure</code>
14.131 +document containing the type values for each <code>type</code>
14.132 element in that document.</p>
14.133 <h2>Other Multiple-Choice Data</h2>
14.134 <p>We have now added a simple, single-valued multiple-choice field to
14.135 the application. However, many applications often need to obtain <a href="multivalue.html">multivalued multiple-choice data</a>, and this
14.136 kind of information is investigated in the next part of the development
14.137 <a href="overview.html">process</a>.</p>
14.138 -</body></html>
14.139 \ No newline at end of file
14.140 +</body></html>
15.1 --- a/docs/multivalue.html Sat Sep 08 16:53:18 2007 +0000
15.2 +++ b/docs/multivalue.html Sat Sep 08 16:53:34 2007 +0000
15.3 @@ -1,15 +1,15 @@
15.4 +<?xml version="1.0" encoding="iso-8859-1"?>
15.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
15.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
15.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
15.8 -
15.9 - <title>Creating Applications: Adding Multivalued Fields</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
15.10 + <title>Creating Applications: Adding Multivalued Fields</title>
15.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
15.12 <body>
15.13 <h1>Creating Applications: Adding Multivalued Fields</h1>
15.14 <p>Although some applications only require multiple-choice fields where
15.15 only a single value may be chosen, in many situations it is desirable
15.16 to be able to choose an arbitrary number of values for a particular
15.17 -field. However, up to this point, we have been content to
15.18 +field. However, up to this point, we have been content to
15.19 represent form data using a single attribute on a single element to
15.20 represent any given field value. With multivalued fields, we must
15.21 choose a different strategy in using XML to represent such information.</p>
15.22 @@ -23,31 +23,31 @@
15.23 users to select one
15.24 or many values presented in a list or menu.</p>
15.25
15.26 - <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
15.27 + <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
15.28 <p>Item type:
15.29 <select multiple="multiple" name="type"><option>(Not selected)</option><option>Important</option><option>Not important</option><option>Personal</option></select>
15.30 </p>
15.31 <p>Itself containing more items:</p>
15.32 <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p>
15.33
15.34 -From the item type list many value may now be selected.
15.35 -<p>Taking the example HTML code from before, we can add a
15.36 +From the item type list many value may now be selected.
15.37 +<p>Taking the example HTML code from before, we can add a
15.38 definition of this new list to the template to produce something
15.39 like this:</p>
15.40 <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>
15.41 <p>From the previous <a href="multiple.html">single-valued case</a>,
15.42 some crucial changes have been made:</p>
15.43 <ol>
15.44 - <li>The <code>select</code> element remains mapped onto the <code>type</code>
15.45 -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>
15.46 -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>
15.47 -element is created within the <code>type</code>
15.48 -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>
15.49 -elements may be created within the <code>type</code>
15.50 + <li>The <code>select</code> element remains mapped onto the <code>type</code>
15.51 +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>
15.52 +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>
15.53 +element is created within the <code>type</code>
15.54 +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>
15.55 +elements may be created within the <code>type</code>
15.56 element, and each one of them will have a different <code>value</code> attribute.</li>
15.57 - <li>Of course, the <code>select</code> element now has a <code>multiple</code>
15.58 + <li>Of course, the <code>select</code> element now has a <code>multiple</code>
15.59 attribute defined to permit multiple value selections.</li>
15.60 - <li>Inside the <code>select</code> element, the <code>option</code>
15.61 + <li>Inside the <code>select</code> element, the <code>option</code>
15.62 element now employs the <code>template:multiple-choice-list-value</code> annotation.</li>
15.63 </ol>
15.64 <h2>Output Structures</h2>
15.65 @@ -56,7 +56,7 @@
15.66 template. Indeed, the subtle differences cannot be represented in our
15.67 simplistic presentation of the structure:</p>
15.68 <pre><?xml version="1.0"?><br /><structure><br /> <item value="some value"><br /> <type><br /> <type-enum value="some type"/><br /> <type-enum value="some other type"/><br /> </type><br /> <subitem subvalue="some other value"/><br /> </item><br /></structure></pre>
15.69 -<p>In fact, the principal difference arises through the number of <code>type-enum</code>
15.70 +<p>In fact, the principal difference arises through the number of <code>type-enum</code>
15.71 elements that occur in the input, representing the values selected by
15.72 the user, and the number that occur in the output, representing the
15.73 complete range of values available for selection.
15.74 @@ -64,29 +64,29 @@
15.75 <h3>Presenting the Extra Values</h3>
15.76 <p>In most respects, the presentation of the extra values is the same
15.77 as in the single-valued case. The result of the presentation of the
15.78 -extra values is that the <code>type</code> element in the
15.79 -this example structure fragment...</p>
15.80 +extra values is that the <code>type</code> element in the
15.81 +this example structure fragment...</p>
15.82 <pre><type><br /> <type-enum value="(Not selected)"/><br /> <type-enum value="Important" value-is-set="true"/><br /> <type-enum value="Not important" value-is-set="true"/><br /> <type-enum value="Personal"/><br /></type><br /></pre>
15.83 <p>...is transformed into something resembling this HTML code:</p>
15.84 <pre><select name="..." multiple="multiple"><br /> <option value="(Not selected)">(Not selected)</option><br /> <option value="Important" selected="selected">Important</option><br /> <option value="Not important" selected="selected">Not important</option><br /> <option value="Personal">Personal</option><br /></select><br /></pre>
15.85 -<p>Above, the special <code>value-is-set</code>
15.86 +<p>Above, the special <code>value-is-set</code>
15.87 attribute is an XSLForms mechanism to remember which values were set.
15.88 Fortunately, the document initialisation mechanism automatically
15.89 distinguishes between different multiple-choice field types and
15.90 understands where the above approach needs to be employed.</p>
15.91 <ul>
15.92 </ul><h3>Updating the Web Resource</h3>
15.93 -<p>To update the special WebStack resource, we
15.94 +<p>To update the special WebStack resource, we
15.95 now need to modify a few of the class attributes and to add a few
15.96 others:</p>
15.97 <pre> template_resources = {<br /> "structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl")<br /> }<br /></pre>
15.98 <p>With these adjustments, it should now be possible to manipulate the
15.99 items and subitems whilst specifying multiple type values on each item.
15.100 Note that it may be necessary to remove the old stylesheet for
15.101 -producing output, <code>structure_output.xsl</code>, so that the
15.102 +producing output, <code>structure_output.xsl</code>, so that the
15.103 multivalue version of the template is taken into use.</p>
15.104 <h2>Improving the Presented Values</h2>
15.105 -<p>In the application we have been developing, we have been content to show the multiple-choice values as they are known in the application - that is, the application refers to values like <code>Personal</code>
15.106 +<p>In the application we have been developing, we have been content to show the multiple-choice values as they are known in the application - that is, the application refers to values like <code>Personal</code>
15.107 and the same text is shown to users of the application. However, there
15.108 are various situations where this is not desirable, and the <a href="labels.html">usage of separate labels</a> is described in the next section of the development <a href="overview.html">process</a>.</p>
15.109 -</body></html>
15.110 \ No newline at end of file
15.111 +</body></html>
16.1 --- a/docs/overview.html Sat Sep 08 16:53:18 2007 +0000
16.2 +++ b/docs/overview.html Sat Sep 08 16:53:34 2007 +0000
16.3 @@ -1,8 +1,8 @@
16.4 +<?xml version="1.0" encoding="iso-8859-1"?>
16.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
16.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
16.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
16.8 -
16.9 - <title>Creating Applications: An Overview</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
16.10 + <title>Creating Applications: An Overview</title>
16.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
16.12 <body>
16.13 <h1>Creating Applications: An Overview</h1>
16.14 @@ -22,5 +22,5 @@
16.15 <li><a href="multivalue.html">Adding multivalued fields</a></li><li><a href="labels.html">Labelling multiple-choice values</a></li>
16.16 <li><a href="advice.html">Recommendations and advice</a></li>
16.17 <li><a href="in-page-updates.html">Adding in-page updates</a></li>
16.18 -</ol><p>A topic-by-topic guide to XSLTools:</p><ul><li><a href="template-design.html">A guide to template design</a></li><li><a href="internationalisation.html">Internationalisation</a></li><li><a href="advanced.html">Advanced template design</a></li><li><a href="XSLForms-resource.html">Using the XSLFormsResource API</a></li><li>Using Qt Designer to make templates <span style="font-style: italic;">(to be written)</span></li><li>Developing applications for PyQt and the Web <span style="font-style: italic;">(to be written)</span></li></ul><p>Some other resources:</p><ul><li><a href="reference.html">A template attribute reference</a></li><li><a href="../apidocs/public/XSLForms.Output-module.html">A template extension function reference</a></li><li><a href="JavaScript-reference.html">An in-page update JavaScript function reference</a></li></ul>
16.19 -</body></html>
16.20 \ No newline at end of file
16.21 +</ol><p>A topic-by-topic guide to XSLTools:</p><ul><li><a href="template-design.html">A guide to template design</a></li><li><a href="internationalisation.html">Internationalisation</a></li><li><a href="advanced.html">Advanced template design</a></li><li><a href="XSLForms-resource.html">Using the XSLFormsResource API</a></li><li>Using Qt Designer to make templates <span style="font-style: italic;">(to be written)</span></li><li>Developing applications for PyQt and the Web <span style="font-style: italic;">(to be written)</span></li></ul><p>Some other resources:</p><ul><li><a href="reference.html">A template attribute reference</a></li><li><a href="../apidocs/public/XSLForms.Output-module.html">A template extension function reference</a></li><li><a href="JavaScript-reference.html">An in-page update JavaScript function reference</a></li></ul>
16.22 +</body></html>
17.1 --- a/docs/reference.html Sat Sep 08 16:53:18 2007 +0000
17.2 +++ b/docs/reference.html Sat Sep 08 16:53:34 2007 +0000
17.3 @@ -1,14 +1,16 @@
17.4 +<?xml version="1.0" encoding="iso-8859-1"?>
17.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
17.6 -<html xmlns="http://www.w3.org/1999/xhtml"><head> <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /><title>Template Attribute Reference</title>
17.7 -<meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> <link href="styles.css" rel="stylesheet" type="text/css" /></head>
17.8 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
17.9 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /><title>Template Attribute Reference</title>
17.10 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
17.11 <body><h1>Template Attribute Reference</h1>
17.12 <p>This document presents each of the attributes used in
17.13 templates to annotate the structure of the XML documents being
17.14 presented and to modify the final output of the presented document.</p><h2>Basic Annotations</h2><p>The annotation attributes in this section are the most basic of those available. Apart from <code>template:element</code> and <code>template:i18n</code>, it is usually preferable to use the annotations listed in the "Convenience Annotations" section below.</p><h3><a name="element"></a>template:element</h3><p>This
17.15 attribute associates the template element on which it is used with an
17.16 element from the XML document being presented. Matching elements are
17.17 -found from the current position (or context), where the position
17.18 -is updated upon entering a template element with a <code>template:element</code> or <code>template:attribute</code> annotation.</p><p>Example:</p><pre><p template:element="item"><br /> For each item element found, this section is produced.<br /> <span template:element="subitem"><br /> For each subitem element found within an item element, this is produced.<br /> </span><br /> <span template:element="other"><br /> This is produced for each other element found within an item element.<br /> </span><br /></p></pre><p>Example:</p><pre><p template:element="first,second,third"><br /> For each third element found, this section is produced.<br /></p></pre><p>Syntax:</p><pre>element-name1[,element-name2[,...]]</pre><p>Related attributes:</p><ul><li><code>template:init</code></li></ul><h3><a name="attribute"></a>template:attribute</h3><p>This attribute associates the template element on which it is used with an attribute in the XML document being presented.</p><p>Example:</p><pre><p template:element="item"><br /> <span template:attribute="value"><br /> This section is associated with the value attribute of the item element.<br /> To be really useful, we should also use other annotations to produce the value of the attribute.<br /> </span><br /></p></pre><p>Syntax:</p><pre>attribute-name</pre><p>Related attributes:</p><ul><li><code>template:value</code></li><li><code>template:attribute-field</code></li><li><code>template:attribute-button</code></li><li><code>template:attribute-area</code></li><li><code>template:attribute-list-button</code></li></ul><h3><a name="value"></a>template:value</h3><p>This attribute produces, in the final output, the value of part of the XML document being presented.</p><p>Example:</p><pre><p template:element="item"><br /> <span template:attribute="value" template:value="$this-value"><br /> This text will be replaced by the value of the attribute, but the span template element will remain.<br /> </span><br /></p></pre><p>Example:</p><pre><p template:element="item"><br /> <span template:attribute="value" template:value="$this-value" template:effect="replace"><br /> This text and its enclosing span element will be replaced by the value of the attribute.<br /> </span><br /></p></pre><p>Syntax:</p><pre>XPath-expression</pre><p>Here, the underlying XPath mechanisms are exposed, but a number of useful shortcuts are available:</p><ul><li><code>$this-value</code> produces the value of the current position (or context) in the XML document being presented.</li><li><code>template:this-attribute()</code> produces a reference to the current attribute (or context).</li></ul>Other XPath expressions can be used to navigate from the current position to other nodes in the XML document.<p>Related attributes:</p><ul><li><code>template:effect</code></li></ul><h3><a name="effect"></a>template:effect</h3><p>This attribute modifies the effect of a <code>template:value</code> annotation.</p><p>Example:</p><p>(See above.)</p><p>Syntax:</p><pre><span style="font-weight: bold;">insert</span>|<span style="font-weight: bold;">replace</span></pre><p>Related attributes:</p><ul><li><code>template:effect</code></li><li><code>template:attribute-area</code></li></ul><h3><a name="if"></a>template:if</h3><p>This
17.19 +found from the current position (or context), where the position
17.20 +is updated upon entering a template element with a <code>template:element</code> or <code>template:attribute</code> annotation.</p><p>Example:</p><pre><p template:element="item"><br /> For each item element found, this section is produced.<br /> <span template:element="subitem"><br /> For each subitem element found within an item element, this is produced.<br /> </span><br /> <span template:element="other"><br /> This is produced for each other element found within an item element.<br /> </span><br /></p></pre><p>Example:</p><pre><p template:element="first,second,third"><br /> For each third element found, this section is produced.<br /></p></pre><p>Syntax:</p><pre>element-name1[,element-name2[,...]]</pre><p>Related attributes:</p><ul><li><code>template:init</code></li></ul><h3><a name="attribute"></a>template:attribute</h3><p>This attribute associates the template element on which it is used with an attribute in the XML document being presented.</p><p>Example:</p><pre><p template:element="item"><br /> <span template:attribute="value"><br /> This section is associated with the value attribute of the item element.<br /> To be really useful, we should also use other annotations to produce the value of the attribute.<br /> </span><br /></p></pre><p>Syntax:</p><pre>attribute-name</pre><p>Related attributes:</p><ul><li><code>template:value</code></li><li><code>template:attribute-field</code></li><li><code>template:attribute-button</code></li><li><code>template:attribute-area</code></li><li><code>template:attribute-list-button</code></li></ul><h3><a name="value"></a>template:value</h3><p>This attribute produces, in the final output, the value of part of the XML document being presented.</p><p>Example:</p><pre><p template:element="item"><br /> <span template:attribute="value" template:value="$this-value"><br /> This text will be replaced by the value of the attribute, but the span template element will remain.<br /> </span><br /></p></pre><p>Example:</p><pre><p template:element="item"><br /> <span template:attribute="value" template:value="$this-value" template:effect="replace"><br /> This text and its enclosing span element will be replaced by the value of the attribute.<br /> </span><br /></p></pre><p>Syntax:</p><pre>XPath-expression</pre><p>Here, the underlying XPath mechanisms are exposed, but a number of useful shortcuts are available:</p><ul><li><code>$this-value</code> produces the value of the current position (or context) in the XML document being presented.</li><li><code>template:this-attribute()</code> produces a reference to the current attribute (or context).</li></ul>Other XPath expressions can be used to navigate from the current position to other nodes in the XML document.<p>Related attributes:</p><ul><li><code>template:effect</code></li></ul><h3><a name="effect"></a>template:effect</h3><p>This attribute modifies the effect of a <code>template:value</code> annotation.</p><p>Example:</p><p>(See above.)</p><p>Syntax:</p><pre><span style="font-weight: bold;">insert</span>|<span style="font-weight: bold;">replace</span></pre><p>Related attributes:</p><ul><li><code>template:effect</code></li><li><code>template:attribute-area</code></li></ul><h3><a name="if"></a>template:if</h3><p>This
17.21 attribute permits the inclusion of a section of the template document
17.22 according to a test performed on the XML document being presented.</p><p>Example:</p><pre><p template:if="@value = 'true'"><br /> If the value attribute is set to the string value 'true', include this section.<br /></p></pre><p>Syntax:</p><pre>XPath-expression</pre><p>Here,
17.23 the underlying XPath mechanisms are exposed, and any XPath expression
17.24 @@ -16,24 +18,24 @@
17.25 attribute is used to translate the textual contents of an element to
17.26 another language where additional parameters specifying the language
17.27 and the whereabouts of the translations have been provided to the
17.28 -stylesheet in the output generation process.</p><p>Example:</p><pre><span template:i18n="-">Hello</span></pre><p>In this example, the contents of the <code>span</code> element would be replaced with an appropriate translation for the text <code>Hello</code><span></span>.</p><p>Example:</p><pre><span template:i18n="hello">Hello</span></pre><p>In this example, the contents of the <code>span</code> element would be replaced with an appropriate translation using the token <code>hello</code><span></span> as a key in the translation dictionary.</p><p>Example:</p><pre><span template:i18n="{$this-value}">Hello</span></pre><p>In this example, the value of the special template variable <code>$this-value</code> is used as a key in the translation dictionary.</p><p>Syntax:</p><pre><span style="font-weight: bold;">-</span>|<span style="font-weight: bold;">{</span>expression<span style="font-weight: bold;">}</span>|token</pre><p>See the <a href="internationalisation.html">"Internationalisation"</a> document for more information on this attribute.</p><h2>Initialisation Annotations</h2><p>The annotation attributes in this section control the initialisation of documents where this is done by the XSLForms toolkit.</p><h3><a name="init"></a>template:init</h3><p>This attribute controls the creation of elements in the initialisation process and is used together with <code>template:element</code>. For each element name listed in a <code>template:element</code> annotation, the corresponding value in a <code>template:init</code> annotation states whether or how such elements are to be initialised.</p><p>Example:</p><pre><p template:element="item" template:init="no"><br /> Such item elements will not be created automatically when the document is initialised.<br /></p></pre><p>Example:</p><pre><p template:element="first,second,third" template:init="yes,yes,no"><br /> The first and second elements will be created automatically when the document is initialised.<br /> No third elements will be created automatically when the document is initialised.<br /></p></pre><p>Syntax:</p><pre><span style="font-weight: bold;">yes</span>|<span style="font-weight: bold;">no</span>|<span style="font-weight: bold;">auto</span>[,<span style="font-weight: bold;">yes</span>|<span style="font-weight: bold;">no</span>|<span style="font-weight: bold;">auto</span>[,...]]</pre><p>Here, <code>yes</code> means that an element will be created automatically, <code>no</code> means that an element will not be created automatically (relying on the existence of such elements from before), and <code>auto</code>
17.29 +stylesheet in the output generation process.</p><p>Example:</p><pre><span template:i18n="-">Hello</span></pre><p>In this example, the contents of the <code>span</code> element would be replaced with an appropriate translation for the text <code>Hello</code><span></span>.</p><p>Example:</p><pre><span template:i18n="hello">Hello</span></pre><p>In this example, the contents of the <code>span</code> element would be replaced with an appropriate translation using the token <code>hello</code><span></span> as a key in the translation dictionary.</p><p>Example:</p><pre><span template:i18n="{$this-value}">Hello</span></pre><p>In this example, the value of the special template variable <code>$this-value</code> is used as a key in the translation dictionary.</p><p>Syntax:</p><pre><span style="font-weight: bold;">-</span>|<span style="font-weight: bold;">{</span>expression<span style="font-weight: bold;">}</span>|token</pre><p>See the <a href="internationalisation.html">"Internationalisation"</a> document for more information on this attribute.</p><h2>Initialisation Annotations</h2><p>The annotation attributes in this section control the initialisation of documents where this is done by the XSLForms toolkit.</p><h3><a name="init"></a>template:init</h3><p>This attribute controls the creation of elements in the initialisation process and is used together with <code>template:element</code>. For each element name listed in a <code>template:element</code> annotation, the corresponding value in a <code>template:init</code> annotation states whether or how such elements are to be initialised.</p><p>Example:</p><pre><p template:element="item" template:init="no"><br /> Such item elements will not be created automatically when the document is initialised.<br /></p></pre><p>Example:</p><pre><p template:element="first,second,third" template:init="yes,yes,no"><br /> The first and second elements will be created automatically when the document is initialised.<br /> No third elements will be created automatically when the document is initialised.<br /></p></pre><p>Syntax:</p><pre><span style="font-weight: bold;">yes</span>|<span style="font-weight: bold;">no</span>|<span style="font-weight: bold;">auto</span>[,<span style="font-weight: bold;">yes</span>|<span style="font-weight: bold;">no</span>|<span style="font-weight: bold;">auto</span>[,...]]</pre><p>Here, <code>yes</code> means that an element will be created automatically, <code>no</code> means that an element will not be created automatically (relying on the existence of such elements from before), and <code>auto</code>
17.30 means that the initialisation process will attempt to guess whether an
17.31 element should be created automatically (by looking for selectors which
17.32 use the element's name and only creating elements where no such
17.33 -selectors could be found). Where no values are provided, <code>auto</code> is assumed.</p><p>Related attributes:</p><ul><li><code>template:element</code></li></ul><h2>Convenience Annotations</h2><p>The
17.34 +selectors could be found). Where no values are provided, <code>auto</code> is assumed.</p><p>Related attributes:</p><ul><li><code>template:element</code></li></ul><h2>Convenience Annotations</h2><p>The
17.35 annotation attributes in this section provide more convenient ways of
17.36 presenting the XML document information in the final output.</p><h3><a name="attribute-field"></a>template:attribute-field</h3><p>This
17.37 attribute associates the template element on which it is used with an
17.38 attribute from the XML document, whilst providing certain other
17.39 -attributes in the final output:</p><ul><li>The <code>name</code> attribute is used to identify the location of the attribute in the XML document being presented.</li><li>The <code>value</code> attribute is used to present the value of the attribute from the XML document.</li></ul><p>Example:</p><pre><input template:attribute-field="name" name="..." value="..." type="text"/></pre><p>This would be output as follows:</p><pre><input name="path-to-name" value="value-of-name" type="text"/></pre><p>...where <code>path-to-name</code> and <code>value-of-name</code> would be replaced with the appropriate computed values.</p><p>Syntax:</p><pre>attribute-name</pre><p>Related attributes:</p><ul><li><code>template:attribute-area</code></li><li><code>template:attribute-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li></ul><h3><a name="attribute-area"></a>template:attribute-area</h3><p>This
17.40 +attributes in the final output:</p><ul><li>The <code>name</code> attribute is used to identify the location of the attribute in the XML document being presented.</li><li>The <code>value</code> attribute is used to present the value of the attribute from the XML document.</li></ul><p>Example:</p><pre><input template:attribute-field="name" name="..." value="..." type="text"/></pre><p>This would be output as follows:</p><pre><input name="path-to-name" value="value-of-name" type="text"/></pre><p>...where <code>path-to-name</code> and <code>value-of-name</code> would be replaced with the appropriate computed values.</p><p>Syntax:</p><pre>attribute-name</pre><p>Related attributes:</p><ul><li><code>template:attribute-area</code></li><li><code>template:attribute-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li></ul><h3><a name="attribute-area"></a>template:attribute-area</h3><p>This
17.41 attribute associates the template element on which it is used with an
17.42 attribute from the XML document being presented, much in the way
17.43 -that <code>template:attribute-field</code> does. However, the
17.44 +that <code>template:attribute-field</code> does. However, the
17.45 attribute value is not inserted into an attribute in the final output;
17.46 instead it is inserted into the output in a different way according to
17.47 -additional information specified in the annotation.</p><p>Example:</p><pre><textarea template:attribute-area="name" name="..." cols="40" rows="5"><br /> This text will be replaced by the value of the name attribute from the document being presented.<br /> The textarea element will enclose the attribute value in the final output.<br /></textarea></pre><p>Example:</p><pre><p><br /> The name is:<br /> <span template:attribute-area="name,replace"><br /> This text will be replaced in the final output, and the span element will not be reproduced.<br /> </span><br /></p></pre><p>Syntax:</p><pre>attribute-name[,<span style="font-weight: bold;">insert</span>|<span style="font-weight: bold;">replace</span>]</pre><p>By default, the value of <code>attribute-name</code> is inserted within the template element on which the annotation appears, and this is equivalent to specifying <code>insert</code>. If <code>replace</code> is specified, the template element is entirely replaced by the value of <code>attribute-name</code>.</p><p>Related attributes:</p><ul><li><code>template:attribute-field</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li></ul><h3><a name="attribute-button"></a>template:attribute-button</h3><p>This attribute associates the template element on which it is used
17.48 +additional information specified in the annotation.</p><p>Example:</p><pre><textarea template:attribute-area="name" name="..." cols="40" rows="5"><br /> This text will be replaced by the value of the name attribute from the document being presented.<br /> The textarea element will enclose the attribute value in the final output.<br /></textarea></pre><p>Example:</p><pre><p><br /> The name is:<br /> <span template:attribute-area="name,replace"><br /> This text will be replaced in the final output, and the span element will not be reproduced.<br /> </span><br /></p></pre><p>Syntax:</p><pre>attribute-name[,<span style="font-weight: bold;">insert</span>|<span style="font-weight: bold;">replace</span>]</pre><p>By default, the value of <code>attribute-name</code> is inserted within the template element on which the annotation appears, and this is equivalent to specifying <code>insert</code>. If <code>replace</code> is specified, the template element is entirely replaced by the value of <code>attribute-name</code>.</p><p>Related attributes:</p><ul><li><code>template:attribute-field</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li></ul><h3><a name="attribute-button"></a>template:attribute-button</h3><p>This attribute associates the template element on which it is used
17.49 with an attribute from the XML document, whilst providing certain other
17.50 -attributes in the final output, much like <code>template:attribute-field</code> does, but with features which make the presentation of buttons and related user interface controls much simpler:</p><ul><li>The <code>name</code> attribute is used to identify the location of the attribute in the XML document being presented.</li><li>The <code>value</code> attribute is used to present a specified value associated with the button being activated.</li><li>An additional named attribute is used to indicate whether the button was activated or set.</li></ul><p>Example:</p><pre><input template:attribute-button="question-type,text,checked" name="..." value="..." type="radio"/></pre><p>This would produce a "radio" button like the following:</p><pre><input name="path-to-question-type" value="text" type="radio"/></pre><p>If the value of <code>question-type</code> was set to text, output like the following would be produced:</p><pre><input name="path-to-question-type" value="text" type="radio" checked="checked"/></pre><p>In an XHTML document, this would cause the "radio" button to appear selected or activated.</p><p>Syntax:</p><pre>attribute-name,attribute-value,attribute-to-create-when-set</pre><p>Related attributes:</p><ul><li><code>template:attribute-field</code></li><li><code>template:attribute-list-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li></ul><h3><a name="selector-field"></a>template:selector-field</h3><p>This
17.51 +attributes in the final output, much like <code>template:attribute-field</code> does, but with features which make the presentation of buttons and related user interface controls much simpler:</p><ul><li>The <code>name</code> attribute is used to identify the location of the attribute in the XML document being presented.</li><li>The <code>value</code> attribute is used to present a specified value associated with the button being activated.</li><li>An additional named attribute is used to indicate whether the button was activated or set.</li></ul><p>Example:</p><pre><input template:attribute-button="question-type,text,checked" name="..." value="..." type="radio"/></pre><p>This would produce a "radio" button like the following:</p><pre><input name="path-to-question-type" value="text" type="radio"/></pre><p>If the value of <code>question-type</code> was set to text, output like the following would be produced:</p><pre><input name="path-to-question-type" value="text" type="radio" checked="checked"/></pre><p>In an XHTML document, this would cause the "radio" button to appear selected or activated.</p><p>Syntax:</p><pre>attribute-name,attribute-value,attribute-to-create-when-set</pre><p>Related attributes:</p><ul><li><code>template:attribute-field</code></li><li><code>template:attribute-list-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li></ul><h3><a name="selector-field"></a>template:selector-field</h3><p>This
17.52 attribute permits the definition of references to the parts of the XML
17.53 document being presented which are associated with the template
17.54 elements in which it is used. When used in certain HTML form-related
17.55 @@ -49,41 +51,41 @@
17.56 attribute associates the template element on which it is used with an
17.57 attribute in the XML document being presented whose value is to be
17.58 chosen from a list of possibilities. The list itself is represented by
17.59 -a list of elements, each having an attribute with a distinct
17.60 -value; such information is added in the initialisation of the
17.61 +a list of elements, each having an attribute with a distinct
17.62 +value; such information is added in the initialisation of the
17.63 document before it is presented, since it is not part of the
17.64 -"essential" information in the document.</p><p>Example:</p><pre><select template:multiple-choice-field="base-system,value" name="..."><br /> ...<br /></select></pre><p>Example:</p><pre><select template:multiple-choice-field="-,question-type" name="..."><br /> ...<br /></select></pre><p>See below for an example combining this attribute with the <code>template:multiple-choice-value</code> attribute.</p><p>Syntax:</p><pre>element-name|<span style="font-weight: bold;">-</span>,attribute-name[,<span style="font-weight: bold;">new</span>|,<span style="font-weight: bold;">new</span>,<span style="font-weight: bold;">dynamic</span>|,,<span style="font-weight: bold;">dynamic</span>]</pre><p>Where the special value <code>-</code>
17.65 +"essential" information in the document.</p><p>Example:</p><pre><select template:multiple-choice-field="base-system,value" name="..."><br /> ...<br /></select></pre><p>Example:</p><pre><select template:multiple-choice-field="-,question-type" name="..."><br /> ...<br /></select></pre><p>See below for an example combining this attribute with the <code>template:multiple-choice-value</code> attribute.</p><p>Syntax:</p><pre>element-name|<span style="font-weight: bold;">-</span>,attribute-name[,<span style="font-weight: bold;">new</span>|,<span style="font-weight: bold;">new</span>,<span style="font-weight: bold;">dynamic</span>|,,<span style="font-weight: bold;">dynamic</span>]</pre><p>Where the special value <code>-</code>
17.66 is given as the element name, the context element is chosen as the
17.67 element in the XML document being presented whose attribute is
17.68 -involved. Where the optional parameter <code>new</code> is given, the attribute is assumed not to already exist on the element. Where the optional parameter <code>dynamic</code> is given, the source of the multiple-choice values is considered to be found dynamically rather than from another document.</p><p>Related attributes:</p><ul><li><code>template:multiple-choice-value</code></li><li><code>template:multiple-choice-list-field</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:element</code></li><li><code>template:attribute</code></li></ul><h3><a name="multiple-choice-value"></a>template:multiple-choice-value</h3><p>This
17.69 +involved. Where the optional parameter <code>new</code> is given, the attribute is assumed not to already exist on the element. Where the optional parameter <code>dynamic</code> is given, the source of the multiple-choice values is considered to be found dynamically rather than from another document.</p><p>Related attributes:</p><ul><li><code>template:multiple-choice-value</code></li><li><code>template:multiple-choice-list-field</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:element</code></li><li><code>template:attribute</code></li></ul><h3><a name="multiple-choice-value"></a>template:multiple-choice-value</h3><p>This
17.70 attribute associates the template element on which it is used with an
17.71 element in the XML document being presented whose purpose is to hold
17.72 one of a list of selectable values (as described above).</p><p>Example:</p><pre><select template:multiple-choice-field="base-system,value" name="..."><br /> <option template:multiple-choice-value="base-system-enum,value,selected" value="..."/><br /></select></pre><p>This presents the following document fragment:</p><pre><base-system value="c"><br /> <base-system-enum value="a"/><br /> <base-system-enum value="b"/><br /> <base-system-enum value="c"/><br /></base-system></pre><p>The output from the combination of the above would be as follows:</p><pre><select name="path-to-base-system"><br /> <option value="a">a</option><br /> <option value="b">b</option><br /> <option value="c" selected="selected">c</option><br /></select></pre><h4>Values and Labels</h4><p>Labels different from the actual values employed can be specified using an extra parameter in the annotation:</p><pre><select template:multiple-choice-field="base-system,value" name="..."><br /> <option template:multiple-choice-value="base-system-enum,value,selected,text()" value="..."/><br /></select></pre><p>This
17.73 additional parameter is an XPath expression whose context is the
17.74 current value-bearing element. The above example selects the text from
17.75 -inside each <code>base-system-enum</code> element in the modified document fragment presented below.</p><p>A modified document fragment providing the labels can be written as follows:</p><pre><base-system value="c"><br /> <base-system-enum value="a">A</base-system-enum><br /> <base-system-enum value="b">B</base-system-enum><br /> <base-system-enum value="c">C</base-system-enum><br /></base-system></pre><p>The output from the modified combination would be as follows:</p><pre><select name="path-to-base-system"><br /> <option value="a">A</option><br /> <option value="b">B</option><br /> <option value="c" selected="selected">C</option><br /></select></pre><p>Syntax:</p><pre>list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]</pre><p>Related attributes:</p><ul><li><code>template:multiple-choice-field</code></li><li><code>template:multiple-choice-list-value</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:element</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li><li><code>template:value</code></li></ul><h3><a name="multiple-choice-list-field"></a>template:multiple-choice-list-field</h3><p>This attribute is similar to <code>template:multiple-choice-field</code>
17.76 +inside each <code>base-system-enum</code> element in the modified document fragment presented below.</p><p>A modified document fragment providing the labels can be written as follows:</p><pre><base-system value="c"><br /> <base-system-enum value="a">A</base-system-enum><br /> <base-system-enum value="b">B</base-system-enum><br /> <base-system-enum value="c">C</base-system-enum><br /></base-system></pre><p>The output from the modified combination would be as follows:</p><pre><select name="path-to-base-system"><br /> <option value="a">A</option><br /> <option value="b">B</option><br /> <option value="c" selected="selected">C</option><br /></select></pre><p>Syntax:</p><pre>list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]</pre><p>Related attributes:</p><ul><li><code>template:multiple-choice-field</code></li><li><code>template:multiple-choice-list-value</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:element</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li><li><code>template:value</code></li></ul><h3><a name="multiple-choice-list-field"></a>template:multiple-choice-list-field</h3><p>This attribute is similar to <code>template:multiple-choice-field</code>
17.77 except that it associates the template element on which it is used with
17.78 an element in the XML document being presented containing a list
17.79 -of elements whose values have been selected. This list of selected
17.80 +of elements whose values have been selected. This list of selected
17.81 elements is expanded before presentation to include elements whose
17.82 values have not been selected. Consequently, the selected elements are
17.83 marked in a particular way to distinguish them from the non-selected
17.84 -elements.</p><p>Example:</p><pre><select template:multiple-choice-list-field="question-types,question-type-enum,question-type" name="..." multiple="multiple"><br /> ...<br /></select></pre><p>See below for an example combining this attribute with the <code>template:multiple-choice-list-value</code> attribute.</p><p>Syntax:</p><pre>element-name|<span style="font-weight: bold;">-</span>,list-element-name,list-attribute-name[,<span style="font-weight: bold;">dynamic</span>]</pre><p>Here, <code>element-name</code> is the element in the document being presented which contains the selected value elements; if the special value <code>-</code> is given then the context element is the element containing the selected value elements. The <code>list-element-name</code> and <code>list-attribute-name</code> indicate the details of the elements providing the list of selectable values. Where the optional parameter <code>dynamic</code> is given, the source of the multiple-choice values is considered to be found dynamically rather than from another document.</p><p>Related attributes:</p><ul><li><code>template:multiple-choice-list-value</code></li><li><code>template:multiple-choice-list-element</code></li><li><code>template:multiple-choice-field</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:element</code></li></ul><h3><a name="multiple-choice-list-value"></a>template:multiple-choice-list-value</h3><p>This attribute is similar to <code>template:multiple-choice-value</code>
17.85 +elements.</p><p>Example:</p><pre><select template:multiple-choice-list-field="question-types,question-type-enum,question-type" name="..." multiple="multiple"><br /> ...<br /></select></pre><p>See below for an example combining this attribute with the <code>template:multiple-choice-list-value</code> attribute.</p><p>Syntax:</p><pre>element-name|<span style="font-weight: bold;">-</span>,list-element-name,list-attribute-name[,<span style="font-weight: bold;">dynamic</span>]</pre><p>Here, <code>element-name</code> is the element in the document being presented which contains the selected value elements; if the special value <code>-</code> is given then the context element is the element containing the selected value elements. The <code>list-element-name</code> and <code>list-attribute-name</code> indicate the details of the elements providing the list of selectable values. Where the optional parameter <code>dynamic</code> is given, the source of the multiple-choice values is considered to be found dynamically rather than from another document.</p><p>Related attributes:</p><ul><li><code>template:multiple-choice-list-value</code></li><li><code>template:multiple-choice-list-element</code></li><li><code>template:multiple-choice-field</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:element</code></li></ul><h3><a name="multiple-choice-list-value"></a>template:multiple-choice-list-value</h3><p>This attribute is similar to <code>template:multiple-choice-value</code>
17.86 in that it associates the template element on which it is used with an
17.87 element holding a value in a list of selectable values, with the
17.88 principal difference that potentially many such values may be selected
17.89 in this case.</p><p>Example:</p><pre><select template:multiple-choice-list-field="question-types,question-type-enum,question-type" multiple="multiple"><br /> <option template:multiple-choice-list-value="question-type-enum,question-type,selected" value="..."/><br /></select></pre><p>This presents the following document fragment:</p><pre><question-types><br /> <question-type-enum question-type="text"/><br /> <question-type-enum question-type="choice" value-is-set="true"/><br /> <question-type-enum question-type="special" value-is-set="true"/><br /></question-types></pre><p>The output from the combination of the above would be as follows:</p><pre><select name="path-to-question-types" multiple="multiple"><br /> <option value="text">text</option><br /> <option value="choice" selected="selected">choice</option><br /> <option value="special" selected="selected">special</option><br /></select></pre><h4>Values and Labels</h4><p>Labels different from the actual values employed can be specified using an extra parameter in the annotation:</p><pre><select template:multiple-choice-list-field="question-types,question-type-enum,question-type" multiple="multiple"><br /> <option template:multiple-choice-list-value="question-type-enum,question-type,selected,text()" value="..."/><br /></select></pre><p>This additional parameter is an XPath expression whose context is
17.90 the current value-bearing element. The above example selects the text
17.91 -from inside each <code>base-system-enum</code> element in the modified document fragment presented below.</p><p>A modified document fragment providing the labels can be written as follows:</p><pre><question-types><br /> <question-type-enum question-type="text">Text</question-type-enum><br /> <question-type-enum question-type="choice" value-is-set="true">Choice</question-type-enum><br /> <question-type-enum question-type="special" value-is-set="true">Special</question-type-enum><br /></question-types></pre><p>The output from the modified combination would be as follows:</p><pre><select name="path-to-question-types" multiple="multiple"><br /> <option value="text">Text</option><br /> <option value="choice" selected="selected">Choice</option><br /> <option value="special" selected="selected">Special</option><br /></select></pre><p>Syntax:</p><pre>list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]</pre><p>Related attributes:</p><ul><li><code>template:multiple-choice-list-field</code></li><li><code>template:multiple-choice-value</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:element</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li><li><code>template:value</code></li></ul><h3><a name="multiple-choice-list-element"></a>template:multiple-choice-list-element</h3><p>This attribute works in much the same way as <code>template:multiple-choice-list-field</code> except that it does not add a <code>name</code> attribute to the template element on which it is used. The purpose of this attribute, along with <code>template:attribute-list-button</code>, is to provide an alternative approach to presenting lists of selectable values.</p><p>Example:</p><pre><p template:multiple-choice-list-element="question,question-types,question-type"><br /> ...<br /></p></pre><p>See below for an example combining this attribute with the <code>template:attribute-list-button</code> attribute.</p><p>Syntax:</p><pre>element-name|<span style="font-weight: bold;">-</span>,list-element-name,list-attribute-name</pre><p>Here, <code>element-name</code> is the element in the document being presented which contains the selected value elements; if the special value <code>-</code> is given then the context element is the element containing the selected value elements. The <code>list-element-name</code> and <code>list-attribute-name</code> indicate the details of the elements providing the list of selectable values.</p><p>Related attributes:</p><ul><li><code>template:multiple-choice-list-field</code></li><li><code>template:attribute-list-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:element</code></li></ul><h3><a name="attribute-list-button"></a>template:attribute-list-button</h3><p>This attribute works in much the same way as <code>template:attribute-button</code>
17.92 +from inside each <code>base-system-enum</code> element in the modified document fragment presented below.</p><p>A modified document fragment providing the labels can be written as follows:</p><pre><question-types><br /> <question-type-enum question-type="text">Text</question-type-enum><br /> <question-type-enum question-type="choice" value-is-set="true">Choice</question-type-enum><br /> <question-type-enum question-type="special" value-is-set="true">Special</question-type-enum><br /></question-types></pre><p>The output from the modified combination would be as follows:</p><pre><select name="path-to-question-types" multiple="multiple"><br /> <option value="text">Text</option><br /> <option value="choice" selected="selected">Choice</option><br /> <option value="special" selected="selected">Special</option><br /></select></pre><p>Syntax:</p><pre>list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]</pre><p>Related attributes:</p><ul><li><code>template:multiple-choice-list-field</code></li><li><code>template:multiple-choice-value</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:element</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li><li><code>template:value</code></li></ul><h3><a name="multiple-choice-list-element"></a>template:multiple-choice-list-element</h3><p>This attribute works in much the same way as <code>template:multiple-choice-list-field</code> except that it does not add a <code>name</code> attribute to the template element on which it is used. The purpose of this attribute, along with <code>template:attribute-list-button</code>, is to provide an alternative approach to presenting lists of selectable values.</p><p>Example:</p><pre><p template:multiple-choice-list-element="question,question-types,question-type"><br /> ...<br /></p></pre><p>See below for an example combining this attribute with the <code>template:attribute-list-button</code> attribute.</p><p>Syntax:</p><pre>element-name|<span style="font-weight: bold;">-</span>,list-element-name,list-attribute-name</pre><p>Here, <code>element-name</code> is the element in the document being presented which contains the selected value elements; if the special value <code>-</code> is given then the context element is the element containing the selected value elements. The <code>list-element-name</code> and <code>list-attribute-name</code> indicate the details of the elements providing the list of selectable values.</p><p>Related attributes:</p><ul><li><code>template:multiple-choice-list-field</code></li><li><code>template:attribute-list-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:element</code></li></ul><h3><a name="attribute-list-button"></a>template:attribute-list-button</h3><p>This attribute works in much the same way as <code>template:attribute-button</code>
17.93 does, but instead presents a button or related user interface control
17.94 whose state reflects the presence of an attribute on an element in a
17.95 -collection of elements.</p><p>Example:</p><pre><p template:multiple-choice-list-element="question,question-types,question-type"><br /> <input template:attribute-list-button="question-type,checked" name="..." value="..." type="checkbox"/><br /></p></pre><p>Given an XML document like this...</p><pre><question><br /> <question-types question-type="text" value-is-set="true"/><br /> <question-types question-type="choice"/><br /></question></pre><p>...the following would be produced as output:</p><pre><p><br /> <input name="path-to-question-type" value="text" type="checkbox" checked="checked"/><br /></p><br /><p><br /> <input name="path-to-question-type" value="choice" type="checkbox"/><br /></p></pre><p>Syntax:</p><pre>attribute-name,attribute-to-create-when-set</pre><p>Related attributes:</p><ul><li><code>template:multiple-choice-list-element</code></li><li><code>template:attribute-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li></ul><h2>Internal Annotations</h2><p>The special annotations <code>template:expr</code> and <code>template:expr-attr</code>
17.96 +collection of elements.</p><p>Example:</p><pre><p template:multiple-choice-list-element="question,question-types,question-type"><br /> <input template:attribute-list-button="question-type,checked" name="..." value="..." type="checkbox"/><br /></p></pre><p>Given an XML document like this...</p><pre><question><br /> <question-types question-type="text" value-is-set="true"/><br /> <question-types question-type="choice"/><br /></question></pre><p>...the following would be produced as output:</p><pre><p><br /> <input name="path-to-question-type" value="text" type="checkbox" checked="checked"/><br /></p><br /><p><br /> <input name="path-to-question-type" value="choice" type="checkbox"/><br /></p></pre><p>Syntax:</p><pre>attribute-name,attribute-to-create-when-set</pre><p>Related attributes:</p><ul><li><code>template:multiple-choice-list-element</code></li><li><code>template:attribute-button</code></li></ul><p>Implementing attributes:</p><ul><li><code>template:attribute</code></li><li><code>template:expr</code></li><li><code>template:expr-attr</code></li></ul><h2>Internal Annotations</h2><p>The special annotations <code>template:expr</code> and <code>template:expr-attr</code>
17.97 are used respectively to test an XPath expression in the current
17.98 context and to provide the name of an attribute which is to be created
17.99 -in the final output, should the expression evaluate to a true value.</p><h2>Housekeeping Annotations</h2><p>In order to support explicit, additional namespaces in output document processing, the special <code>expr-prefix</code>
17.100 +in the final output, should the expression evaluate to a true value.</p><h2>Housekeeping Annotations</h2><p>In order to support explicit, additional namespaces in output document processing, the special <code>expr-prefix</code>
17.101 attribute can be used to ensure the presence of a namespace declaration
17.102 in the generated stylesheet files. Consider the usage of various
17.103 -stylesheet extension functions:</p><pre><body><br /> <p><br /> <span template:value="sum(str:split('1 2 3 4 5'))">result</span><br /> </p><br /></body></pre><p>For the stylesheet which produces the output, the <code>str</code>
17.104 +stylesheet extension functions:</p><pre><body><br /> <p><br /> <span template:value="sum(str:split('1 2 3 4 5'))">result</span><br /> </p><br /></body></pre><p>For the stylesheet which produces the output, the <code>str</code>
17.105 namespace will need to be declared somewhere. To do this, we must not
17.106 only declare the namespace in the template document, but we must also
17.107 provide a hint to the stylesheet processor that the namespace is
17.108 @@ -92,11 +94,11 @@
17.109 the namespace declaration).</p><pre><body xmlns:str="http://exslt.org/strings" str:expr-prefix="str http://exslt.org/strings"><br /> <p><br /> <span template:value="sum(str:split('1 2 3 4 5'))">result</span><br /> </p><br /></body></pre><p>What the special <code>expr-prefix</code>
17.110 attribute does is to provide that hint to the stylesheet processor,
17.111 although XSLTools also uses the attribute for other internal purposes.
17.112 -Consequently, the resulting output stylesheet is able to find the <code>str:split</code> extension function and to evaluate the expected result.</p><h3>Fixing Annotations</h3><p>One important application of the <code>expr-prefix</code>
17.113 +Consequently, the resulting output stylesheet is able to find the <code>str:split</code> extension function and to evaluate the expected result.</p><h3>Fixing Annotations</h3><p>One important application of the <code>expr-prefix</code>
17.114 attribute is the restoration of damaged attributes after the editing of
17.115 a template document using a less than careful HTML editor. Consider the
17.116 -above document fragment after a small edit in Nvu:</p><pre><body expr-prefix="str http://exslt.org/strings" str="http://exslt.org/strings"><br /> <p><br /> <span value="sum(str:split('1 2 3 4 5'))">result!</span><br /> </p><br /></body></pre><p>Nvu has obviously decided to remove the <code>str</code> and <code>template</code> namespace prefixes. To revert this damage, a tool is provided with XSLTools called <code>xslform_fix.py</code> (found in the <code>scripts</code> directory in the source distribution), and this tool will attempt to re-add namespace declarations for <code>template</code> automatically (since the <code>template</code> namespace is obviously the basis of XSLForms) along with any namespaces declared using <code>expr-prefix</code> attributes. The tool is invoked as follows:</p><pre>xslform_fix.py template.xhtml template_fixed.xhtml</pre><p>Since
17.117 +above document fragment after a small edit in Nvu:</p><pre><body expr-prefix="str http://exslt.org/strings" str="http://exslt.org/strings"><br /> <p><br /> <span value="sum(str:split('1 2 3 4 5'))">result!</span><br /> </p><br /></body></pre><p>Nvu has obviously decided to remove the <code>str</code> and <code>template</code> namespace prefixes. To revert this damage, a tool is provided with XSLTools called <code>xslform_fix.py</code> (found in the <code>scripts</code> directory in the source distribution), and this tool will attempt to re-add namespace declarations for <code>template</code> automatically (since the <code>template</code> namespace is obviously the basis of XSLForms) along with any namespaces declared using <code>expr-prefix</code> attributes. The tool is invoked as follows:</p><pre>xslform_fix.py template.xhtml template_fixed.xhtml</pre><p>Since
17.118 namespace declarations may be moved to the root element of the new
17.119 template document, it is possible that some problems may result
17.120 -with documents using namespaces in advanced ways, but the tool
17.121 -should provide a reasonable solution for most documents.</p></body></html>
17.122 \ No newline at end of file
17.123 +with documents using namespaces in advanced ways, but the tool
17.124 +should provide a reasonable solution for most documents.</p></body></html>
18.1 --- a/docs/selectors.html Sat Sep 08 16:53:18 2007 +0000
18.2 +++ b/docs/selectors.html Sat Sep 08 16:53:34 2007 +0000
18.3 @@ -1,12 +1,12 @@
18.4 +<?xml version="1.0" encoding="iso-8859-1"?>
18.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
18.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
18.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
18.8 -
18.9 - <title>Creating Applications: Add Selectors</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
18.10 + <title>Creating Applications: Add Selectors</title>
18.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
18.12 <body>
18.13 <h1>Creating Applications: Add Selectors</h1>
18.14 -<p>In the previous activity we annotated the template
18.15 +<p>In the previous activity we annotated the template
18.16 with
18.17 <a href="structure.html">structural information</a>,
18.18 and these annotations should be sufficient in
18.19 @@ -15,7 +15,7 @@
18.20 list items from the form data structure, and we added some buttons in
18.21 the template to be used for this purpose.</p>
18.22 <h2>Introducing Selectors</h2>
18.23 -<p>The buttons in the template are implicitly associated with
18.24 +<p>The buttons in the template are implicitly associated with
18.25 specific items and subitems, and when such buttons are pressed - for
18.26 example, to remove an item from the list - our application will want to
18.27 know on which item the removal action is to take place. In order to
18.28 @@ -23,7 +23,7 @@
18.29 special notation is used, and such notation turns elements such as
18.30 buttons into "selectors" - things which select parts of the structure
18.31 so that an operation can be carried out on those parts.</p>
18.32 -<p>Taking the example HTML code from before, we add some of these
18.33 +<p>Taking the example HTML code from before, we add some of these
18.34 selector annotations to the template to produce something
18.35 like this:</p>
18.36 <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>
18.37 @@ -32,43 +32,43 @@
18.38 changed:</p>
18.39 <ul>
18.40 <li>The <code>input</code> element for the
18.41 -first <code>Remove</code> button has a new <code>template:selector-field</code> attribute (and a modified <code>name</code>
18.42 +first <code>Remove</code> button has a new <code>template:selector-field</code> attribute (and a modified <code>name</code>
18.43 attribute
18.44 -containing a value that will be replaced).</li>
18.45 +containing a value that will be replaced).</li>
18.46 <li>The <code>input</code> element for the second <code>Remove</code>
18.47 -button has a new <code>template:selector-field</code> attribute (and a modified <code>name</code>
18.48 +button has a new <code>template:selector-field</code> attribute (and a modified <code>name</code>
18.49 attribute
18.50 -containing a value that will be replaced).</li>
18.51 +containing a value that will be replaced).</li>
18.52 </ul>
18.53 <p>What these amendments provide is a means for the XSLForms
18.54 framework
18.55 -to connect together these buttons with a specific element in the
18.56 +to connect together these buttons with a specific element in the
18.57 form data.</p>
18.58 <ul>
18.59 - <li>The first <code>Remove</code> button
18.60 -appears within the <code>div</code> element which maps onto items
18.61 + <li>The first <code>Remove</code> button
18.62 +appears within the <code>div</code> element which maps onto items
18.63 in the form data. This means that each button will refer to a
18.64 -specific item in the form being edited.</li>
18.65 +specific item in the form being edited.</li>
18.66 <li>The second <code>Remove</code> button appears
18.67 -within the <code>p</code> element which maps onto subitems in the
18.68 +within the <code>p</code> element which maps onto subitems in the
18.69 form data. This means that each button will refer to a
18.70 -specific subitem in the form being edited.</li>
18.71 +specific subitem in the form being edited.</li>
18.72 </ul>
18.73 -<p>We define the names of the selectors in the above cases to be <code>remove</code>
18.74 -and <code>remove2</code> respectively, since the special values
18.75 +<p>We define the names of the selectors in the above cases to be <code>remove</code>
18.76 +and <code>remove2</code> respectively, since the special values
18.77 begin with these identifiers.</p>
18.78 <h3>The Add Buttons</h3>
18.79 <p>Some other attributes have been changed in the previous HTML
18.80 code:</p>
18.81 <ul>
18.82 <li>The <code>input</code> element for the
18.83 -first <code>Add</code> button has a new <code>template:selector-field</code> attribute (and a modified <code>name</code>
18.84 +first <code>Add</code> button has a new <code>template:selector-field</code> attribute (and a modified <code>name</code>
18.85 attribute
18.86 -containing a value that will be replaced).</li>
18.87 +containing a value that will be replaced).</li>
18.88 <li>The <code>input</code> element for the second <code>Add</code>
18.89 -button has a new <code>template:selector-field</code> attribute (and a modified <code>name</code>
18.90 +button has a new <code>template:selector-field</code> attribute (and a modified <code>name</code>
18.91 attribute
18.92 -containing a value that will be replaced).</li>
18.93 +containing a value that will be replaced).</li>
18.94 </ul>
18.95 <ul>
18.96 </ul>
18.97 @@ -76,13 +76,13 @@
18.98 framework to connect these buttons to specific parts of the form data.</p>
18.99 <ul>
18.100 <li>The <code>Add subitem</code> button appears
18.101 -outside the <code>p</code> element which maps onto subitems in the
18.102 -form data. Instead, it appears within the <code>p</code>
18.103 +outside the <code>p</code> element which maps onto subitems in the
18.104 +form data. Instead, it appears within the <code>p</code>
18.105 element which maps onto items. This means that each button will refer
18.106 to a specific item in the form being edited, and the consequence of
18.107 adding a subitem will be the extension of that item's list of subitems.</li>
18.108 - <li>The <code>Add item</code> button
18.109 -appears outside the <code>p</code>
18.110 + <li>The <code>Add item</code> button
18.111 +appears outside the <code>p</code>
18.112 element which maps onto items in the form data. Instead, it appears
18.113 within the <code>body</code>
18.114 element which maps onto the top-level <code>structure</code>
18.115 @@ -94,8 +94,8 @@
18.116 </ul>
18.117 <p>We define the names of the selectors in the above cases to be <code>add2</code>
18.118 and <code>add</code> respectively, since the special values begin with
18.119 -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>
18.120 +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>
18.121 <p>We should now have a template that is sufficiently complete to be
18.122 used in a real application, and the writing of the <a href="Web-resource.html">application code</a> itself will be
18.123 investigated in the next activity in the development <a href="overview.html">process</a>.</p>
18.124 -</body></html>
18.125 \ No newline at end of file
18.126 +</body></html>
19.1 --- a/docs/structure.html Sat Sep 08 16:53:18 2007 +0000
19.2 +++ b/docs/structure.html Sat Sep 08 16:53:34 2007 +0000
19.3 @@ -1,8 +1,8 @@
19.4 +<?xml version="1.0" encoding="iso-8859-1"?>
19.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
19.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
19.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
19.8 -
19.9 - <title>Creating Applications: Add Structure</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
19.10 + <title>Creating Applications: Add Structure</title>
19.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
19.12 <body>
19.13 <h1>Creating Applications: Add Structure</h1>
19.14 @@ -16,40 +16,40 @@
19.15 adding special attributes to the HTML code.</p>
19.16 <p> Consider the interesting parts of the template side by side with
19.17 the structure information:</p>
19.18 -<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>
19.19 -<p>To make such connections, we will annotate the HTML code using
19.20 +<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>
19.21 +<p>To make such connections, we will annotate the HTML code using
19.22 special attributes and values.</p>
19.23 <ul>
19.24 </ul>
19.25 <h2><a name="AnnotatingTheTemplate"></a>Annotating the Template</h2>
19.26 <p>Taking the template extract from above, we add special annotations
19.27 to produce something like this:</p>
19.28 -<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>
19.29 +<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>
19.30 <p style="">
19.31 The following annotations have been added:</p>
19.32 <ul>
19.33 - <li>For elements in the structure, <code>template:element</code>
19.34 + <li>For elements in the structure, <code>template:element</code>
19.35 attributes have been added to the corresponding HTML elements in the
19.36 template.</li>
19.37 - <li>For attributes in the structure, <code>template:attribute-field</code>
19.38 -attributes have been added to the corresponding HTML elements
19.39 + <li>For attributes in the structure, <code>template:attribute-field</code>
19.40 +attributes have been added to the corresponding HTML elements
19.41 in the template.</li>
19.42 </ul>
19.43 -<p>Note how the <code>name</code> and <code>value</code> attributes have had their contents replaced with <code>...</code>;
19.44 +<p>Note how the <code>name</code> and <code>value</code> attributes have had their contents replaced with <code>...</code>;
19.45 we do this to keep Web page editors happy, and in the final output
19.46 these attributes will be replaced with those which model the underlying
19.47 document correctly.</p>
19.48 <h2>Completing the Template</h2>
19.49 <p>The template in full should now look something like this:</p>
19.50 <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>
19.51 -<p>Note also that a namespace declaration is required for the <code>template</code>
19.52 +<p>Note also that a namespace declaration is required for the <code>template</code>
19.53 attributes, and it is usually best to put this declaration on the
19.54 -top-level <code>html</code> element in the template, as shown in
19.55 +top-level <code>html</code> element in the template, as shown in
19.56 the above example code.</p>
19.57 <p>Whilst the above annotations permit the template to display the data
19.58 in XML documents containing form data, the other aspects of the user
19.59 interface - the addition and removal of items and subitems - are not
19.60 yet fully modelled in the template. These things will be added to the
19.61 -template as <a href="selectors.html">selectors</a> as part of the
19.62 +template as <a href="selectors.html">selectors</a> as part of the
19.63 next activity in the development <a href="overview.html">process</a>.</p>
19.64 -</body></html>
19.65 \ No newline at end of file
19.66 +</body></html>
20.1 --- a/docs/template-design.html Sat Sep 08 16:53:18 2007 +0000
20.2 +++ b/docs/template-design.html Sat Sep 08 16:53:34 2007 +0000
20.3 @@ -1,8 +1,8 @@
20.4 +<?xml version="1.0" encoding="iso-8859-1"?>
20.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
20.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
20.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
20.8 -
20.9 - <title>Template Design</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
20.10 + <title>Template Design</title>
20.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
20.12 <body>
20.13 <h1>Template Design</h1>
20.14 @@ -26,32 +26,32 @@
20.15 "patterns" in a document structure.</p><h3>Multiple Languages and Translations</h3><p>One
20.16 presentation issue which is largely separate from the presentation of
20.17 the structure of form data involves the use of appropriate languages
20.18 -for an application's users - this is described in the <a href="internationalisation.html">"Internationalisation"</a> document.</p><h3>General Template Structure</h3><ul><li>Described in the <a href="design.html">"Creating Applications: Design a Template"</a> document.</li></ul><p>Templates based on HTML usually have the following general structure:</p><pre><?xml version="1.0"?><br /><html xmlns="http://www.w3.org/1999/xhtml"<br /> xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"><br /><head><br /> <title>Some title</title><br /></head><br /><body template:element="structure"><br /><br /><!-- The interesting part goes here... --><br /><br /></body><br /></html></pre><p>Since we will want to edit the data produced by such a template, an HTML <code>form</code> element is usually necessary within the <code>body</code> element:</p><pre><body template:element="structure"><br /><form action="" method="POST"><br /><br /><!-- The interesting part goes here... --><br /><br /></form><br /></body></pre><p>We usually define the <code>method</code> as <code>post</code> in order to minimise complications with handling the data in the XSLForms toolkit.</p><h3>Static Elements</h3><ul><li>See <a href="reference.html#element">"template:element"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Static
20.19 +for an application's users - this is described in the <a href="internationalisation.html">"Internationalisation"</a> document.</p><h3>General Template Structure</h3><ul><li>Described in the <a href="design.html">"Creating Applications: Design a Template"</a> document.</li></ul><p>Templates based on HTML usually have the following general structure:</p><pre><?xml version="1.0"?><br /><html xmlns="http://www.w3.org/1999/xhtml"<br /> xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"><br /><head><br /> <title>Some title</title><br /></head><br /><body template:element="structure"><br /><br /><!-- The interesting part goes here... --><br /><br /></body><br /></html></pre><p>Since we will want to edit the data produced by such a template, an HTML <code>form</code> element is usually necessary within the <code>body</code> element:</p><pre><body template:element="structure"><br /><form action="" method="POST"><br /><br /><!-- The interesting part goes here... --><br /><br /></form><br /></body></pre><p>We usually define the <code>method</code> as <code>post</code> in order to minimise complications with handling the data in the XSLForms toolkit.</p><h3>Static Elements</h3><ul><li>See <a href="reference.html#element">"template:element"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Static
20.20 elements, as opposed to collection elements, are elements in the
20.21 form data document structure which maintain some kind of organisation or grouping
20.22 within a document, but whose presence cannot be edited by the user of
20.23 -an application. For example, in the <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> document the following example is given:</p><pre><div template:element="hard-disks"><br /> <input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/><br /> <p template:element="hard-disk"><br /> ...<br /> </p><br /></div></pre><p>Here, the <code>hard-disks</code> element is present to group <code>hard-disk</code>
20.24 +an application. For example, in the <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> document the following example is given:</p><pre><div template:element="hard-disks"><br /> <input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/><br /> <p template:element="hard-disk"><br /> ...<br /> </p><br /></div></pre><p>Here, the <code>hard-disks</code> element is present to group <code>hard-disk</code>
20.25 elements together. We can insist that elements are treated as static
20.26 -elements in the document initialisation process by adding the <code>template:init</code> attribute to the annotated template element:</p><pre><div template:element="hard-disks" template:init="yes"><br /> ...<br /></div></pre><p>See the <a href="reference.html">"Template Attribute Reference"</a> document for more information on the <code>template:init</code> attribute.</p><h3>Collection Elements</h3><ul><li>See <a href="reference.html#element">"template:element"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li><li>Described in the <a href="structure.html#AnnotatingTheTemplate">"Annotating the Template"</a> section of the <a href="design.html">"Creating Applications: Design a Template"</a> document.</li></ul><p>Collection
20.27 +elements in the document initialisation process by adding the <code>template:init</code> attribute to the annotated template element:</p><pre><div template:element="hard-disks" template:init="yes"><br /> ...<br /></div></pre><p>See the <a href="reference.html">"Template Attribute Reference"</a> document for more information on the <code>template:init</code> attribute.</p><h3>Collection Elements</h3><ul><li>See <a href="reference.html#element">"template:element"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li><li>Described in the <a href="structure.html#AnnotatingTheTemplate">"Annotating the Template"</a> section of the <a href="design.html">"Creating Applications: Design a Template"</a> document.</li></ul><p>Collection
20.28 elements are elements in the form data document structure which represent a
20.29 collection of items or objects and whose presence may be edited by the
20.30 user of an application. In the following example, <code>hard-disk</code> elements are collection elements:</p><pre><p template:element="hard-disk"><br /> ...<br /></p></pre><p>Whether
20.31 elements are treated as collection elements in the document
20.32 -initialisation process depends on the presence or absence of the <code>template:init</code> attribute on the annotated template element: if the <code>template:init</code> attribute is present, the value of that attribute will determine whether such elements (named in the <code>template:element</code>
20.33 +initialisation process depends on the presence or absence of the <code>template:init</code> attribute on the annotated template element: if the <code>template:init</code> attribute is present, the value of that attribute will determine whether such elements (named in the <code>template:element</code>
20.34 attribute) will be created automatically (and thus behave like static
20.35 elements) or created dynamically (and thus behave like collection
20.36 -elements); if the <code>template:init</code> attribute is absent,
20.37 +elements); if the <code>template:init</code> attribute is absent,
20.38 the way such elements are treated will depend on other factors, notably
20.39 -the presence of selectors referring to such elements. Here is such a selector:</p><pre><input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/></pre><p>In the above example, the selector field (see below and in the <a href="reference.html">"Template Attribute Reference"</a> document for more details) mentions the document structure's <code>hard-disk</code>
20.40 +the presence of selectors referring to such elements. Here is such a selector:</p><pre><input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/></pre><p>In the above example, the selector field (see below and in the <a href="reference.html">"Template Attribute Reference"</a> document for more details) mentions the document structure's <code>hard-disk</code>
20.41 element; thus, the element is treated as a collection. If we did not
20.42 -have such a selector in the template, we could also have used a <code>template:init</code> attribute to have the same effect:</p><pre><p template:element="hard-disk" template:init="no"><br /> ...<br /></p></pre><p>Generally,
20.43 +have such a selector in the template, we could also have used a <code>template:init</code> attribute to have the same effect:</p><pre><p template:element="hard-disk" template:init="no"><br /> ...<br /></p></pre><p>Generally,
20.44 collection elements do have selector fields providing operations on the
20.45 collection, and so the extra annotation is not usually necessary.</p><h3>Selectors</h3><ul><li>Described in the <a href="selectors.html">"Creating Applications: Add Selectors"</a>
20.46 document.</li></ul><p>Selectors provide a means to select elements in collections
20.47 and to request that some operation be performed on those selected
20.48 elements. Two common selector types are those concerning the addition
20.49 -and removal of elements.</p><h4>Selectors as Buttons</h4><ul><li>See <a href="reference.html#selector-field">"template:selector-field"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>In the collection elements example above, we saw the usage of a selector which could be used to add elements to a document:</p><pre><input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="Add hard disk" type="submit" /> </p><p>As described in the <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> document, the above selector (with the name <code>add-hard-disk</code>)
20.50 -could be obtained in the application itself, and the collection of
20.51 +and removal of elements.</p><h4>Selectors as Buttons</h4><ul><li>See <a href="reference.html#selector-field">"template:selector-field"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>In the collection elements example above, we saw the usage of a selector which could be used to add elements to a document:</p><pre><input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="Add hard disk" type="submit" /> </p><p>As described in the <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> document, the above selector (with the name <code>add-hard-disk</code>)
20.52 +could be obtained in the application itself, and the collection of
20.53 elements associated with the selector used as a collection of places to
20.54 insert new elements into the form data document. Similarly, a
20.55 selector which could be used to remove elements from a document could
20.56 @@ -72,16 +72,16 @@
20.57 template.</p><h4>Editable Fields</h4><ul><li>See <a href="reference.html#attribute-field">"template:attribute-field"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>If we are to permit an attribute value to be edited, we might choose the following template representation:</p><pre><input template:attribute-field="attribute" name="..." value="..." type="text"/></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="..." /></p><p>Note
20.58 that the element on which the attribute is defined is not declared in
20.59 the above example, although we could also add such an annotation to
20.60 -the <code>input</code> element (as described above and in the <a href="reference.html">"Template Attribute Reference"</a> document).</p><h4>Read-only Values</h4><ul><li>See <a href="reference.html#attribute-area">"template:attribute-area"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Where attribute values are only displayed, we can use non-form HTML elements to display them:</p><pre><span template:attribute-area="attribute">some text to be replaced with the value</span></pre><p>This would insert the value of the attribute in the document within the defined <code>span</code> template element.</p><h4>Hidden Values</h4><ul><li>See <a href="reference.html#attribute-field">"template:attribute-field"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Where
20.61 -attribute values are to be retained and submitted again by the
20.62 -user, but probably not edited, we need to include them as hidden
20.63 +the <code>input</code> element (as described above and in the <a href="reference.html">"Template Attribute Reference"</a> document).</p><h4>Read-only Values</h4><ul><li>See <a href="reference.html#attribute-area">"template:attribute-area"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Where attribute values are only displayed, we can use non-form HTML elements to display them:</p><pre><span template:attribute-area="attribute">some text to be replaced with the value</span></pre><p>This would insert the value of the attribute in the document within the defined <code>span</code> template element.</p><h4>Hidden Values</h4><ul><li>See <a href="reference.html#attribute-field">"template:attribute-field"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Where
20.64 +attribute values are to be retained and submitted again by the
20.65 +user, but probably not edited, we need to include them as hidden
20.66 elements:</p><pre><input template:attribute-field="attribute" name="..." value="..." type="hidden"/></pre><p>This
20.67 keeps the contents of the document intact, but it should be noted that
20.68 -such values are only uneditable in the way they are presented to
20.69 +such values are only uneditable in the way they are presented to
20.70 the user, and that a determined user could easily find a way to change
20.71 such values and send them in to the application.</p><h4>Checkboxes</h4><ul><li>See <a href="reference.html#attribute-button">"template:attribute-button"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Sometimes,
20.72 attributes are used to retain particular values that correspond to a
20.73 -boolean state. Such values can be modelled as follows:</p><pre><input template:attribute-button="attribute,true,checked" name="..." value="..." type="checkbox"/></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="..." type="checkbox" /></p><p>If selected, the checkbox would when submitted cause the attribute to contain the value <code>true</code>
20.74 +boolean state. Such values can be modelled as follows:</p><pre><input template:attribute-button="attribute,true,checked" name="..." value="..." type="checkbox"/></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="..." type="checkbox" /></p><p>If selected, the checkbox would when submitted cause the attribute to contain the value <code>true</code>
20.75 in the form data document. Moreover, the presence of the attribute with
20.76 such a value would cause the checkbox to appear selected when the form
20.77 data is presented to the user again.</p><h4>Radio Buttons</h4><ul><li>See <a href="reference.html#attribute-button">"template:attribute-button"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li></ul><p>Unlike
20.78 @@ -90,7 +90,7 @@
20.79 value would be stored on a single attribute in the form data document.
20.80 For example:</p><pre><input type="radio" template:attribute-button="attribute,some-choice,checked" name="..." value="..." /></pre><p>This would produce the following HTML form control:</p><p><input name="..." value="..." type="radio" /></p><p>If
20.81 selected, the radio button when submitted would cause the attribute to
20.82 -contain the stated value in the form data document, which would be <code>some-choice</code>
20.83 +contain the stated value in the form data document, which would be <code>some-choice</code>
20.84 for the button in the above example. Should a different button
20.85 associated with the same attribute be pressed, the value stated in the
20.86 definition of that button would be stored in the attribute. Like the
20.87 @@ -100,23 +100,23 @@
20.88 and whilst such attributes typically reside in the form data document
20.89 carrying a single, currently set value, the representation of the
20.90 document processed by the template must somehow incorporate the list of
20.91 -acceptable values; this was covered in the <a href="multiple.html">"Creating Applications: Adding Multiple-Choice Fields and Values"</a> document, and involved adding new elements, each carrying a single acceptable value for the attribute concerned.</p><h4>Single Selection Menus</h4><ul><li>See <a href="reference.html#multiple-choice-field">"template:multiple-choice-field"</a> and <a href="reference.html#multiple-choice-value">"template:multiple-choice-value"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li><li>Described in the <a href="multiple.html">"Creating Applications: Adding Multiple-Choice Fields and Values"</a> document.</li></ul><p>In
20.92 +acceptable values; this was covered in the <a href="multiple.html">"Creating Applications: Adding Multiple-Choice Fields and Values"</a> document, and involved adding new elements, each carrying a single acceptable value for the attribute concerned.</p><h4>Single Selection Menus</h4><ul><li>See <a href="reference.html#multiple-choice-field">"template:multiple-choice-field"</a> and <a href="reference.html#multiple-choice-value">"template:multiple-choice-value"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li><li>Described in the <a href="multiple.html">"Creating Applications: Adding Multiple-Choice Fields and Values"</a> document.</li></ul><p>In
20.93 certain situations, it makes more sense to present acceptable values
20.94 for an attribute in a menu-like representation in the final output
20.95 presented to the user. With the element on which the attribute resides
20.96 now containing a list of sub-elements with each carrying an acceptable
20.97 value in an attribute, a form control can be defined as follows:</p><pre><select template:multiple-choice-field="-,attribute" name="..."><br /> <option template:multiple-choice-value="element-enum,value,selected" value="..."></option><br /></select></pre><p>This would produce the following HTML form control:</p><p><select name="..."><option>First</option><option>Second</option><option>Third</option></select></p><p>Note that the element on which the attribute is defined is not declared
20.98 -in the above example, although we could modify the <code>template:multiple-choice-field</code> annotation on
20.99 -the <code>select</code> element (as described in the <a href="reference.html">"Template Attribute Reference"</a> document) and replace the <code>-</code> with a name such as <code>element</code>.</p><h4>Multiple Selection Lists</h4><ul><li>See <a href="reference.html#multiple-choice-list-field">"template:multiple-choice-list-field"</a> and <a href="reference.html#multiple-choice-list-value">"template:multiple-choice-list-value"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li><li>Described in the <a href="multivalue.html">"Creating Applications: Adding Multivalued Fields"</a> document.</li></ul><p>In
20.100 +in the above example, although we could modify the <code>template:multiple-choice-field</code> annotation on
20.101 +the <code>select</code> element (as described in the <a href="reference.html">"Template Attribute Reference"</a> document) and replace the <code>-</code> with a name such as <code>element</code>.</p><h4>Multiple Selection Lists</h4><ul><li>See <a href="reference.html#multiple-choice-list-field">"template:multiple-choice-list-field"</a> and <a href="reference.html#multiple-choice-list-value">"template:multiple-choice-list-value"</a> in the <a href="reference.html">"Template Attribute Reference"</a> document.</li><li>Described in the <a href="multivalue.html">"Creating Applications: Adding Multivalued Fields"</a> document.</li></ul><p>In
20.102 other situations, where many values can be chosen, a single attribute
20.103 on a single element is not sufficient to hold all such values.
20.104 Consequently, a collection of elements is employed, each with an
20.105 attribute defined to hold a single value. With each value-bearing
20.106 -element now containing a list of sub-elements with each carrying
20.107 +element now containing a list of sub-elements with each carrying
20.108 an acceptable
20.109 -value in an attribute, a form control can be defined as follows:</p><pre><select name="..." template:multiple-choice-list-field="-,element-enum,attribute" multiple="multiple"><br /> <option template:multiple-choice-list-value="element-enum,value,selected" value="..."></option><br /></select></pre><p>This would produce the following HTML form control:</p><p><select multiple="multiple" name="..."><option>First</option><option>Second</option><option>Third</option></select></p><p>Note that unlike the single selection menu example, an additional parameter is present in the <code>template:multiple-choice-list-field</code> annotation, but the first parameter is given as the placeholder value <code>-</code> (and is regarded as not having been stated). However, had the first parameter been stated (as opposed to being given as <code>-</code>)
20.110 +value in an attribute, a form control can be defined as follows:</p><pre><select name="..." template:multiple-choice-list-field="-,element-enum,attribute" multiple="multiple"><br /> <option template:multiple-choice-list-value="element-enum,value,selected" value="..."></option><br /></select></pre><p>This would produce the following HTML form control:</p><p><select multiple="multiple" name="..."><option>First</option><option>Second</option><option>Third</option></select></p><p>Note that unlike the single selection menu example, an additional parameter is present in the <code>template:multiple-choice-list-field</code> annotation, but the first parameter is given as the placeholder value <code>-</code> (and is regarded as not having been stated). However, had the first parameter been stated (as opposed to being given as <code>-</code>)
20.111 the consequence would merely have been that upon submission of the
20.112 -form, the elements in the collection would have been enclosed
20.113 +form, the elements in the collection would have been enclosed
20.114 within a single named element. In the above example, we assume that a
20.115 suitable element has already been defined in a template element and
20.116 -that the above <code>select</code> element resides within that template element, thus providing the necessary enclosure (as recommended in the <a href="advice.html">"Creating Applications: Recommendations and Advice"</a> document).</p></body></html>
20.117 \ No newline at end of file
20.118 +that the above <code>select</code> element resides within that template element, thus providing the necessary enclosure (as recommended in the <a href="advice.html">"Creating Applications: Recommendations and Advice"</a> document).</p></body></html>
21.1 --- a/docs/what.html Sat Sep 08 16:53:18 2007 +0000
21.2 +++ b/docs/what.html Sat Sep 08 16:53:34 2007 +0000
21.3 @@ -1,39 +1,11 @@
21.4 +<?xml version="1.0" encoding="iso-8859-1"?>
21.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
21.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
21.7 -
21.8 -
21.9 -
21.10 -
21.11 -
21.12 -
21.13 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
21.14 -
21.15 -
21.16 -
21.17 -
21.18 -
21.19 -
21.20 -
21.21 -
21.22 -
21.23 -
21.24 - <title>What are XSLTools and XSLForms?</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
21.25 -
21.26 -
21.27 -
21.28 -
21.29 -
21.30 -
21.31 + <title>What are XSLTools and XSLForms?</title>
21.32 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
21.33 -
21.34 <body>
21.35 -
21.36 -
21.37 -
21.38 <h1>What are XSLTools and XSLForms?</h1>
21.39 -
21.40 -
21.41 -
21.42 <p>XSLTools is the name of an entire distribution of modules, packages, examples and documentation; it includes...</p>
21.43 <ul>
21.44 <li>The XSLForms
21.45 @@ -61,4 +33,4 @@
21.46 stylesheets, permitting the framework to take advantage of that
21.47 particular standardised and well-supported technology using XSLTools (specifically XSLOutput)
21.48 and, in turn, libxslt.</p>
21.49 -</body></html>
21.50 \ No newline at end of file
21.51 +</body></html>