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 10 <p>When introducing the item type multiple-choice field into the application, we defined the following values:</p> 11 12 <pre> 13 <?xml version="1.0"?> 14 <type> 15 <type-enum value="(Not selected)"/> 16 <type-enum value="Important"/> 17 <type-enum value="Not important"/> 18 <type-enum value="Personal"/> 19 </type> 20 </pre> 21 22 <p>For simple applications with a limited audience, it is often acceptable to 23 use values which are then presented unchanged such that the value 24 <code>Personal</code> is known both inside the application and is also shown to 25 the user as the textual string <code>Personal</code>. However, for other 26 applications there may be good reasons not to show values directly in this 27 way:</p> 28 29 <ol> 30 <li>There may be a special internal value which is not descriptive; for example 31 <code>123</code> representing the same concept as <code>Personal</code>.</li> 32 <li>The value might be understandable not be understandable to some users; for 33 example, the text <code>Personal</code> may not be understood by users who do 34 not speak or otherwise use the English language.</li> 35 </ol> 36 37 <p>We must therefore consider introducing additional label information in order 38 to remedy the first case, at least. Consequently, we may modify the defined 39 values as follows:</p> 40 41 <pre>?xml version="1.0"?> 42 <type> 43 <type-enum value="0">(Not selected)</type-enum> 44 <type-enum value="I">Important</type-enum> 45 <type-enum value="N">Not important</type-enum> 46 <type-enum value="P">Personal</type-enum> 47 </type></pre> 48 49 <p>Here, we have provided user-visible labels which can now be used by the 50 template. A single change to the item type choices list is required to include 51 these labels as the visible text in that particular form control whilst 52 maintaining the usage of the internal values:</p> 53 54 <pre> 55 <p> 56 Item type: 57 <select template:multiple-choice-list-field="type,type-enum,value" name="..." multiple="multiple" 58 onchange="requestUpdate( 59 'comments', 60 '{template:list-attribute('type-enum', 'value')}', 61 '{template:other-elements(../options)}', 62 '{template:child-attribute('value', template:child-element('comment', 1, template:other-elements(../options)))}', 63 '/structure/item/options')"> 64 <option template:multiple-choice-list-value="type-enum,value,selected<span style="font-weight: bold;">,text()</span>" value="..." /> 65 </select> 66 </p> 67 </pre> 68 69 <p>The addition, as described in the <a 70 href="reference.html#multiple-choice-value"><code>template:multiple-choice-value</code></a> 71 and <a href="reference.html#multiple-choice-list-value"><code>template:multiple-choice-list-value</code></a> 72 sections of the <a href="reference.html">"Template Attribute Reference"</a> 73 document, selects the text inside the appropriate <code>type-enum</code> 74 elements and inserts it as a label into each choice in the item type list.</p> 75 76 <h3>Updating the Web Resource</h3> 77 78 <p>To update the special WebStack resource, we 79 now need to modify a few of the class attributes:</p> 80 81 <pre> 82 template_resources = { 83 "structure" : ("structure_multivalue_label_template.xhtml", "structure_output.xsl") 84 } 85 init_resources = { 86 "structure" : ("structure_multivalue_label_template.xhtml", "structure_input.xsl") 87 } 88 document_resources = { 89 "types" : "structure_types_label.xml" 90 } 91 </pre> 92 93 <p>With these adjustments, it should now be possible to see the original labels 94 and yet have the application manipulate a separate set of internal values. 95 Note that it may be necessary to remove the old stylesheet for producing 96 output, <code>structure_output.xsl</code>, so that the updated version of the 97 template is taken into use.</p> 98 99 <h3>Translating Labels</h3> 100 101 <p>Whilst the above work made it possible to satisfy the first motivation of 102 the use of labels - to hide internal values - it did not permit us to provide 103 translations for different languages. In fact, there are at least two 104 approaches which could provide labels in multiple languages:</p> 105 106 <ol> 107 <li>Define a file containing the <code>types</code> and <code>type-enum</code> 108 elements for each language.</li> 109 <li>Use the internationalisation support in XSLForms to translate the 110 labels.</li> 111 </ol> 112 113 <p>The former approach might work in situations where multiple-choice values 114 are obtained from a repository, such as a database, which contains the labels 115 for items in each supported language. One can envisage a product database, for 116 example, containing product descriptions for each language or market, and such 117 information could be extracted in such a way that it could be convenient to use 118 many different data files (or to extract the information dynamically, insert it 119 into the form data document, and to provide a reference to the form data 120 document as a source of value information).</p> 121 122 <p>Let us concentrate, however, on the latter, more convenient approach for our 123 example application. In order to produce translated labels, we must first 124 define a <a href="internationalisation.html#PreparingTheTranslations">translations file</a> 125 as described in the <a href="internationalisation.html">"Internationalisation"</a> 126 document; this file can be saved alongside our other resources with the name 127 <code>translations.xml</code>, and its contents can be defined as follows:</p> 128 129 <pre> 130 <?xml version="1.0" encoding="iso-8859-1"?> 131 <translations> 132 <locale> 133 <code value="nb"/> 134 <code value="nb_NO"/> 135 <translation value="(Not selected)">(Ikke valgt)</translation> 136 <translation value="Important">Viktig</translation> 137 <translation value="Not important">Ikke viktig</translation> 138 <translation value="Personal">Personlig</translation> 139 </locale> 140 </translations></pre> 141 142 <p>To make use of this file, we must add additional references in the Web 143 resource's attributes:</p> 144 145 <pre> 146 document_resources = { 147 "types" : "structure_types_label.xml", 148 <span style="font-weight: bold;">"translations" : "translations.xml"</span> 149 } 150 </pre> 151 152 <p>And to introduce the translation mechanisms into the output production, we 153 must modify the resource further:</p> 154 155 <pre> 156 # Complete the response. 157 158 <span style="font-weight: bold;">stylesheet_parameters["locale"] = trans.get_content_languages()[0]</span> 159 self.send_output(trans, [trans_xsl], structure, stylesheet_parameters, 160 <span style="font-weight: bold;">references={"translations" : self.prepare_document("translations")}</span>) 161 </pre> 162 163 <p>Here, we define a <code>locale</code> parameter for the output stylesheet 164 using the first language specified in each user's browser's language 165 preferences. Then, we add a reference to the translations document specified 166 above.</p> 167 168 <p>Finally, we have to change the template to make use of the translations:</p> 169 170 <pre> 171 <p> 172 Item type: 173 <select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple"> 174 <option template:multiple-choice-list-value="type-enum,value,selected<span style="font-weight: bold;">,template:i18n(text())</span>" value="..." /> 175 </select> 176 </p> 177 </pre> 178 179 <p>Note that we use the <a 180 href="../apidocs/XSLForms.Output-module.html#i18n"><code>template:i18n</code></a> 181 extension function to modify the text found in each <code>type-enum</code> 182 element in the types document. The usage of this function is described in the 183 <a href="../apidocs/XSLForms.Output-module.html">extension function API 184 documentation</a>.</p><p>Now, upon adding items in the application, if the 185 browser is set up appropriately - in this case using <code>Norwegian 186 Bokm?l [nb]</code> as the first choice of language - the item types will 187 appear translated in the final output.</p> 188 189 <h3>Sorting Choices</h3> 190 191 <p>Despite offering translations of labels, our work may not be complete. For 192 long lists of values, it may be desirable to sort the choices in an order that 193 is meaningful to the user, and it might not be possible to rely on a suitable 194 ordering of values from the source which provides them. Consider a list of 195 countries where the underlying multiple-choice value is a two letter country 196 code. If such a list were presented sorted by the country codes, yet were to 197 employ labels which gave the translated names of the countries, the ordering 198 would seem almost arbitrary and difficult to navigate for the user.</p> 199 200 <p>To resolve such matters, we have to introduce an additional annotation in 201 order to control the ordering of choices:</p> 202 203 <pre> 204 <p> 205 Item type: 206 <select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple"> 207 <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="..." /> 208 </select> 209 </p> 210 </pre> 211 212 <p>By requesting that the choices be sorted according to the translated label, 213 they should have an ordering that the user can relate to and navigate more 214 easily.</p> 215 216 <h2>Further Reading</h2> 217 218 <p>Now that we have designed and implemented a simple application, it 219 may be worth reading some <a href="advice.html">recommendations</a> 220 about developing your own applications.</p> 221 </body></html>