1.1 --- a/docs/JavaScript-reference.html Fri Nov 21 01:43:03 2008 +0100
1.2 +++ b/docs/JavaScript-reference.html Fri Nov 21 01:43:30 2008 +0100
1.3 @@ -12,7 +12,7 @@
1.4 <pre>'platforms'</pre>
1.5 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.6 <pre>'/package$1/platforms$1'</pre>
1.7 -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.8 +Typically, one would use an <a href="../apidocs/XSLForms.Output-module.html">template extension function</a> to provide such information. For example:<br />
1.9 <pre>'{template:other-elements(..)}'</pre>
1.10 Selector fields may be specified in addition to regions:<br />
1.11 <pre>'{template:selector-name('remove_platform', .)}'</pre>
1.12 @@ -20,6 +20,6 @@
1.13 <h2>requestUpdate</h2>
1.14 <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.15 <pre>'/package$1/name'</pre>
1.16 -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.17 +Typically, one would use an <a href="../apidocs/XSLForms.Output-module.html">template extension function</a> to provide such information. For example:<br />
1.18 <pre>'{template:other-attributes('name', .)}'</pre>
1.19 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/XSLForms-resource.html Fri Nov 21 01:43:03 2008 +0100
2.2 +++ b/docs/XSLForms-resource.html Fri Nov 21 01:43:30 2008 +0100
2.3 @@ -11,7 +11,7 @@
2.4 from this class, <code>XSLFormsResource</code>,
2.5 you can derive your own application-specific resources and use the
2.6 class's API to obtain, manipulate and present form data. Although the
2.7 -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>
2.8 +supplied <a href="../apidocs/index.html">API documentation</a> provides details of the class's API, specifically in the <code><a href="../apidocs/XSLForms.Resources.WebResources-module.html">XSLForms.Resources.WebResources</a></code><a href="../apidocs/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>
2.9 support the concept of resources which are used to produce output,
2.10 support processing and to provide access to useful information. At the
2.11 class level it is essential to define at least some of these resources
2.12 @@ -109,7 +109,7 @@
2.13 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>
2.14 node in that template document. Note that the choice of template
2.15 document is not defined here, but is instead made when handling an
2.16 -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
2.17 +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/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
2.18 XSLForms is an XML-based toolkit, the form data is available as XML
2.19 documents which can be accessed and manipulated using a DOM-style API.
2.20 Upon receiving submitted form data, XSLForms converts the data to such
2.21 @@ -155,7 +155,7 @@
2.22 operation, we could use the DOM-style API exposed by the contents of
2.23 the selectors to perform such an operation in the resource using our
2.24 own code. However, the XSLForms toolkit provides some useful
2.25 -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>
2.26 +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/XSLForms.Utils-module.html">XSLForms.Utils</a></code><a href="../apidocs/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>
2.27 attribute, is similar to the transformation of a document as described
2.28 above. First, we obtain a reference to an initialisation stylesheet:</p><pre>init_stylesheet = self.prepare_initialiser("configuration")</pre><p>Note
2.29 that only a single stylesheet is returned. With the result of the call,
3.1 --- a/docs/index.html Fri Nov 21 01:43:03 2008 +0100
3.2 +++ b/docs/index.html Fri Nov 21 01:43:30 2008 +0100
3.3 @@ -29,7 +29,7 @@
3.4 guide can be found inside the <a href="../apidocs/index.html"><code>apidocs</code></a>
3.5 directory within the <code>XSLTools-0.6</code> directory. Of course,
3.6 it is always possible to view the API documentation
3.7 -within Python by importing modules (such as <a href="../apidocs/public/XSLTools.XSLOutput-module.html"><code>XSLTools.XSLOutput</code></a>)
3.8 +within Python by importing modules (such as <a href="../apidocs/XSLTools.XSLOutput-module.html"><code>XSLTools.XSLOutput</code></a>)
3.9 and using Python's built-in <code>help</code> function.</p>
3.10 <h2>About XSLForms Applications</h2>
3.11 <ul>
4.1 --- a/docs/internationalisation.html Fri Nov 21 01:43:03 2008 +0100
4.2 +++ b/docs/internationalisation.html Fri Nov 21 01:43:30 2008 +0100
4.3 @@ -10,7 +10,7 @@
4.4 document: the usage of different texts, labels or phrases chosen
4.5 according to the languages understood by users of an application. The
4.6 XSLForms toolkit provides two mechanisms for the use of translations
4.7 -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
4.8 +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/XSLForms.Output-module.html#i18n"><code>template:i18n</code></a> extension function, as described in the <a href="../apidocs/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
4.9 of the above mechanisms has its own specific purpose in template
4.10 documents, and these purposes are described below, along with the
4.11 necessary procedures for initialising and invoking the translation
4.12 @@ -34,7 +34,7 @@
4.13 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
4.14 no suitable translation can be found for the text passed to the
4.15 function, the submitted text is returned as a result, producing
4.16 -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
4.17 +something resembling the original, non-translated document fragment.</p><p>See the <a href="../apidocs/XSLForms.Output-module.html#i18n"><code>template:i18n</code></a> extension function description in the <a href="../apidocs/XSLForms.Output-module.html">extension function API documentation</a> for more details.</p><h2>Initialising and Invoking Translations</h2><p>To
4.18 permit the translation of text to occur, we must first prepare the
4.19 translations themselves; then, we must change our application to make
4.20 use of the translations.</p><h3><a name="PreparingTheTranslations"></a>Preparing the Translations</h3><p>Translations
5.1 --- a/docs/labels.html Fri Nov 21 01:43:03 2008 +0100
5.2 +++ b/docs/labels.html Fri Nov 21 01:43:30 2008 +0100
5.3 @@ -42,7 +42,7 @@
5.4 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>
5.5 parameter for the output stylesheet using the first language specified
5.6 in each user's browser's language preferences. Then, we add a reference
5.7 -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>
5.8 +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/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/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>
5.9 <h2>Further Reading</h2>
5.10 <p>Now that we have designed and implemented a simple application, it
5.11 may be worth reading some <a href="advice.html">recommendations</a>
6.1 --- a/docs/overview.html Fri Nov 21 01:43:03 2008 +0100
6.2 +++ b/docs/overview.html Fri Nov 21 01:43:30 2008 +0100
6.3 @@ -45,7 +45,7 @@
6.4
6.5 <ul>
6.6 <li><a href="reference.html">A template attribute reference</a></li>
6.7 -<li><a href="../apidocs/public/XSLForms.Output-module.html">A template extension function reference</a></li>
6.8 +<li><a href="../apidocs/XSLForms.Output-module.html">A template extension function reference</a></li>
6.9 <li><a href="JavaScript-reference.html">An in-page update JavaScript function reference</a></li>
6.10 </ul>
6.11