1.1 --- a/docs/labels.html Sat Sep 08 16:53:18 2007 +0000
1.2 +++ b/docs/labels.html Sat Sep 08 16:53:34 2007 +0000
1.3 @@ -1,50 +1,50 @@
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>Creating Applications: Labelling Multiple-Choice Values</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.10 + <title>Creating Applications: Labelling Multiple-Choice Values</title>
1.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.12 <body>
1.13 <h1>Creating Applications: Labelling Multiple-Choice Values</h1>
1.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
1.15 simple applications with a limited audience, it is often acceptable to
1.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
1.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
1.18 must therefore consider introducing additional label information in
1.19 order to remedy the first case, at least. Consequently, we may modify
1.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,
1.21 we have provided user-visible labels which can now be used by the
1.22 template. A single change to the item type choices list is required to
1.23 include these labels as the visible text in that particular form
1.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>
1.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>
1.26 </ul><h3>Updating the Web Resource</h3>
1.27 -<p>To update the special WebStack resource, we
1.28 +<p>To update the special WebStack resource, we
1.29 now need to modify a few of the class attributes:</p>
1.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>
1.31 <p>With these adjustments, it should now be possible to see the
1.32 original labels and yet have the application manipulate a separate set
1.33 of internal values.
1.34 Note that it may be necessary to remove the old stylesheet for
1.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
1.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
1.37 the above work made it possible to satisfy the first motivation of the
1.38 use of labels - to hide internal values - it did not permit us to
1.39 provide translations for different languages. In fact, there are at
1.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
1.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
1.42 former approach might work in situations where multiple-choice values
1.43 are obtained from a repository, such as a database, which contains the
1.44 labels for items in each supported language. One can envisage a product
1.45 database, for example, containing product descriptions for each
1.46 language or market, and such information could be extracted in such a
1.47 way that it could be convenient to use many different data files (or to
1.48 -extract the information dynamically, insert it into the form data
1.49 +extract the information dynamically, insert it into the form data
1.50 document, and to provide a reference to the form data document as a
1.51 source of value information).</p><p>Let us concentrate, however, on the
1.52 latter, more convenient approach for our example application. In order
1.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>
1.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>
1.55 parameter for the output stylesheet using the first language specified
1.56 in each user's browser's language preferences. Then, we add a reference
1.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>
1.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>
1.59 <h2>Further Reading</h2>
1.60 <p>Now that we have designed and implemented a simple application, it
1.61 may be worth reading some <a href="advice.html">recommendations</a>
1.62 about developing your own applications.</p>
1.63 -</body></html>
1.64 \ No newline at end of file
1.65 +</body></html>