| paulb@615 | 1 | <?xml version="1.0" encoding="iso-8859-1"?> |
| paulb@444 | 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| paulb@444 | 3 | <html xmlns="http://www.w3.org/1999/xhtml"><head> |
| paulb@444 | 4 | <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> |
| paulb@615 | 5 | <title>Creating Applications: Labelling Multiple-Choice Values</title> |
| paulb@444 | 6 | <link href="styles.css" rel="stylesheet" type="text/css" /></head> |
| paulb@444 | 7 | <body> |
| paulb@444 | 8 | <h1>Creating Applications: Labelling Multiple-Choice Values</h1> |
| paulb@444 | 9 | <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 |
| paulb@444 | 10 | simple applications with a limited audience, it is often acceptable to |
| paulb@615 | 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 |
| paulb@444 | 12 | must therefore consider introducing additional label information in |
| paulb@444 | 13 | order to remedy the first case, at least. Consequently, we may modify |
| paulb@444 | 14 | 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, |
| paulb@444 | 15 | we have provided user-visible labels which can now be used by the |
| paulb@444 | 16 | template. A single change to the item type choices list is required to |
| paulb@444 | 17 | include these labels as the visible text in that particular form |
| paulb@615 | 18 | 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> |
| paulb@444 | 19 | </ul><h3>Updating the Web Resource</h3> |
| paulb@615 | 20 | <p>To update the special WebStack resource, we |
| paulb@444 | 21 | now need to modify a few of the class attributes:</p> |
| paulb@444 | 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> |
| paulb@444 | 23 | <p>With these adjustments, it should now be possible to see the |
| paulb@444 | 24 | original labels and yet have the application manipulate a separate set |
| paulb@444 | 25 | of internal values. |
| paulb@444 | 26 | Note that it may be necessary to remove the old stylesheet for |
| paulb@615 | 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 |
| paulb@444 | 28 | the above work made it possible to satisfy the first motivation of the |
| paulb@444 | 29 | use of labels - to hide internal values - it did not permit us to |
| paulb@444 | 30 | provide translations for different languages. In fact, there are at |
| paulb@615 | 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 |
| paulb@444 | 32 | former approach might work in situations where multiple-choice values |
| paulb@444 | 33 | are obtained from a repository, such as a database, which contains the |
| paulb@444 | 34 | labels for items in each supported language. One can envisage a product |
| paulb@444 | 35 | database, for example, containing product descriptions for each |
| paulb@444 | 36 | language or market, and such information could be extracted in such a |
| paulb@444 | 37 | way that it could be convenient to use many different data files (or to |
| paulb@615 | 38 | extract the information dynamically, insert it into the form data |
| paulb@444 | 39 | document, and to provide a reference to the form data document as a |
| paulb@444 | 40 | source of value information).</p><p>Let us concentrate, however, on the |
| paulb@444 | 41 | latter, more convenient approach for our example application. In order |
| paulb@615 | 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><?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> |
| paulb@444 | 43 | parameter for the output stylesheet using the first language specified |
| paulb@444 | 44 | in each user's browser's language preferences. Then, we add a reference |
| paul@678 | 45 | 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> |
| paulb@444 | 46 | <h2>Further Reading</h2> |
| paulb@444 | 47 | <p>Now that we have designed and implemented a simple application, it |
| paulb@444 | 48 | may be worth reading some <a href="advice.html">recommendations</a> |
| paulb@444 | 49 | about developing your own applications.</p> |
| paulb@615 | 50 | </body></html> |
