XSLTools

docs/labels.html

615:f805e7565482
2007-09-08 paulb [project @ 2007-09-08 16:53:34 by paulb] Tidied the HTML, removing entities and adding XML declarations.
     1 <?xml version="1.0" encoding="iso-8859-1"?>     2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">     3 <html xmlns="http://www.w3.org/1999/xhtml"><head>     4   <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />     5   <title>Creating Applications: Labelling Multiple-Choice Values</title>     6   <link href="styles.css" rel="stylesheet" type="text/css" /></head>     7 <body>     8 <h1>Creating Applications: Labelling Multiple-Choice Values</h1>     9 <p>When introducing the item type multiple-choice field into the application, we defined the following values:</p><pre>&lt;?xml version="1.0"?&gt;<br />&lt;type&gt;<br />  &lt;type-enum value="(Not selected)"/&gt;<br />  &lt;type-enum value="Important"/&gt;<br />  &lt;type-enum value="Not important"/&gt;<br />  &lt;type-enum value="Personal"/&gt;<br />&lt;/type&gt;</pre><p>For    10 simple applications with a limited audience, it is often acceptable to    11 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 must therefore consider introducing additional label information in    13 order to remedy the first case, at least. Consequently, we may modify    14 the defined values as follows:</p><pre>?xml version="1.0"?&gt;<br />&lt;type&gt;<br />  &lt;type-enum value="0"&gt;(Not selected)&lt;/type-enum&gt;<br />  &lt;type-enum value="I"&gt;Important&lt;/type-enum&gt;<br />  &lt;type-enum value="N"&gt;Not important&lt;/type-enum&gt;<br />  &lt;type-enum value="P"&gt;Personal&lt;/type-enum&gt;<br />&lt;/type&gt;</pre><p>Here,    15 we have provided user-visible labels which can now be used by the    16 template. A single change to the item type choices list is required to    17 include these labels as the visible text in that particular form    18 control whilst maintaining the usage of the internal values:</p><pre>  &lt;p&gt;<br />    Item type:<br />    &lt;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')"&gt;<br />      &lt;option template:multiple-choice-list-value="type-enum,value,selected<span style="font-weight: bold;">,text()</span>" value="..." /&gt;<br />    &lt;/select&gt;<br />  &lt;/p&gt;</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>    19 </ul><h3>Updating the Web Resource</h3>    20 <p>To update the special WebStack resource, we    21 now need to modify a few of the class attributes:</p>    22 <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>    23 <p>With these adjustments, it should now be possible to see the    24 original labels and yet have the application manipulate a separate set    25 of internal values.    26 Note that it may be necessary to remove the old stylesheet for    27 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    28 the above work made it possible to satisfy the first motivation of the    29 use of labels - to hide internal values - it did not permit us to    30 provide translations for different languages. In fact, there are at    31 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    32 former approach might work in situations where multiple-choice values    33 are obtained from a repository, such as a database, which contains the    34 labels for items in each supported language. One can envisage a product    35 database, for example, containing product descriptions for each    36 language or market, and such information could be extracted in such a    37 way that it could be convenient to use many different data files (or to    38 extract the information dynamically, insert it into the form data    39 document, and to provide a reference to the form data document as a    40 source of value information).</p><p>Let us concentrate, however, on the    41 latter, more convenient approach for our example application. In order    42 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>&lt;?xml version="1.0" encoding="iso-8859-1"?&gt;<br />&lt;translations&gt;<br />  &lt;locale&gt;<br />    &lt;code value="nb"/&gt;<br />    &lt;code value="nb_NO"/&gt;<br />    &lt;translation value="(Not selected)"&gt;(Ikke valgt)&lt;/translation&gt;<br />    &lt;translation value="Important"&gt;Viktig&lt;/translation&gt;<br />    &lt;translation value="Not important"&gt;Ikke viktig&lt;/translation&gt;<br />    &lt;translation value="Personal"&gt;Personlig&lt;/translation&gt;<br />  &lt;/locale&gt;<br />&lt;/translations&gt;</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>    43 parameter for the output stylesheet using the first language specified    44 in each user's browser's language preferences. Then, we add a reference    45 to the translations document specified above.</p><p>Finally, we have to change the template to make use of the translations:</p><pre>  &lt;p&gt;<br />    Item type:<br />    &lt;select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple"&gt;<br />      &lt;option template:multiple-choice-list-value="type-enum,value,selected<span style="font-weight: bold;">,template:i18n(text())</span>" value="..." /&gt;<br />    &lt;/select&gt;<br />  &lt;/p&gt;</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&aring;l [nb]</code> as the first choice of language - the item types will appear translated in the final output.</p>    46 <h2>Further Reading</h2>    47 <p>Now that we have designed and implemented a simple application, it    48 may be worth reading some <a href="advice.html">recommendations</a>    49 about developing your own applications.</p>    50 </body></html>