# HG changeset patch # User paulb # Date 1191627859 0 # Node ID ae9fb603ea93ab05a7d2a0afff4f2e58ed329a31 # Parent 4da6f6b98efad2582f009fcb8d040c603fc46a24 [project @ 2007-10-05 23:44:19 by paulb] Improved documentation about XSLT extension functions and their use. Updated release information. diff -r 4da6f6b98efa -r ae9fb603ea93 docs/advanced.html --- a/docs/advanced.html Fri Oct 05 23:43:58 2007 +0000 +++ b/docs/advanced.html Fri Oct 05 23:44:19 2007 +0000 @@ -11,12 +11,17 @@ data documents (or just general XML documents with no special connection to Web forms). However, since XSLForms templates build upon XSL transformations, it is also possible to employ certain XSL -techniques to present the information in various different ways.

Templates and Transformations

When prepared, XSLForms templates are converted to XSL stylesheets, and +techniques to present the information in various different ways.

+ +

Templates and Transformations

+ +

When prepared, XSLForms templates are converted to XSL stylesheets, and when form data is displayed, such XSL stylesheets are used to transform the form data to a representation which looks like the original template, but with different parts of the template populated with the form data. The process can be illustrated as follows:

+ @@ -29,29 +34,80 @@
+

Since the stylesheet is based on XSL, which is a rich language in its own right, advanced template design techniques can involve some of the features of XSL - at least those which do not -affect the simplicity or general structure of our templates.

Template Extension Functions and Variables

One +affect the simplicity or general structure of our templates.

+ +

Template Extension Functions and Variables

+ +

One area where XSL features are already employed to affect the final output in XSLForms is in the toolkit's use of template extension functions and special variables - the latter being used in the output production process. For example, we might decide to use the lower level -template functions to present the value of an attribute:

<span template:attribute="some-attribute" template:value="$this-value">xxx</span>

In the above example, we reference the special variable $this-value which refers to the value of some-attribute. An example of template functions in use looks like this:

<span id="{template:this-element()}">xxx</span>

In the above example, we invoke the template function template:this-element +template functions to present the value of an attribute:

+ +
<span template:attribute="some-attribute" template:value="$this-value">xxx</span>
+ +

In the above example, we reference the special variable $this-value which refers to the value of some-attribute. An example of template functions in use looks like this:

+ +
<span id="{template:this-element()}">xxx</span>
+ +

In the above example, we invoke the template function template:this-element in order to create a unique identifier in the final output. Since we -use the function inside an attribute which is not prefixed with template, we must enclose the expression between { and } characters.

Beyond Template Extension Functions

Since +use the function inside an attribute which is not prefixed with template, we must enclose the expression between { and } characters.

+ +

Beyond Template Extension Functions

+ +

Since the above template extension functions and variables are merely special in the sense that XSLForms provides them to produce its output, and since they are accessed in the stylesheet using normal XSL-based mechanisms, there is no technical barrier to using other kinds of valid XSL (or more precisely, XPath) expressions in cases such as those given above. The -rules for using such expressions in attributes are straightforward:

Here is a trivial example of the usage of an XPath expression, based on one of the above examples:

<span template:attribute="some-attribute" template:value="string-length($this-value)">xxx</span>

In the above example, we invoke the standard XPath function string-length in order to produce within the span element the length of the value of some-attribute (instead of the actual value).

More +rules for using such expressions in attributes are straightforward:

+ + + +

Here is a trivial example of the usage of an XPath expression, based on one of the above examples:

+ +
<span template:attribute="some-attribute" template:value="string-length($this-value)">xxx</span>
+ +

In the above example, we invoke the standard XPath function string-length in order to produce within the span element the length of the value of some-attribute (instead of the actual value).

+ +

More interesting applications of XPath expressions and non-XSLForms functions arise when using more of the potential of XPath to select arbitrary elements and attributes and to perform calculations on the selected nodes. The following example originates from the Configurator -example application:

<span template:value="sum(/configuration//*[@value-is-set]/@price) + sum(/configuration//*[@value = ../@value]/@price)"></span>

This complicated expression, to be inserted within the span element, finds all elements in the system configuration having the value-is-set +example application:

+ +
<span template:value="sum(/configuration//*[@value-is-set]/@price) + sum(/configuration//*[@value = ../@value]/@price)"></span>
+ +

This complicated expression, to be inserted within the span element, finds all elements in the system configuration having the value-is-set attribute and adds their prices together; this total is combined with the sum of the prices from all elements marked as selected in their respective lists. In other words, it gets the total of all selected -components and inserts it into the final output.

+components and inserts it into the final output.

+ +

Using XSLT Extension Function Libraries

+ +

Unlike the standard XPath functions, the XSLT extension functions supported +by libxslt must have their library namespace declared within the template. For +example:

+ +
<span xmlns:math="http://exslt.org/math" math:expr-prefix="math http://exslt.org/math"
+  template:value="math:max(product/@price)">highest price</span>
+ +

Here, the math namespace is declared so that the +math:max function can be used. In addition, the +math:expr-prefix attribute ensures that such declarations are +preserved not only within the XSLForms framework and in the preparation of the +output stylesheet, but also as a measure to prevent potentially damaging edits +to the template. See the "Housekeeping Annotations" +section of the attribute reference guide for details.

+ + diff -r 4da6f6b98efa -r ae9fb603ea93 docs/index.html --- a/docs/index.html Fri Oct 05 23:43:58 2007 +0000 +++ b/docs/index.html Fri Oct 05 23:44:19 2007 +0000 @@ -11,23 +11,23 @@ libxml2, libxslt and (optionally) WebStack.

Setting Up

First of all, let us assume that the XSLTools distribution has been -unpacked and now sits in the XSLTools-0.5 directory.

+unpacked and now sits in the XSLTools-0.5.1 directory.

Before we begin, we must make sure that the XSLTools package is available -to Python. The easiest way to do this is to change into the XSLTools-0.5 directory and to run the setup.py +to Python. The easiest way to do this is to change into the XSLTools-0.5.1 directory and to run the setup.py script provided with the version of Python you are going to be using (possibly as a privileged user like root):

-
cd XSLTools-0.5
python setup.py install
+
cd XSLTools-0.5.1
python setup.py install

If you don't want to install XSLTools in this way, or if you can't do so because you don't have root privileges, you can just make sure -that the XSLTools-0.5 directory sits on your +that the XSLTools-0.5.1 directory sits on your PYTHONPATH.

Viewing the API Documentation

The API documentation for use in conjunction with this guide can be found inside the apidocs -directory within the XSLTools-0.5 directory. Of course, +directory within the XSLTools-0.5.1 directory. Of course, it is always possible to view the API documentation within Python by importing modules (such as XSLTools.XSLOutput) and using Python's built-in help function.

diff -r 4da6f6b98efa -r ae9fb603ea93 docs/reference.html --- a/docs/reference.html Fri Oct 05 23:43:58 2007 +0000 +++ b/docs/reference.html Fri Oct 05 23:44:19 2007 +0000 @@ -3,101 +3,587 @@ Template Attribute Reference -

Template Attribute Reference

+ + +

Template Attribute Reference

This document presents each of the attributes used in templates to annotate the structure of the XML documents being -presented and to modify the final output of the presented document.

Basic Annotations

The annotation attributes in this section are the most basic of those available. Apart from template:element and template:i18n, it is usually preferable to use the annotations listed in the "Convenience Annotations" section below.

template:element

This +presented and to modify the final output of the presented document.

+ +

Basic Annotations

+ +

The annotation attributes in this section are the most basic of those available. Apart from template:element and template:i18n, it is usually preferable to use the annotations listed in the "Convenience Annotations" section below.

+ +

template:element

+ +

This attribute associates the template element on which it is used with an element from the XML document being presented. Matching elements are found from the current position (or context), where the position -is updated upon entering a template element with a template:element or template:attribute annotation.

Example:

<p template:element="item">
  For each item element found, this section is produced.
  <span template:element="subitem">
    For each subitem element found within an item element, this is produced.
  </span>
  <span template:element="other">
    This is produced for each other element found within an item element.
  </span>
</p>

Example:

<p template:element="first,second,third">
  For each third element found, this section is produced.
</p>

Syntax:

element-name1[,element-name2[,...]]

Related attributes:

template:attribute

This attribute associates the template element on which it is used with an attribute in the XML document being presented.

Example:

<p template:element="item">
  <span template:attribute="value">
    This section is associated with the value attribute of the item element.
    To be really useful, we should also use other annotations to produce the value of the attribute.
  </span>
</p>

Syntax:

attribute-name

Related attributes:

template:value

This attribute produces, in the final output, the value of part of the XML document being presented.

Example:

<p template:element="item">
  <span template:attribute="value" template:value="$this-value">
    This text will be replaced by the value of the attribute, but the span template element will remain.
  </span>
</p>

Example:

<p template:element="item">
  <span template:attribute="value" template:value="$this-value" template:effect="replace">
    This text and its enclosing span element will be replaced by the value of the attribute.
  </span>
</p>

Syntax:

XPath-expression

Here, the underlying XPath mechanisms are exposed, but a number of useful shortcuts are available:

Other XPath expressions can be used to navigate from the current position to other nodes in the XML document.

Related attributes:

template:effect

This attribute modifies the effect of a template:value annotation.

Example:

(See above.)

Syntax:

insert|replace

Related attributes:

template:if

This +is updated upon entering a template element with a template:element or template:attribute annotation.

+ +

Example:

+ +
<p template:element="item">
  For each item element found, this section is produced.
  <span template:element="subitem">
    For each subitem element found within an item element, this is produced.
  </span>
  <span template:element="other">
    This is produced for each other element found within an item element.
  </span>
</p>
+ +

Example:

+ +
<p template:element="first,second,third">
  For each third element found, this section is produced.
</p>
+ +

Syntax:

+ +
element-name1[,element-name2[,...]]
+ +

Related attributes:

+ + + +

template:attribute

+ +

This attribute associates the template element on which it is used with an attribute in the XML document being presented.

+ +

Example:

+ +
<p template:element="item">
  <span template:attribute="value">
    This section is associated with the value attribute of the item element.
    To be really useful, we should also use other annotations to produce the value of the attribute.
  </span>
</p>
+ +

Syntax:

+ +
attribute-name
+ +

Related attributes:

+ + + +

template:value

+ +

This attribute produces, in the final output, the value of part of the XML document being presented.

+ +

Example:

+ +
<p template:element="item">
  <span template:attribute="value" template:value="$this-value">
    This text will be replaced by the value of the attribute, but the span template element will remain.
  </span>
</p>
+ +

Example:

+ +
<p template:element="item">
  <span template:attribute="value" template:value="$this-value" template:effect="replace">
    This text and its enclosing span element will be replaced by the value of the attribute.
  </span>
</p>
+ +

Syntax:

+ +
XPath-expression
+ +

Here, the underlying XPath mechanisms are exposed, but a number of useful shortcuts are available:

+ +Other XPath expressions can be used to navigate from the current position to other nodes in the XML document. + +

Related attributes:

+ + + +

template:effect

+ +

This attribute modifies the effect of a template:value annotation.

+ +

Example:

+ +

(See above.)

+ +

Syntax:

+ +
insert|replace
+ +

Related attributes:

+ + + +

template:if

+ +

This attribute permits the inclusion of a section of the template document -according to a test performed on the XML document being presented.

Example:

<p template:if="@value = 'true'">
  If the value attribute is set to the string value 'true', include this section.
</p>

Syntax:

XPath-expression

Here, +according to a test performed on the XML document being presented.

+ +

Example:

+ +
<p template:if="@value = 'true'">
  If the value attribute is set to the string value 'true', include this section.
</p>
+ +

Syntax:

+ +
XPath-expression
+ +

Here, the underlying XPath mechanisms are exposed, and any XPath expression -which tests aspects of the XML document can be written.

template:i18n

This +which tests aspects of the XML document can be written.

+ +

template:i18n

+ +

This attribute is used to translate the textual contents of an element to another language where additional parameters specifying the language and the whereabouts of the translations have been provided to the -stylesheet in the output generation process.

Example:

<span template:i18n="-">Hello</span>

In this example, the contents of the span element would be replaced with an appropriate translation for the text Hello.

Example:

<span template:i18n="hello">Hello</span>

In this example, the contents of the span element would be replaced with an appropriate translation using the token hello as a key in the translation dictionary.

Example:

<span template:i18n="{$this-value}">Hello</span>

In this example, the value of the special template variable $this-value is used as a key in the translation dictionary.

Syntax:

-|{expression}|token

See the "Internationalisation" document for more information on this attribute.

Initialisation Annotations

The annotation attributes in this section control the initialisation of documents where this is done by the XSLForms toolkit.

template:init

This attribute controls the creation of elements in the initialisation process and is used together with template:element. For each element name listed in a template:element annotation, the corresponding value in a template:init annotation states whether or how such elements are to be initialised.

Example:

<p template:element="item" template:init="no">
  Such item elements will not be created automatically when the document is initialised.
</p>

Example:

<p template:element="first,second,third" template:init="yes,yes,no">
  The first and second elements will be created automatically when the document is initialised.
  No third elements will be created automatically when the document is initialised.
</p>

Syntax:

yes|no|auto[,yes|no|auto[,...]]

Here, yes means that an element will be created automatically, no means that an element will not be created automatically (relying on the existence of such elements from before), and auto +stylesheet in the output generation process.

+ +

Example:

+ +
<span template:i18n="-">Hello</span>
+ +

In this example, the contents of the span element would be replaced with an appropriate translation for the text Hello.

+ +

Example:

+ +
<span template:i18n="hello">Hello</span>
+ +

In this example, the contents of the span element would be replaced with an appropriate translation using the token hello as a key in the translation dictionary.

+ +

Example:

+ +
<span template:i18n="{$this-value}">Hello</span>
+ +

In this example, the value of the special template variable $this-value is used as a key in the translation dictionary.

+ +

Syntax:

+ +
-|{expression}|token
+ +

See the "Internationalisation" document for more information on this attribute.

+ +

Initialisation Annotations

+ +

The annotation attributes in this section control the initialisation of documents where this is done by the XSLForms toolkit.

+ +

template:init

+ +

This attribute controls the creation of elements in the initialisation process and is used together with template:element. For each element name listed in a template:element annotation, the corresponding value in a template:init annotation states whether or how such elements are to be initialised.

+ +

Example:

+ +
<p template:element="item" template:init="no">
  Such item elements will not be created automatically when the document is initialised.
</p>
+ +

Example:

+ +
<p template:element="first,second,third" template:init="yes,yes,no">
  The first and second elements will be created automatically when the document is initialised.
  No third elements will be created automatically when the document is initialised.
</p>
+ +

Syntax:

+ +
yes|no|auto[,yes|no|auto[,...]]
+ +

Here, yes means that an element will be created automatically, no means that an element will not be created automatically (relying on the existence of such elements from before), and auto means that the initialisation process will attempt to guess whether an element should be created automatically (by looking for selectors which use the element's name and only creating elements where no such -selectors could be found). Where no values are provided, auto is assumed.

Related attributes:

Convenience Annotations

The +selectors could be found). Where no values are provided, auto is assumed.

+ +

Related attributes:

+ + + +

Convenience Annotations

+ +

The annotation attributes in this section provide more convenient ways of -presenting the XML document information in the final output.

template:attribute-field

This +presenting the XML document information in the final output.

+ +

template:attribute-field

+ +

This attribute associates the template element on which it is used with an attribute from the XML document, whilst providing certain other -attributes in the final output:

Example:

<input template:attribute-field="name" name="..." value="..." type="text"/>

This would be output as follows:

<input name="path-to-name" value="value-of-name" type="text"/>

...where path-to-name and value-of-name would be replaced with the appropriate computed values.

Syntax:

attribute-name

Related attributes:

Implementing attributes:

template:attribute-area

This +attributes in the final output:

+ + + +

Example:

+ +
<input template:attribute-field="name" name="..." value="..." type="text"/>
+ +

This would be output as follows:

+ +
<input name="path-to-name" value="value-of-name" type="text"/>
+ +

...where path-to-name and value-of-name would be replaced with the appropriate computed values.

+ +

Syntax:

+ +
attribute-name
+ +

Related attributes:

+ + + +

Implementing attributes:

+ + + +

template:attribute-area

+ +

This attribute associates the template element on which it is used with an attribute from the XML document being presented, much in the way that template:attribute-field does. However, the attribute value is not inserted into an attribute in the final output; instead it is inserted into the output in a different way according to -additional information specified in the annotation.

Example:

<textarea template:attribute-area="name" name="..." cols="40" rows="5">
  This text will be replaced by the value of the name attribute from the document being presented.
  The textarea element will enclose the attribute value in the final output.
</textarea>

Example:

<p>
  The name is:
  <span template:attribute-area="name,replace">
    This text will be replaced in the final output, and the span element will not be reproduced.
  </span>
</p>

Syntax:

attribute-name[,insert|replace]

By default, the value of attribute-name is inserted within the template element on which the annotation appears, and this is equivalent to specifying insert. If replace is specified, the template element is entirely replaced by the value of attribute-name.

Related attributes:

Implementing attributes:

template:attribute-button

This attribute associates the template element on which it is used +additional information specified in the annotation.

+ +

Example:

+ +
<textarea template:attribute-area="name" name="..." cols="40" rows="5">
  This text will be replaced by the value of the name attribute from the document being presented.
  The textarea element will enclose the attribute value in the final output.
</textarea>
+ +

Example:

+ +
<p>
  The name is:
  <span template:attribute-area="name,replace">
    This text will be replaced in the final output, and the span element will not be reproduced.
  </span>
</p>
+ +

Syntax:

+ +
attribute-name[,insert|replace]
+ +

By default, the value of attribute-name is inserted within the template element on which the annotation appears, and this is equivalent to specifying insert. If replace is specified, the template element is entirely replaced by the value of attribute-name.

+ +

Related attributes:

+ + + +

Implementing attributes:

+ + + +

template:attribute-button

+ +

This attribute associates the template element on which it is used with an attribute from the XML document, whilst providing certain other -attributes in the final output, much like template:attribute-field does, but with features which make the presentation of buttons and related user interface controls much simpler:

Example:

<input template:attribute-button="question-type,text,checked" name="..." value="..." type="radio"/>

This would produce a "radio" button like the following:

<input name="path-to-question-type" value="text" type="radio"/>

If the value of question-type was set to text, output like the following would be produced:

<input name="path-to-question-type" value="text" type="radio" checked="checked"/>

In an XHTML document, this would cause the "radio" button to appear selected or activated.

Syntax:

attribute-name,attribute-value,attribute-to-create-when-set

Related attributes:

Implementing attributes:

template:selector-field

This +attributes in the final output, much like template:attribute-field does, but with features which make the presentation of buttons and related user interface controls much simpler:

+ + + +

Example:

+ +
<input template:attribute-button="question-type,text,checked" name="..." value="..." type="radio"/>
+ +

This would produce a "radio" button like the following:

+ +
<input name="path-to-question-type" value="text" type="radio"/>
+ +

If the value of question-type was set to text, output like the following would be produced:

+ +
<input name="path-to-question-type" value="text" type="radio" checked="checked"/>
+ +

In an XHTML document, this would cause the "radio" button to appear selected or activated.

+ +

Syntax:

+ +
attribute-name,attribute-value,attribute-to-create-when-set
+ +

Related attributes:

+ + + +

Implementing attributes:

+ + + +

template:selector-field

+ +

This attribute permits the definition of references to the parts of the XML document being presented which are associated with the template elements in which it is used. When used in certain HTML form-related elements, it becomes possible to receive and obtain such references from the XSLForms toolkit and to then access the selected parts of the -original document.

Example:

<p template:element="item">
  <input template:selector-field="remove" name="..." value="Remove this item" type="submit"/>
</p>

Example:

<p template:element="item">
  An item...
</p>
<input template:selector-field="add,item" name="..." value="Add item" type="submit"/>

Syntax:

selector-name[,element-name]

The +original document.

+ +

Example:

+ +
<p template:element="item">
  <input template:selector-field="remove" name="..." value="Remove this item" type="submit"/>
</p>
+ +

Example:

+ +
<p template:element="item">
  An item...
</p>
<input template:selector-field="add,item" name="..." value="Add item" type="submit"/>
+ +

Syntax:

+ +
selector-name[,element-name]
+ +

The optional element name can be used to associate the selector with other elements; when this is done, the initialisation of the XML document will be affected such that the named element will not be automatically created in the initialisation process, since the presence of the selector implies that such elements can be added and removed in the -application user interface.

Related attributes:

Multiple-choice Annotations

The annotation attributes in this section provide ways of presenting enumerations and selections of values.

template:multiple-choice-field

This +application user interface.

+ +

Related attributes:

+ + + +

Multiple-choice Annotations

+ +

The annotation attributes in this section provide ways of presenting enumerations and selections of values.

+ +

template:multiple-choice-field

+ +

This attribute associates the template element on which it is used with an attribute in the XML document being presented whose value is to be chosen from a list of possibilities. The list itself is represented by a list of elements, each having an attribute with a distinct value; such information is added in the initialisation of the document before it is presented, since it is not part of the -"essential" information in the document.

Example:

<select template:multiple-choice-field="base-system,value" name="...">
  ...
</select>

Example:

<select template:multiple-choice-field="-,question-type" name="...">
  ...
</select>

See below for an example combining this attribute with the template:multiple-choice-value attribute.

Syntax:

element-name|-,attribute-name[,new|,new,dynamic|,,dynamic]

Where the special value - +"essential" information in the document.

+ +

Example:

+ +
<select template:multiple-choice-field="base-system,value" name="...">
  ...
</select>
+ +

Example:

+ +
<select template:multiple-choice-field="-,question-type" name="...">
  ...
</select>
+ +

See below for an example combining this attribute with the template:multiple-choice-value attribute.

+ +

Syntax:

+ +
element-name|-,attribute-name[,new|,new,dynamic|,,dynamic]
+ +

Where the special value - is given as the element name, the context element is chosen as the element in the XML document being presented whose attribute is -involved. Where the optional parameter new is given, the attribute is assumed not to already exist on the element. Where the optional parameter dynamic is given, the source of the multiple-choice values is considered to be found dynamically rather than from another document.

Related attributes:

Implementing attributes:

template:multiple-choice-value

This +involved. Where the optional parameter new is given, the attribute is assumed not to already exist on the element. Where the optional parameter dynamic is given, the source of the multiple-choice values is considered to be found dynamically rather than from another document.

+ +

Related attributes:

+ + + +

Implementing attributes:

+ + + +

template:multiple-choice-value

+ +

This attribute associates the template element on which it is used with an element in the XML document being presented whose purpose is to hold -one of a list of selectable values (as described above).

Example:

<select template:multiple-choice-field="base-system,value" name="...">
  <option template:multiple-choice-value="base-system-enum,value,selected" value="..."/>
</select>

This presents the following document fragment:

<base-system value="c">
  <base-system-enum value="a"/>
  <base-system-enum value="b"/>
  <base-system-enum value="c"/>
</base-system>

The output from the combination of the above would be as follows:

<select name="path-to-base-system">
  <option value="a">a</option>
  <option value="b">b</option>
  <option value="c" selected="selected">c</option>
</select>

Values and Labels

Labels different from the actual values employed can be specified using an extra parameter in the annotation:

<select template:multiple-choice-field="base-system,value" name="...">
  <option template:multiple-choice-value="base-system-enum,value,selected,text()" value="..."/>
</select>

This +one of a list of selectable values (as described above).

+ +

Example:

+ +
<select template:multiple-choice-field="base-system,value" name="...">
  <option template:multiple-choice-value="base-system-enum,value,selected" value="..."/>
</select>
+ +

This presents the following document fragment:

+ +
<base-system value="c">
  <base-system-enum value="a"/>
  <base-system-enum value="b"/>
  <base-system-enum value="c"/>
</base-system>
+ +

The output from the combination of the above would be as follows:

+ +
<select name="path-to-base-system">
  <option value="a">a</option>
  <option value="b">b</option>
  <option value="c" selected="selected">c</option>
</select>
+ +

Values and Labels

+ +

Labels different from the actual values employed can be specified using an extra parameter in the annotation:

+ +
<select template:multiple-choice-field="base-system,value" name="...">
  <option template:multiple-choice-value="base-system-enum,value,selected,text()" value="..."/>
</select>
+ +

This additional parameter is an XPath expression whose context is the current value-bearing element. The above example selects the text from -inside each base-system-enum element in the modified document fragment presented below.

A modified document fragment providing the labels can be written as follows:

<base-system value="c">
  <base-system-enum value="a">A</base-system-enum>
  <base-system-enum value="b">B</base-system-enum>
  <base-system-enum value="c">C</base-system-enum>
</base-system>

The output from the modified combination would be as follows:

<select name="path-to-base-system">
  <option value="a">A</option>
  <option value="b">B</option>
  <option value="c" selected="selected">C</option>
</select>

Syntax:

list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]

Related attributes:

Implementing attributes:

template:multiple-choice-list-field

This attribute is similar to template:multiple-choice-field +inside each base-system-enum element in the modified document fragment presented below.

+ +

A modified document fragment providing the labels can be written as follows:

+ +
<base-system value="c">
  <base-system-enum value="a">A</base-system-enum>
  <base-system-enum value="b">B</base-system-enum>
  <base-system-enum value="c">C</base-system-enum>
</base-system>
+ +

The output from the modified combination would be as follows:

+ +
<select name="path-to-base-system">
  <option value="a">A</option>
  <option value="b">B</option>
  <option value="c" selected="selected">C</option>
</select>
+ +

Syntax:

+ +
list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]
+ +

Related attributes:

+ + + +

Implementing attributes:

+ + + +

template:multiple-choice-list-field

+ +

This attribute is similar to template:multiple-choice-field except that it associates the template element on which it is used with an element in the XML document being presented containing a list of elements whose values have been selected. This list of selected elements is expanded before presentation to include elements whose values have not been selected. Consequently, the selected elements are marked in a particular way to distinguish them from the non-selected -elements.

Example:

<select template:multiple-choice-list-field="question-types,question-type-enum,question-type" name="..." multiple="multiple">
  ...
</select>

See below for an example combining this attribute with the template:multiple-choice-list-value attribute.

Syntax:

element-name|-,list-element-name,list-attribute-name[,dynamic]

Here, element-name is the element in the document being presented which contains the selected value elements; if the special value - is given then the context element is the element containing the selected value elements. The list-element-name and list-attribute-name indicate the details of the elements providing the list of selectable values. Where the optional parameter dynamic is given, the source of the multiple-choice values is considered to be found dynamically rather than from another document.

Related attributes:

Implementing attributes:

template:multiple-choice-list-value

This attribute is similar to template:multiple-choice-value +elements.

+ +

Example:

+ +
<select template:multiple-choice-list-field="question-types,question-type-enum,question-type" name="..." multiple="multiple">
  ...
</select>
+ +

See below for an example combining this attribute with the template:multiple-choice-list-value attribute.

+ +

Syntax:

+ +
element-name|-,list-element-name,list-attribute-name[,dynamic]
+ +

Here, element-name is the element in the document being presented which contains the selected value elements; if the special value - is given then the context element is the element containing the selected value elements. The list-element-name and list-attribute-name indicate the details of the elements providing the list of selectable values. Where the optional parameter dynamic is given, the source of the multiple-choice values is considered to be found dynamically rather than from another document.

+ +

Related attributes:

+ + + +

Implementing attributes:

+ + + +

template:multiple-choice-list-value

+ +

This attribute is similar to template:multiple-choice-value in that it associates the template element on which it is used with an element holding a value in a list of selectable values, with the principal difference that potentially many such values may be selected -in this case.

Example:

<select template:multiple-choice-list-field="question-types,question-type-enum,question-type" multiple="multiple">
  <option template:multiple-choice-list-value="question-type-enum,question-type,selected" value="..."/>
</select>

This presents the following document fragment:

<question-types>
  <question-type-enum question-type="text"/>
  <question-type-enum question-type="choice" value-is-set="true"/>
  <question-type-enum question-type="special" value-is-set="true"/>
</question-types>

The output from the combination of the above would be as follows:

<select name="path-to-question-types" multiple="multiple">
  <option value="text">text</option>
  <option value="choice" selected="selected">choice</option>
  <option value="special" selected="selected">special</option>
</select>

Values and Labels

Labels different from the actual values employed can be specified using an extra parameter in the annotation:

<select template:multiple-choice-list-field="question-types,question-type-enum,question-type" multiple="multiple">
  <option template:multiple-choice-list-value="question-type-enum,question-type,selected,text()" value="..."/>
</select>

This additional parameter is an XPath expression whose context is +in this case.

+ +

Example:

+ +
<select template:multiple-choice-list-field="question-types,question-type-enum,question-type" multiple="multiple">
  <option template:multiple-choice-list-value="question-type-enum,question-type,selected" value="..."/>
</select>
+ +

This presents the following document fragment:

+ +
<question-types>
  <question-type-enum question-type="text"/>
  <question-type-enum question-type="choice" value-is-set="true"/>
  <question-type-enum question-type="special" value-is-set="true"/>
</question-types>
+ +

The output from the combination of the above would be as follows:

+ +
<select name="path-to-question-types" multiple="multiple">
  <option value="text">text</option>
  <option value="choice" selected="selected">choice</option>
  <option value="special" selected="selected">special</option>
</select>
+ +

Values and Labels

+ +

Labels different from the actual values employed can be specified using an extra parameter in the annotation:

+ +
<select template:multiple-choice-list-field="question-types,question-type-enum,question-type" multiple="multiple">
  <option template:multiple-choice-list-value="question-type-enum,question-type,selected,text()" value="..."/>
</select>
+ +

This additional parameter is an XPath expression whose context is the current value-bearing element. The above example selects the text -from inside each base-system-enum element in the modified document fragment presented below.

A modified document fragment providing the labels can be written as follows:

<question-types>
  <question-type-enum question-type="text">Text</question-type-enum>
  <question-type-enum question-type="choice" value-is-set="true">Choice</question-type-enum>
  <question-type-enum question-type="special" value-is-set="true">Special</question-type-enum>
</question-types>

The output from the modified combination would be as follows:

<select name="path-to-question-types" multiple="multiple">
  <option value="text">Text</option>
  <option value="choice" selected="selected">Choice</option>
  <option value="special" selected="selected">Special</option>
</select>

Syntax:

list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]

Related attributes:

Implementing attributes:

template:multiple-choice-list-element

This attribute works in much the same way as template:multiple-choice-list-field except that it does not add a name attribute to the template element on which it is used. The purpose of this attribute, along with template:attribute-list-button, is to provide an alternative approach to presenting lists of selectable values.

Example:

<p template:multiple-choice-list-element="question,question-types,question-type">
  ...
</p>

See below for an example combining this attribute with the template:attribute-list-button attribute.

Syntax:

element-name|-,list-element-name,list-attribute-name

Here, element-name is the element in the document being presented which contains the selected value elements; if the special value - is given then the context element is the element containing the selected value elements. The list-element-name and list-attribute-name indicate the details of the elements providing the list of selectable values.

Related attributes:

Implementing attributes:

template:attribute-list-button

This attribute works in much the same way as template:attribute-button +from inside each base-system-enum element in the modified document fragment presented below.

+ +

A modified document fragment providing the labels can be written as follows:

+ +
<question-types>
  <question-type-enum question-type="text">Text</question-type-enum>
  <question-type-enum question-type="choice" value-is-set="true">Choice</question-type-enum>
  <question-type-enum question-type="special" value-is-set="true">Special</question-type-enum>
</question-types>
+ +

The output from the modified combination would be as follows:

+ +
<select name="path-to-question-types" multiple="multiple">
  <option value="text">Text</option>
  <option value="choice" selected="selected">Choice</option>
  <option value="special" selected="selected">Special</option>
</select>
+ +

Syntax:

+ +
list-element-name,list-attribute-name,attribute-to-create-when-selected[,content-expression]
+ +

Related attributes:

+ + + +

Implementing attributes:

+ + + +

template:multiple-choice-list-element

+ +

This attribute works in much the same way as template:multiple-choice-list-field except that it does not add a name attribute to the template element on which it is used. The purpose of this attribute, along with template:attribute-list-button, is to provide an alternative approach to presenting lists of selectable values.

+ +

Example:

+ +
<p template:multiple-choice-list-element="question,question-types,question-type">
  ...
</p>
+ +

See below for an example combining this attribute with the template:attribute-list-button attribute.

+ +

Syntax:

+ +
element-name|-,list-element-name,list-attribute-name
+ +

Here, element-name is the element in the document being presented which contains the selected value elements; if the special value - is given then the context element is the element containing the selected value elements. The list-element-name and list-attribute-name indicate the details of the elements providing the list of selectable values.

+ +

Related attributes:

+ + + +

Implementing attributes:

+ + + +

template:attribute-list-button

+ +

This attribute works in much the same way as template:attribute-button does, but instead presents a button or related user interface control whose state reflects the presence of an attribute on an element in a -collection of elements.

Example:

<p template:multiple-choice-list-element="question,question-types,question-type">
  <input template:attribute-list-button="question-type,checked" name="..." value="..." type="checkbox"/>
</p>

Given an XML document like this...

<question>
  <question-types question-type="text" value-is-set="true"/>
  <question-types question-type="choice"/>
</question>

...the following would be produced as output:

<p>
  <input name="path-to-question-type" value="text" type="checkbox" checked="checked"/>
</p>
<p>
  <input name="path-to-question-type" value="choice" type="checkbox"/>
</p>

Syntax:

attribute-name,attribute-to-create-when-set

Related attributes:

Implementing attributes:

Internal Annotations

The special annotations template:expr and template:expr-attr +collection of elements.

+ +

Example:

+ +
<p template:multiple-choice-list-element="question,question-types,question-type">
  <input template:attribute-list-button="question-type,checked" name="..." value="..." type="checkbox"/>
</p>
+ +

Given an XML document like this...

+ +
<question>
  <question-types question-type="text" value-is-set="true"/>
  <question-types question-type="choice"/>
</question>
+ +

...the following would be produced as output:

+ +
<p>
  <input name="path-to-question-type" value="text" type="checkbox" checked="checked"/>
</p>
<p>
  <input name="path-to-question-type" value="choice" type="checkbox"/>
</p>
+ +

Syntax:

+ +
attribute-name,attribute-to-create-when-set
+ +

Related attributes:

+ + + +

Implementing attributes:

+ + + +

Internal Annotations

+ +

The special annotations template:expr and template:expr-attr are used respectively to test an XPath expression in the current context and to provide the name of an attribute which is to be created -in the final output, should the expression evaluate to a true value.

Housekeeping Annotations

In order to support explicit, additional namespaces in output document processing, the special expr-prefix +in the final output, should the expression evaluate to a true value.

+ +

Housekeeping Annotations

+ +

In order to support explicit, additional namespaces in output document processing, the special expr-prefix attribute can be used to ensure the presence of a namespace declaration in the generated stylesheet files. Consider the usage of various -stylesheet extension functions:

<body>
  <p>
    <span template:value="sum(str:split('1 2 3 4 5'))">result</span>
  </p>
</body>

For the stylesheet which produces the output, the str +stylesheet extension functions:

+ +
<body>
  <p>
    <span template:value="sum(str:split('1 2 3 4 5'))">result</span>
  </p>
</body>
+ +

For the stylesheet which produces the output, the str namespace will need to be declared somewhere. To do this, we must not only declare the namespace in the template document, but we must also provide a hint to the stylesheet processor that the namespace is important (even though it is only mentioned in the text of an attribute, which might persuade some XML processing toolkits to abandon -the namespace declaration).

<body xmlns:str="http://exslt.org/strings" str:expr-prefix="str http://exslt.org/strings">
  <p>
    <span template:value="sum(str:split('1 2 3 4 5'))">result</span>
  </p>
</body>

What the special expr-prefix +the namespace declaration).

+ +
<body xmlns:str="http://exslt.org/strings" str:expr-prefix="str http://exslt.org/strings">
  <p>
    <span template:value="sum(str:split('1 2 3 4 5'))">result</span>
  </p>
</body>
+ +

What the special expr-prefix attribute does is to provide that hint to the stylesheet processor, although XSLTools also uses the attribute for other internal purposes. -Consequently, the resulting output stylesheet is able to find the str:split extension function and to evaluate the expected result.

Fixing Annotations

One important application of the expr-prefix +Consequently, the resulting output stylesheet is able to find the str:split extension function and to evaluate the expected result.

+ +

Fixing Annotations

+ +

One important application of the expr-prefix attribute is the restoration of damaged attributes after the editing of a template document using a less than careful HTML editor. Consider the -above document fragment after a small edit in Nvu:

<body expr-prefix="str http://exslt.org/strings" str="http://exslt.org/strings">
  <p>
    <span value="sum(str:split('1 2 3 4 5'))">result!</span>
  </p>
</body>

Nvu has obviously decided to remove the str and template namespace prefixes. To revert this damage, a tool is provided with XSLTools called xslform_fix.py (found in the scripts directory in the source distribution), and this tool will attempt to re-add namespace declarations for template automatically (since the template namespace is obviously the basis of XSLForms) along with any namespaces declared using expr-prefix attributes. The tool is invoked as follows:

xslform_fix.py template.xhtml template_fixed.xhtml

Since +above document fragment after a small edit in Nvu:

+ +
<body expr-prefix="str http://exslt.org/strings" str="http://exslt.org/strings">
  <p>
    <span value="sum(str:split('1 2 3 4 5'))">result!</span>
  </p>
</body>
+ +

Nvu has obviously decided to remove the str and template namespace prefixes. To revert this damage, a tool is provided with XSLTools called xslform_fix.py (found in the scripts directory in the source distribution), and this tool will attempt to re-add namespace declarations for template automatically (since the template namespace is obviously the basis of XSLForms) along with any namespaces declared using expr-prefix attributes. The tool is invoked as follows:

+ +
xslform_fix.py template.xhtml template_fixed.xhtml
+ +

Since namespace declarations may be moved to the root element of the new template document, it is possible that some problems may result with documents using namespaces in advanced ways, but the tool