1.1 --- a/docs/in-page-updates.html Sat Dec 03 01:52:11 2005 +0000
1.2 +++ b/docs/in-page-updates.html Sat Dec 03 01:53:18 2005 +0000
1.3 @@ -50,7 +50,7 @@
1.4 <ol>
1.5 <li>Inside this new <code>options</code> element, investigate
1.6 the values associated with the <code>type</code> element.</li>
1.7 - <li>If any of the selected type values is "Personal", make a new <code>comment</code>
1.8 + <li>If any of the selected type values represents the "Personal" category, make a new <code>comment</code>
1.9 element, then add any attributes that may be found on
1.10 existing <code>comment</code> elements within the current <code>type</code>
1.11 element.</li>
1.12 @@ -194,7 +194,9 @@
1.13 <p>Instead of just obtaining a stylesheet for the <code>structure</code>
1.14 document, we instead check to see if an in-page update is being
1.15 requested and, if so, prepare the stylesheet representing the fragment
1.16 -of the Web form to be presented. Additionally, we obtain special stylesheet parameters using the raw request parameters; this introduces information that will be used to control the
1.17 +of the Web form to be presented. Additionally, we obtain special
1.18 +stylesheet parameters using the raw request parameters; this introduces
1.19 +information that will be used to control the
1.20 stylesheet when making the final Web page output.</p>
1.21 <p>Finally, we send the output to the user but employing the additional
1.22 stylesheet parameters to configure the result:</p>
1.23 @@ -220,4 +222,4 @@
1.24 script file; otherwise it gets a Web page showing either all of the
1.25 form (if a normal request is received), or a part of the form (if an
1.26 in-page request is received).</p>
1.27 -</body></html>
1.28 +</body></html>
1.29 \ No newline at end of file
2.1 --- a/docs/internationalisation.html Sat Dec 03 01:52:11 2005 +0000
2.2 +++ b/docs/internationalisation.html Sat Dec 03 01:53:18 2005 +0000
2.3 @@ -10,11 +10,11 @@
2.4 document: the usage of different texts, labels or phrases chosen
2.5 according to the languages understood by users of an application. The
2.6 XSLForms toolkit provides two mechanisms for the use of translations
2.7 -and translated phrases:</p><ul><li>The <a href="reference.html#template: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
2.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/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
2.9 of the above mechanisms has its own specific purpose in template
2.10 documents, and these purposes are described below, along with the
2.11 necessary procedures for initialising and invoking the translation
2.12 -mechanisms in an XSLForms application.<br /></p><h2>Translating Element Content</h2><p>Consider the following document fragment:</p><pre><h1>System Configurator</h1></pre><p>In
2.13 +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
2.14 order to translate this to a different language, according to that
2.15 preferred by the user, we must annotate the element containing the text
2.16 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>)
2.17 @@ -25,7 +25,7 @@
2.18 cases where no translation could be found, the original contents of the
2.19 element would be preserved.</p><p>It is also possible to employ a
2.20 specific translation as opposed to the text which just happen to reside
2.21 -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><p>See the <a href="reference.html#template: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>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,
2.22 +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><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,
2.23 we insert an expression inside the attribute whose result will be
2.24 inserted in place of the expression. Note that for non-template
2.25 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
2.26 @@ -34,7 +34,7 @@
2.27 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
2.28 permit the translation of text to occur, we must first prepare the
2.29 translations themselves; then, we must change our application to make
2.30 -use of the translations.</p><h3>Preparing the Translations</h3><p>Translations
2.31 +use of the translations.</p><h3><a name="PreparingTheTranslations"></a>Preparing the Translations</h3><p>Translations
2.32 are typically stored in an XML file alongside other resources such as
2.33 templates and documents containing data which are also used to prepare
2.34 the final user-viewable output from an application. For example, one
2.35 @@ -45,7 +45,7 @@
2.36 document.</p><p>Conversely, in the above example, the locale for <code>en</code> and <code>en_GB</code>
2.37 has some translations defined; as a result, requests for translations
2.38 in this locale will result in the specified translations being
2.39 -returned, provided the token is defined in a <code>value</code> attribute of a <code>translation</code> element; otherwise, the text already found in the document will be preserved.</p><h3>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
2.40 +returned, provided the token is defined in a <code>value</code> attribute of a <code>translation</code> element; otherwise, the text already found in the document will be preserved.</p><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
2.41 producing output for a template which uses internationalisation
2.42 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,
2.43 we must decide which language or locale the output will employ. One way
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/labels.html Sat Dec 03 01:53:18 2005 +0000
3.3 @@ -0,0 +1,50 @@
3.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
3.6 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
3.7 +
3.8 + <title>Creating Applications: Labelling Multiple-Choice Values</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.9 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
3.10 +<body>
3.11 +<h1>Creating Applications: Labelling Multiple-Choice Values</h1>
3.12 +<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
3.13 +simple applications with a limited audience, it is often acceptable to
3.14 +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
3.15 +must therefore consider introducing additional label information in
3.16 +order to remedy the first case, at least. Consequently, we may modify
3.17 +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,
3.18 +we have provided user-visible labels which can now be used by the
3.19 +template. A single change to the item type choices list is required to
3.20 +include these labels as the visible text in that particular form
3.21 +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>
3.22 +</ul><h3>Updating the Web Resource</h3>
3.23 +<p>To update the special WebStack resource, we
3.24 +now need to modify a few of the class attributes:</p>
3.25 +<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>
3.26 +<p>With these adjustments, it should now be possible to see the
3.27 +original labels and yet have the application manipulate a separate set
3.28 +of internal values.
3.29 +Note that it may be necessary to remove the old stylesheet for
3.30 +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
3.31 +the above work made it possible to satisfy the first motivation of the
3.32 +use of labels - to hide internal values - it did not permit us to
3.33 +provide translations for different languages. In fact, there are at
3.34 +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
3.35 +former approach might work in situations where multiple-choice values
3.36 +are obtained from a repository, such as a database, which contains the
3.37 +labels for items in each supported language. One can envisage a product
3.38 +database, for example, containing product descriptions for each
3.39 +language or market, and such information could be extracted in such a
3.40 +way that it could be convenient to use many different data files (or to
3.41 +extract the information dynamically, insert it into the form data
3.42 +document, and to provide a reference to the form data document as a
3.43 +source of value information).</p><p>Let us concentrate, however, on the
3.44 +latter, more convenient approach for our example application. In order
3.45 +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>
3.46 +parameter for the output stylesheet using the first language specified
3.47 +in each user's browser's language preferences. Then, we add a reference
3.48 +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 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;">,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>
3.49 +<h2>Further Reading</h2>
3.50 +<p>Now that we have designed and implemented a simple application, it
3.51 +may be worth reading some <a href="advice.html">recommendations</a>
3.52 +about developing your own applications.</p>
3.53 +</body></html>
3.54 \ No newline at end of file
4.1 --- a/docs/multiple.html Sat Dec 03 01:52:11 2005 +0000
4.2 +++ b/docs/multiple.html Sat Dec 03 01:53:18 2005 +0000
4.3 @@ -74,9 +74,9 @@
4.4 </li><li>The <code>value</code> attribute is set to a value which does not matter - it will be replaced in the final output.</li></ul>
4.5 <p>The result of this is that the <code>type</code> element in the
4.6 this example structure fragment...</p>
4.7 -<pre><type value="2"><br /> <type-enum value="1"/><br /> <type-enum value="2"/><br /> <type-enum value="3"/><br /></type></pre>
4.8 +<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>
4.9 <p>...is transformed into something resembling this HTML code:</p>
4.10 -<pre><select name="..."><br /> <option value="1">1</option><br /> <option value="2" selected="selected">2</option><br /> <option value="3">3</option><br /></select></pre>
4.11 +<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>
4.12 <p>Such presentation techniques are sufficient if the input form data
4.13 structure is identical to the output structure, but since we will
4.14 receive a structure resembling that defined
5.1 --- a/docs/multivalue.html Sat Dec 03 01:52:11 2005 +0000
5.2 +++ b/docs/multivalue.html Sat Dec 03 01:53:18 2005 +0000
5.3 @@ -66,9 +66,9 @@
5.4 as in the single-valued case. The result of the presentation of the
5.5 extra values is that the <code>type</code> element in the
5.6 this example structure fragment...</p>
5.7 -<pre><type><br /> <type-enum value="1"/><br /> <type-enum value="2" value-is-set="true"/><br /> <type-enum value="3" value-is-set="true"/><br /></type><br /></pre>
5.8 +<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>
5.9 <p>...is transformed into something resembling this HTML code:</p>
5.10 -<pre><select name="..." multiple="multiple"><br /> <option value="1">1</option><br /> <option value="2" selected="selected">2</option><br /> <option value="3" selected="selected">3</option><br /></select><br /></pre>
5.11 +<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>
5.12 <p>Above, the special <code>value-is-set</code>
5.13 attribute is an XSLForms mechanism to remember which values were set.
5.14 Fortunately, the document initialisation mechanism automatically
5.15 @@ -85,8 +85,8 @@
5.16 Note that it may be necessary to remove the old stylesheet for
5.17 producing output, <code>structure_output.xsl</code>, so that the
5.18 multivalue version of the template is taken into use.</p>
5.19 -<h2>Further Reading</h2>
5.20 -<p>Now that we have designed and implemented a simple application, it
5.21 -may be worth reading some <a href="advice.html">recommendations</a>
5.22 -about developing your own applications.</p>
5.23 +<h2>Improving the Presented Values</h2>
5.24 +<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>
5.25 +and the same text is shown to users of the application. However, there
5.26 +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>
5.27 </body></html>
5.28 \ No newline at end of file
6.1 --- a/docs/overview.html Sat Dec 03 01:52:11 2005 +0000
6.2 +++ b/docs/overview.html Sat Dec 03 01:53:18 2005 +0000
6.3 @@ -19,7 +19,7 @@
6.4 <li><a href="Web-resource.html">Write a Web resource to display the
6.5 form</a></li>
6.6 <li><a href="multiple.html">Adding multiple-choice fields and values</a></li>
6.7 - <li><a href="multivalue.html">Adding multivalued fields</a></li>
6.8 + <li><a href="multivalue.html">Adding multivalued fields</a></li><li><a href="labels.html">Labelling multiple-choice values</a></li>
6.9 <li><a href="advice.html">Recommendations and advice</a></li>
6.10 <li><a href="in-page-updates.html">Adding in-page updates</a></li>
6.11 </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>
7.1 --- a/docs/reference.html Sat Dec 03 01:52:11 2005 +0000
7.2 +++ b/docs/reference.html Sat Dec 03 01:53:18 2005 +0000
7.3 @@ -12,7 +12,7 @@
7.4 attribute permits the inclusion of a section of the template document
7.5 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,
7.6 the underlying XPath mechanisms are exposed, and any XPath expression
7.7 -which tests aspects of the XML document can be written.</p><h3><a name="template:i18n"></a>template:i18n</h3><p>This
7.8 +which tests aspects of the XML document can be written.</p><h3><a name="i18n"></a>template:i18n</h3><p>This
7.9 attribute is used to translate the textual contents of an element to
7.10 another language where additional parameters specifying the language
7.11 and the whereabouts of the translations have been provided to the