# HG changeset patch
# User Paul Boddie When introducing the item type multiple-choice field into the application, we defined the following values: For
-simple applications with a limited audience, it is often acceptable to
-use values which are then presented unchanged such that the value We
-must therefore consider introducing additional label information in
-order to remedy the first case, at least. Consequently, we may modify
-the defined values as follows: Here,
-we have provided user-visible labels which can now be used by the
-template. A single change to the item type choices list is required to
-include these labels as the visible text in that particular form
-control whilst maintaining the usage of the internal values: The addition, as described in the When introducing the item type multiple-choice field into the application, we defined the following values: For simple applications with a limited audience, it is often acceptable to
+use values which are then presented unchanged such that the value
+ We must therefore consider introducing additional label information in order
+to remedy the first case, at least. Consequently, we may modify the defined
+values as follows: Here, we have provided user-visible labels which can now be used by the
+template. A single change to the item type choices list is required to include
+these labels as the visible text in that particular form control whilst
+maintaining the usage of the internal values: The addition, as described in the To update the special WebStack resource, we
now need to modify a few of the class attributes: With these adjustments, it should now be possible to see the
-original labels and yet have the application manipulate a separate set
-of internal values.
-Note that it may be necessary to remove the old stylesheet for
-producing output, Whilst
-the above work made it possible to satisfy the first motivation of the
-use of labels - to hide internal values - it did not permit us to
-provide translations for different languages. In fact, there are at
-least two approaches which could provide labels in multiple languages: The
-former approach might work in situations where multiple-choice values
-are obtained from a repository, such as a database, which contains the
-labels for items in each supported language. One can envisage a product
-database, for example, containing product descriptions for each
-language or market, and such information could be extracted in such a
-way that it could be convenient to use many different data files (or to
-extract the information dynamically, insert it into the form data
-document, and to provide a reference to the form data document as a
-source of value information). Let us concentrate, however, on the
-latter, more convenient approach for our example application. In order
-to produce translated labels, we must first define a translations file as described in the "Internationalisation" document; this file can be saved alongside our other resources with the name To make use of this file, we must add additional references in the Web resource's attributes: And to introduce the translation mechanisms into the output production, we must modify the resource further: Here, we define a Finally, we have to change the template to make use of the translations: Note that we use the Now, upon adding items in the application, if the browser is set up appropriately - in this case using With these adjustments, it should now be possible to see the original labels
+and yet have the application manipulate a separate set of internal values.
+Note that it may be necessary to remove the old stylesheet for producing
+output, Whilst the above work made it possible to satisfy the first motivation of
+the use of labels - to hide internal values - it did not permit us to provide
+translations for different languages. In fact, there are at least two
+approaches which could provide labels in multiple languages: The former approach might work in situations where multiple-choice values
+are obtained from a repository, such as a database, which contains the labels
+for items in each supported language. One can envisage a product database, for
+example, containing product descriptions for each language or market, and such
+information could be extracted in such a way that it could be convenient to use
+many different data files (or to extract the information dynamically, insert it
+into the form data document, and to provide a reference to the form data
+document as a source of value information). Let us concentrate, however, on the latter, more convenient approach for our
+example application. In order to produce translated labels, we must first
+define a translations file
+as described in the "Internationalisation"
+document; this file can be saved alongside our other resources with the name
+ To make use of this file, we must add additional references in the Web
+resource's attributes: And to introduce the translation mechanisms into the output production, we
+must modify the resource further: Here, we define a Finally, we have to change the template to make use of the translations: Note that we use the Now, upon adding items in the application, if the
+browser is set up appropriately - in this case using Despite offering translations of labels, our work may not be complete. For
+long lists of values, it may be desirable to sort the choices in an order that
+is meaningful to the user, and it might not be possible to rely on a suitable
+ordering of values from the source which provides them. Consider a list of
+countries where the underlying multiple-choice value is a two letter country
+code. If such a list were presented sorted by the country codes, yet were to
+employ labels which gave the translated names of the countries, the ordering
+would seem almost arbitrary and difficult to navigate for the user. To resolve such matters, we have to introduce an additional annotation in
+order to control the ordering of choices: By requesting that the choices be sorted according to the translated label,
+they should have an ordering that the user can relate to and navigate more
+easily. Now that we have designed and implemented a simple application, it
may be worth reading some recommendations
about developing your own applications. Although some applications only require multiple-choice fields where
only a single value may be chosen, in many situations it is desirable
to be able to choose an arbitrary number of values for a particular
@@ -13,80 +14,189 @@
represent form data using a single attribute on a single element to
represent any given field value. With multivalued fields, we must
choose a different strategy in using XML to represent such information. Let us consider permitting multiple type values to be associated
with our items. We revise our form data structure
-to
-be the following:Creating Applications: Labelling Multiple-Choice Values
-<?xml version="1.0"?>
<type>
<type-enum value="(Not selected)"/>
<type-enum value="Important"/>
<type-enum value="Not important"/>
<type-enum value="Personal"/>
</type>Personal
is known both inside the application and is also shown to the user as the textual string Personal
. However, for other applications there may be good reasons not to show values directly in this way:123
representing the same concept as Personal
.Personal
may not be understood by users who do not speak or otherwise use the English language.?xml version="1.0"?>
<type>
<type-enum value="0">(Not selected)</type-enum>
<type-enum value="I">Important</type-enum>
<type-enum value="N">Not important</type-enum>
<type-enum value="P">Personal</type-enum>
</type> <p>
Item type:
<select template:multiple-choice-list-field="type,type-enum,value" name="..." multiple="multiple"
onchange="requestUpdate(
'comments',
'{template:list-attribute('type-enum', 'value')}',
'{template:other-elements(../options)}',
'{template:child-attribute('value', template:child-element('comment', 1, template:other-elements(../options)))}',
'/structure/item/options')">
<option template:multiple-choice-list-value="type-enum,value,selected,text()" value="..." />
</select>
</p>template:multiple-choice-value
and template:multiple-choice-list-value
sections of the "Template Attribute Reference" document, selects the text inside the appropriate type-enum
elements and inserts it as a label into each choice in the item type list.
-
Updating the Web Resource
+
+
+<?xml version="1.0"?>
+<type>
+ <type-enum value="(Not selected)"/>
+ <type-enum value="Important"/>
+ <type-enum value="Not important"/>
+ <type-enum value="Personal"/>
+</type>
+
+
+Personal
is known both inside the application and is also shown to
+the user as the textual string Personal
. However, for other
+applications there may be good reasons not to show values directly in this
+way:
+
+
+123
representing the same concept as Personal
.Personal
may not be understood by users who do
+ not speak or otherwise use the English language.?xml version="1.0"?>
+<type>
+ <type-enum value="0">(Not selected)</type-enum>
+ <type-enum value="I">Important</type-enum>
+ <type-enum value="N">Not important</type-enum>
+ <type-enum value="P">Personal</type-enum>
+</type>
+
+
+ <p>
+ Item type:
+ <select template:multiple-choice-list-field="type,type-enum,value" name="..." multiple="multiple"
+ onchange="requestUpdate(
+ 'comments',
+ '{template:list-attribute('type-enum', 'value')}',
+ '{template:other-elements(../options)}',
+ '{template:child-attribute('value', template:child-element('comment', 1, template:other-elements(../options)))}',
+ '/structure/item/options')">
+ <option template:multiple-choice-list-value="type-enum,value,selected,text()" value="..." />
+ </select>
+ </p>
+
+
+template:multiple-choice-value
+and template:multiple-choice-list-value
+sections of the "Template Attribute Reference"
+document, selects the text inside the appropriate type-enum
+elements and inserts it as a label into each choice in the item type list.Updating the Web Resource
+
template_resources = {
-
"structure" : ("structure_multivalue_label_template.xhtml", "structure_output.xsl")
}
init_resources = {
"structure" : ("structure_multivalue_label_template.xhtml", "structure_input.xsl")
}
document_resources = {
"types" : "structure_types_label.xml"
}structure_output.xsl
, so that the updated version of the template is taken into use.Translating Labels
types
and type-enum
elements for each language.translations.xml
, and its contents can be defined as follows:<?xml version="1.0" encoding="iso-8859-1"?>
<translations>
<locale>
<code value="nb"/>
<code value="nb_NO"/>
<translation value="(Not selected)">(Ikke valgt)</translation>
<translation value="Important">Viktig</translation>
<translation value="Not important">Ikke viktig</translation>
<translation value="Personal">Personlig</translation>
</locale>
</translations> document_resources = {
"types" : "structure_types_label.xml",
"translations" : "translations.xml"
} # Complete the response.
stylesheet_parameters["locale"] = trans.get_content_languages()[0]
self.send_output(trans, [trans_xsl], structure, stylesheet_parameters,
references={"translations" : self.prepare_document("translations")})locale
-parameter for the output stylesheet using the first language specified
-in each user's browser's language preferences. Then, we add a reference
-to the translations document specified above. <p>
Item type:
<select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple">
<option template:multiple-choice-list-value="type-enum,value,selected,template:i18n(text())" value="..." />
</select>
</p>template:i18n
extension function to modify the text found in each type-enum
element in the types document. The usage of this function is described in the extension function API documentation.Norwegian Bokmål [nb]
as the first choice of language - the item types will appear translated in the final output.
+ template_resources = {
+ "structure" : ("structure_multivalue_label_template.xhtml", "structure_output.xsl")
+ }
+ init_resources = {
+ "structure" : ("structure_multivalue_label_template.xhtml", "structure_input.xsl")
+ }
+ document_resources = {
+ "types" : "structure_types_label.xml"
+ }
+
+
+structure_output.xsl
, so that the updated version of the
+template is taken into use.Translating Labels
+
+
+
+
+types
and type-enum
+ elements for each language.translations.xml
, and its contents can be defined as follows:
+<?xml version="1.0" encoding="iso-8859-1"?>
+<translations>
+ <locale>
+ <code value="nb"/>
+ <code value="nb_NO"/>
+ <translation value="(Not selected)">(Ikke valgt)</translation>
+ <translation value="Important">Viktig</translation>
+ <translation value="Not important">Ikke viktig</translation>
+ <translation value="Personal">Personlig</translation>
+ </locale>
+</translations>
+
+
+ document_resources = {
+ "types" : "structure_types_label.xml",
+ "translations" : "translations.xml"
+ }
+
+
+
+ # Complete the response.
+
+ stylesheet_parameters["locale"] = trans.get_content_languages()[0]
+ self.send_output(trans, [trans_xsl], structure, stylesheet_parameters,
+ references={"translations" : self.prepare_document("translations")})
+
+
+locale
parameter for the output stylesheet
+using the first language specified in each user's browser's language
+preferences. Then, we add a reference to the translations document specified
+above.
+ <p>
+ Item type:
+ <select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple">
+ <option template:multiple-choice-list-value="type-enum,value,selected,template:i18n(text())" value="..." />
+ </select>
+ </p>
+
+
+template:i18n
+extension function to modify the text found in each type-enum
+element in the types document. The usage of this function is described in the
+extension function API
+documentation.Norwegian
+Bokmål [nb]
as the first choice of language - the item types will
+appear translated in the final output.Sorting Choices
+
+
+ <p>
+ Item type:
+ <select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple">
+ <option template:multiple-choice-list-value="type-enum,value,selected,template:i18n(text())" template:sort="template:i18n(text())" value="..." />
+ </select>
+ </p>
+
+
+Further Reading
+
Creating Applications: Adding Multivalued Fields
+
<?xml version="1.0"?>
+to be the following:
<structure>
<item value="some value">
<type>
<type-enum value="some type"/>
<type-enum value="some other type"/>
</type>
<subitem subvalue="some other value"/>
</item>
</structure>
<?xml version="1.0"?> +<structure> + <item value="some value"> + <type> + <type-enum value="some type"/> + <type-enum value="some other type"/> + </type> + <subitem subvalue="some other value"/> + </item> +</structure>+
We shall now take advantage of those HTML form fields which permit -users to select one -or many values presented in a list or menu.
+users to select one or many values presented in a list or menu.Some item:
Item type: - +
Itself containing more items:
Sub-item:
-From the item type list many value may now be selected. +From the item type list many values may now be selected.
+Taking the example HTML code from before, we can add a definition of this new list to the template to produce something like this:
-<html xmlns="http://www.w3.org/1999/xhtml"+ +
xmlns:template="http://www.boddie.org.uk/ns/xmltools/template">
<head>
<title>Example</title>
</head>
<body template:element="structure">
<form action="" method="post">
<!-- Template text between the start and the interesting part. -->
<div template:element="item">
<p>
Some item: <input template:attribute-field="value" name="..." type="text" value="..." />
<input name="..." template:selector-field="remove" type="submit" value="Remove" />
</p>
<p>
Item type:
<select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple">
<option template:multiple-choice-list-value="type-enum,value,selected" value="..." />
</select>
</p>
<p>
Itself containing more items:
</p>
<p template:element="subitem">
Sub-item: <input template:attribute-field="subvalue" name="..." type="text" value="..." />
<input name="..." template:selector-field="remove2" type="submit" value="Remove" />
</p>
<p>
<input name="..." template:selector-field="add2,subitem" type="submit" value="Add subitem" />
</p>
</div>
<p>
<input name="..." template:selector-field="add,item" type="submit" value="Add item" />
</p>
<!-- Template text between the interesting part and the end. -->
</form>
</body>
</html>
<html xmlns="http://www.w3.org/1999/xhtml" + xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"> +<head> + <title>Example</title> +</head> +<body template:element="structure"> +<form action="" method="post"> + +<!-- Template text between the start and the interesting part. --> + +<div template:element="item"> + <p> + Some item: <input template:attribute-field="value" name="..." type="text" value="..." /> + <input name="..." template:selector-field="remove" type="submit" value="Remove" /> + </p> + <p> + Item type: + <select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple"> + <option template:multiple-choice-list-value="type-enum,value,selected" value="..." /> + </select> + </p> + <p> + Itself containing more items: + </p> + <p template:element="subitem"> + Sub-item: <input template:attribute-field="subvalue" name="..." type="text" value="..." /> + <input name="..." template:selector-field="remove2" type="submit" value="Remove" /> + </p> + <p> + <input name="..." template:selector-field="add2,subitem" type="submit" value="Add subitem" /> + </p> +</div> +<p> + <input name="..." template:selector-field="add,item" type="submit" value="Add item" /> +</p> + +<!-- Template text between the interesting part and the end. --> + +</form> +</body> +</html>+
From the previous single-valued case, some crucial changes have been made:
+select
element remains mapped onto the type
-element in the form data structure. However, we use a different attribute, template:multiple-choice-list-field
, to indicate that a type
-element is created when the form data is submitted, but instead of a single value being added to the value
attribute of that one element, a separate type-enum
-element is created within the type
-element with a value in its value
attribute for each value submitted. This means that many type-enum
-elements may be created within the type
-element, and each one of them will have a different value
attribute.template:multiple-choice-list-field
, to indicate that a
+ type
element is created when the form data is submitted, but
+ instead of a single value being added to the value
attribute of
+ that one element, a separate type-enum
element is created within
+ the type
element with a value in its value
attribute
+ for each value submitted. This means
+ that many type-enum
elements may be created within the
+ type
element, and each one of them will have a different
+ value
attribute.
select
element now has a multiple
-attribute defined to permit multiple value selections.select
element, the option
-element now employs the template:multiple-choice-list-value
annotation.template:multiple-choice-list-value
annotation.
Unlike in the single-valued case, the revised the form data structure for input is almost the same as the structure used by the template. Indeed, the subtle differences cannot be represented in our simplistic presentation of the structure:
-<?xml version="1.0"?>+ +
<structure>
<item value="some value">
<type>
<type-enum value="some type"/>
<type-enum value="some other type"/>
</type>
<subitem subvalue="some other value"/>
</item>
</structure>
<?xml version="1.0"?> +<structure> + <item value="some value"> + <type> + <type-enum value="some type"/> + <type-enum value="some other type"/> + </type> + <subitem subvalue="some other value"/> + </item> +</structure>+
In fact, the principal difference arises through the number of type-enum
elements that occur in the input, representing the values selected by
the user, and the number that occur in the output, representing the
complete range of values available for selection.
In most respects, the presentation of the extra values is the same
as in the single-valued case. The result of the presentation of the
extra values is that the type
element in the
this example structure fragment...
<type>+ +
<type-enum value="(Not selected)"/>
<type-enum value="Important" value-is-set="true"/>
<type-enum value="Not important" value-is-set="true"/>
<type-enum value="Personal"/>
</type>
<type> + <type-enum value="(Not selected)"/> + <type-enum value="Important" value-is-set="true"/> + <type-enum value="Not important" value-is-set="true"/> + <type-enum value="Personal"/> +</type> ++
...is transformed into something resembling this HTML code:
-<select name="..." multiple="multiple">+ +
<option value="(Not selected)">(Not selected)</option>
<option value="Important" selected="selected">Important</option>
<option value="Not important" selected="selected">Not important</option>
<option value="Personal">Personal</option>
</select>
<select name="..." multiple="multiple"> + <option value="(Not selected)">(Not selected)</option> + <option value="Important" selected="selected">Important</option> + <option value="Not important" selected="selected">Not important</option> + <option value="Personal">Personal</option> +</select> ++
Above, the special value-is-set
attribute is an XSLForms mechanism to remember which values were set.
Fortunately, the document initialisation mechanism automatically
distinguishes between different multiple-choice field types and
understands where the above approach needs to be employed.
To update the special WebStack resource, we now need to modify a few of the class attributes and to add a few others:
-template_resources = {+ +
"structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl")
}
+ template_resources = { + "structure" : ("structure_multivalue_template.xhtml", "structure_output.xsl") + } ++
With these adjustments, it should now be possible to manipulate the
items and subitems whilst specifying multiple type values on each item.
Note that it may be necessary to remove the old stylesheet for
producing output, structure_output.xsl
, so that the
multivalue version of the template is taken into use.
In the application we have been developing, we have been content to show the multiple-choice values as they are known in the application - that is, the application refers to values like Personal
-and the same text is shown to users of the application. However, there
-are various situations where this is not desirable, and the usage of separate labels is described in the next section of the development process.
In the application we have been developing, we have been content to show the
+multiple-choice values as they are known in the application - that is, the
+application refers to values like Personal
and the same text is
+shown to users of the application. However, there are various situations where
+this is not desirable, and the usage of separate
+labels is described in the next section of the development process.