1.1 --- a/docs/labels.html Sun Nov 29 02:01:41 2009 +0100
1.2 +++ b/docs/labels.html Wed Feb 24 00:59:37 2010 +0100
1.3 @@ -6,44 +6,215 @@
1.4 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.5 <body>
1.6 <h1>Creating Applications: Labelling Multiple-Choice Values</h1>
1.7 -<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.8 -simple applications with a limited audience, it is often acceptable to
1.9 -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.10 -must therefore consider introducing additional label information in
1.11 -order to remedy the first case, at least. Consequently, we may modify
1.12 -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.13 -we have provided user-visible labels which can now be used by the
1.14 -template. A single change to the item type choices list is required to
1.15 -include these labels as the visible text in that particular form
1.16 -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.17 -</ul><h3>Updating the Web Resource</h3>
1.18 +
1.19 +<p>When introducing the item type multiple-choice field into the application, we defined the following values:</p>
1.20 +
1.21 +<pre>
1.22 +<?xml version="1.0"?>
1.23 +<type>
1.24 + <type-enum value="(Not selected)"/>
1.25 + <type-enum value="Important"/>
1.26 + <type-enum value="Not important"/>
1.27 + <type-enum value="Personal"/>
1.28 +</type>
1.29 +</pre>
1.30 +
1.31 +<p>For simple applications with a limited audience, it is often acceptable to
1.32 +use values which are then presented unchanged such that the value
1.33 +<code>Personal</code> is known both inside the application and is also shown to
1.34 +the user as the textual string <code>Personal</code>. However, for other
1.35 +applications there may be good reasons not to show values directly in this
1.36 +way:</p>
1.37 +
1.38 +<ol>
1.39 + <li>There may be a special internal value which is not descriptive; for example
1.40 + <code>123</code> representing the same concept as <code>Personal</code>.</li>
1.41 + <li>The value might be understandable not be understandable to some users; for
1.42 + example, the text <code>Personal</code> may not be understood by users who do
1.43 + not speak or otherwise use the English language.</li>
1.44 +</ol>
1.45 +
1.46 +<p>We must therefore consider introducing additional label information in order
1.47 +to remedy the first case, at least. Consequently, we may modify the defined
1.48 +values as follows:</p>
1.49 +
1.50 +<pre>?xml version="1.0"?>
1.51 +<type>
1.52 + <type-enum value="0">(Not selected)</type-enum>
1.53 + <type-enum value="I">Important</type-enum>
1.54 + <type-enum value="N">Not important</type-enum>
1.55 + <type-enum value="P">Personal</type-enum>
1.56 +</type></pre>
1.57 +
1.58 +<p>Here, we have provided user-visible labels which can now be used by the
1.59 +template. A single change to the item type choices list is required to include
1.60 +these labels as the visible text in that particular form control whilst
1.61 +maintaining the usage of the internal values:</p>
1.62 +
1.63 +<pre>
1.64 + <p>
1.65 + Item type:
1.66 + <select template:multiple-choice-list-field="type,type-enum,value" name="..." multiple="multiple"
1.67 + onchange="requestUpdate(
1.68 + 'comments',
1.69 + '{template:list-attribute('type-enum', 'value')}',
1.70 + '{template:other-elements(../options)}',
1.71 + '{template:child-attribute('value', template:child-element('comment', 1, template:other-elements(../options)))}',
1.72 + '/structure/item/options')">
1.73 + <option template:multiple-choice-list-value="type-enum,value,selected<span style="font-weight: bold;">,text()</span>" value="..." />
1.74 + </select>
1.75 + </p>
1.76 +</pre>
1.77 +
1.78 +<p>The addition, as described in the <a
1.79 +href="reference.html#multiple-choice-value"><code>template:multiple-choice-value</code></a>
1.80 +and <a href="reference.html#multiple-choice-list-value"><code>template:multiple-choice-list-value</code></a>
1.81 +sections of the <a href="reference.html">"Template Attribute Reference"</a>
1.82 +document, selects the text inside the appropriate <code>type-enum</code>
1.83 +elements and inserts it as a label into each choice in the item type list.</p>
1.84 +
1.85 +<h3>Updating the Web Resource</h3>
1.86 +
1.87 <p>To update the special WebStack resource, we
1.88 now need to modify a few of the class attributes:</p>
1.89 -<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.90 -<p>With these adjustments, it should now be possible to see the
1.91 -original labels and yet have the application manipulate a separate set
1.92 -of internal values.
1.93 -Note that it may be necessary to remove the old stylesheet for
1.94 -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.95 -the above work made it possible to satisfy the first motivation of the
1.96 -use of labels - to hide internal values - it did not permit us to
1.97 -provide translations for different languages. In fact, there are at
1.98 -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.99 -former approach might work in situations where multiple-choice values
1.100 -are obtained from a repository, such as a database, which contains the
1.101 -labels for items in each supported language. One can envisage a product
1.102 -database, for example, containing product descriptions for each
1.103 -language or market, and such information could be extracted in such a
1.104 -way that it could be convenient to use many different data files (or to
1.105 -extract the information dynamically, insert it into the form data
1.106 -document, and to provide a reference to the form data document as a
1.107 -source of value information).</p><p>Let us concentrate, however, on the
1.108 -latter, more convenient approach for our example application. In order
1.109 -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.110 -parameter for the output stylesheet using the first language specified
1.111 -in each user's browser's language preferences. Then, we add a reference
1.112 -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>
1.113 +
1.114 +<pre>
1.115 + template_resources = {
1.116 + "structure" : ("structure_multivalue_label_template.xhtml", "structure_output.xsl")
1.117 + }
1.118 + init_resources = {
1.119 + "structure" : ("structure_multivalue_label_template.xhtml", "structure_input.xsl")
1.120 + }
1.121 + document_resources = {
1.122 + "types" : "structure_types_label.xml"
1.123 + }
1.124 +</pre>
1.125 +
1.126 +<p>With these adjustments, it should now be possible to see the original labels
1.127 +and yet have the application manipulate a separate set of internal values.
1.128 +Note that it may be necessary to remove the old stylesheet for producing
1.129 +output, <code>structure_output.xsl</code>, so that the updated version of the
1.130 +template is taken into use.</p>
1.131 +
1.132 +<h3>Translating Labels</h3>
1.133 +
1.134 +<p>Whilst the above work made it possible to satisfy the first motivation of
1.135 +the use of labels - to hide internal values - it did not permit us to provide
1.136 +translations for different languages. In fact, there are at least two
1.137 +approaches which could provide labels in multiple languages:</p>
1.138 +
1.139 +<ol>
1.140 +<li>Define a file containing the <code>types</code> and <code>type-enum</code>
1.141 + elements for each language.</li>
1.142 +<li>Use the internationalisation support in XSLForms to translate the
1.143 + labels.</li>
1.144 +</ol>
1.145 +
1.146 +<p>The former approach might work in situations where multiple-choice values
1.147 +are obtained from a repository, such as a database, which contains the labels
1.148 +for items in each supported language. One can envisage a product database, for
1.149 +example, containing product descriptions for each language or market, and such
1.150 +information could be extracted in such a way that it could be convenient to use
1.151 +many different data files (or to extract the information dynamically, insert it
1.152 +into the form data document, and to provide a reference to the form data
1.153 +document as a source of value information).</p>
1.154 +
1.155 +<p>Let us concentrate, however, on the latter, more convenient approach for our
1.156 +example application. In order to produce translated labels, we must first
1.157 +define a <a href="internationalisation.html#PreparingTheTranslations">translations file</a>
1.158 +as described in the <a href="internationalisation.html">"Internationalisation"</a>
1.159 +document; this file can be saved alongside our other resources with the name
1.160 +<code>translations.xml</code>, and its contents can be defined as follows:</p>
1.161 +
1.162 +<pre>
1.163 +<?xml version="1.0" encoding="iso-8859-1"?>
1.164 +<translations>
1.165 + <locale>
1.166 + <code value="nb"/>
1.167 + <code value="nb_NO"/>
1.168 + <translation value="(Not selected)">(Ikke valgt)</translation>
1.169 + <translation value="Important">Viktig</translation>
1.170 + <translation value="Not important">Ikke viktig</translation>
1.171 + <translation value="Personal">Personlig</translation>
1.172 + </locale>
1.173 +</translations></pre>
1.174 +
1.175 +<p>To make use of this file, we must add additional references in the Web
1.176 +resource's attributes:</p>
1.177 +
1.178 +<pre>
1.179 + document_resources = {
1.180 + "types" : "structure_types_label.xml",
1.181 + <span style="font-weight: bold;">"translations" : "translations.xml"</span>
1.182 + }
1.183 +</pre>
1.184 +
1.185 +<p>And to introduce the translation mechanisms into the output production, we
1.186 +must modify the resource further:</p>
1.187 +
1.188 +<pre>
1.189 + # Complete the response.
1.190 +
1.191 + <span style="font-weight: bold;">stylesheet_parameters["locale"] = trans.get_content_languages()[0]</span>
1.192 + self.send_output(trans, [trans_xsl], structure, stylesheet_parameters,
1.193 + <span style="font-weight: bold;">references={"translations" : self.prepare_document("translations")}</span>)
1.194 +</pre>
1.195 +
1.196 +<p>Here, we define a <code>locale</code> parameter for the output stylesheet
1.197 +using the first language specified in each user's browser's language
1.198 +preferences. Then, we add a reference to the translations document specified
1.199 +above.</p>
1.200 +
1.201 +<p>Finally, we have to change the template to make use of the translations:</p>
1.202 +
1.203 +<pre>
1.204 + <p>
1.205 + Item type:
1.206 + <select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple">
1.207 + <option template:multiple-choice-list-value="type-enum,value,selected<span style="font-weight: bold;">,template:i18n(text())</span>" value="..." />
1.208 + </select>
1.209 + </p>
1.210 +</pre>
1.211 +
1.212 +<p>Note that we use the <a
1.213 +href="../apidocs/XSLForms.Output-module.html#i18n"><code>template:i18n</code></a>
1.214 +extension function to modify the text found in each <code>type-enum</code>
1.215 +element in the types document. The usage of this function is described in the
1.216 +<a href="../apidocs/XSLForms.Output-module.html">extension function API
1.217 +documentation</a>.</p><p>Now, upon adding items in the application, if the
1.218 +browser is set up appropriately - in this case using <code>Norwegian
1.219 +Bokmål [nb]</code> as the first choice of language - the item types will
1.220 +appear translated in the final output.</p>
1.221 +
1.222 +<h3>Sorting Choices</h3>
1.223 +
1.224 +<p>Despite offering translations of labels, our work may not be complete. For
1.225 +long lists of values, it may be desirable to sort the choices in an order that
1.226 +is meaningful to the user, and it might not be possible to rely on a suitable
1.227 +ordering of values from the source which provides them. Consider a list of
1.228 +countries where the underlying multiple-choice value is a two letter country
1.229 +code. If such a list were presented sorted by the country codes, yet were to
1.230 +employ labels which gave the translated names of the countries, the ordering
1.231 +would seem almost arbitrary and difficult to navigate for the user.</p>
1.232 +
1.233 +<p>To resolve such matters, we have to introduce an additional annotation in
1.234 +order to control the ordering of choices:</p>
1.235 +
1.236 +<pre>
1.237 + <p>
1.238 + Item type:
1.239 + <select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple">
1.240 + <option template:multiple-choice-list-value="type-enum,value,selected,template:i18n(text())" <span style="font-weight: bold;">template:sort="template:i18n(text())"</span> value="..." />
1.241 + </select>
1.242 + </p>
1.243 +</pre>
1.244 +
1.245 +<p>By requesting that the choices be sorted according to the translated label,
1.246 +they should have an ordering that the user can relate to and navigate more
1.247 +easily.</p>
1.248 +
1.249 <h2>Further Reading</h2>
1.250 +
1.251 <p>Now that we have designed and implemented a simple application, it
1.252 may be worth reading some <a href="advice.html">recommendations</a>
1.253 about developing your own applications.</p>