# HG changeset patch # User paulb # Date 1131558095 0 # Node ID d7ed367db6c8fb02e25915ee6733e58e70c3049b # Parent 785bb89c052217799abf0b45af4e0267eba9d765 [project @ 2005-11-09 17:41:35 by paulb] Introduced better cross-referencing. diff -r 785bb89c0522 -r d7ed367db6c8 docs/design.html --- a/docs/design.html Wed Nov 09 17:41:12 2005 +0000 +++ b/docs/design.html Wed Nov 09 17:41:35 2005 +0000 @@ -37,7 +37,7 @@ the form fields added later actually perform some function when testing our application. -

Designing the Items

+

Designing the Items

Each of the items presented using the template may employ a simple label and a text field. Alongside these things, we may also wish to have a button which can be pressed to remove that item from its list. diff -r 785bb89c0522 -r d7ed367db6c8 docs/reference.html --- a/docs/reference.html Wed Nov 09 17:41:12 2005 +0000 +++ b/docs/reference.html Wed Nov 09 17:41:35 2005 +0000 @@ -4,32 +4,32 @@

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, 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, 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, the underlying XPath mechanisms are exposed, and any XPath expression -which tests aspects of the XML document can be written.

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 +which tests aspects of the XML document can be written.

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 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 @@ -41,7 +41,7 @@ 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 @@ -51,21 +51,21 @@ "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]

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.

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.

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>

Syntax:

list-element-name,list-attribute-name,attribute-to-create-when-selected

Related attributes:

Implementing attributes:

template:multiple-choice-list-field

This attribute is similar to template:multiple-choice-field +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>

Syntax:

list-element-name,list-attribute-name,attribute-to-create-when-selected

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

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: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

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: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>

Syntax:

list-element-name,list-attribute-name,attribute-to-create-when-selected

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 +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>

Syntax:

list-element-name,list-attribute-name,attribute-to-create-when-selected

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 diff -r 785bb89c0522 -r d7ed367db6c8 docs/structure.html --- a/docs/structure.html Wed Nov 09 17:41:12 2005 +0000 +++ b/docs/structure.html Wed Nov 09 17:41:35 2005 +0000 @@ -21,7 +21,7 @@ special attributes and values.

-

Annotating the Template

+

Annotating the Template

Taking the template extract from above, we add special annotations to produce something like this:

<structure>                                   <body template:element="structure">

  <item                                         <div template:element="item">
                                                  <p>
        value="some value">                         Some item: <input template:attribute-field="value" name="..." type="text" value="..." />
                                                    <input name="remove" type="submit" value="Remove" />
                                                  </p>
                                                  <p>
                                                    Itself containing more items:
                                                  </p>
    <subitem                                      <p template:element="subitem">
             subvalue="some other value"/>          Sub-item: <input template:attribute-field="subvalue" name="..." type="text" value="..." />
                                                    <input name="remove2" type="submit" value="Remove" />
                                                  </p>
                                                  <p>
                                                    <input name="add2" type="submit" value="Add subitem" />
                                                  </p>
  </item>                                       </div>
                                                <p>
                                                  <input name="add" type="submit" value="Add item" />
                                                </p>

</structure>                                  </body>
diff -r 785bb89c0522 -r d7ed367db6c8 docs/template-design.html --- a/docs/template-design.html Wed Nov 09 17:41:12 2005 +0000 +++ b/docs/template-design.html Wed Nov 09 17:41:35 2005 +0000 @@ -21,65 +21,65 @@ representing the information in the user interface. The most common medium for presentation is HTML and its derivatives, and we consider here the different HTML elements available to present different -"patterns" in a document structure.

General Template Structure

Templates based on HTML usually have the following general structure:

<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:template="http://www.boddie.org.uk/ns/xmltools/template">
<head>
  <title>Some title</title>
</head>
<body template:element="structure">

<!-- The interesting part goes here... -->

</body>
</html>

Since we will want to edit the data produced by such a template, an HTML form element is usually necessary within the body element:

<body template:element="structure">
<form action="" method="POST">

<!-- The interesting part goes here... -->

</form>
</body>

We usually define the method as post in order to minimise complications with handling the data in the XSLForms toolkit.

Static Elements

Static +"patterns" in a document structure.

General Template Structure

Templates based on HTML usually have the following general structure:

<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:template="http://www.boddie.org.uk/ns/xmltools/template">
<head>
  <title>Some title</title>
</head>
<body template:element="structure">

<!-- The interesting part goes here... -->

</body>
</html>

Since we will want to edit the data produced by such a template, an HTML form element is usually necessary within the body element:

<body template:element="structure">
<form action="" method="POST">

<!-- The interesting part goes here... -->

</form>
</body>

We usually define the method as post in order to minimise complications with handling the data in the XSLForms toolkit.

Static Elements

Static elements, as opposed to collection elements, are elements in the form data document structure which maintain some kind of organisation or grouping within a document, but whose presence cannot be edited by the user of an application. For example, in the "Using the XSLFormsResource API" document the following example is given:

<div template:element="hard-disks">
  <input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/>
  <p template:element="hard-disk">
    ...
  </p>
</div>

Here, the hard-disks element is present to group hard-disk elements together. We can insist that elements are treated as static -elements in the document initialisation process by adding the template:init attribute to the annotated template element:

<div template:element="hard-disks" template:init="yes">
  ...
</div>

See the "Template Attribute Reference" document for more information on the template:init attribute.

Collection Elements

Collection +elements in the document initialisation process by adding the template:init attribute to the annotated template element:

<div template:element="hard-disks" template:init="yes">
  ...
</div>

See the "Template Attribute Reference" document for more information on the template:init attribute.

Collection Elements

Collection elements are elements in the form data document structure which represent a collection of items or objects and whose presence may be edited by the -user of an application. In the following example, hard-disk elements are collection elements:

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

Whether +user of an application. In the following example, hard-disk elements are collection elements:

<p template:element="hard-disk">
  ...
</p>

Whether elements are treated as collection elements in the document initialisation process depends on the presence or absence of the template:init attribute on the annotated template element: if the template:init attribute is present, the value of that attribute will determine whether such elements (named in the template:element attribute) will be created automatically (and thus behave like static elements) or created dynamically (and thus behave like collection elements); if the template:init attribute is absent, the way such elements are treated will depend on other factors, notably -the presence of selectors referring to such elements.

In the above example, the selector field (see below and in the "Template Attribute Reference" document for more details) mentions the document structure's hard-disk +the presence of selectors referring to such elements. Here is such a selector:

<input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/>

In the above example, the selector field (see below and in the "Template Attribute Reference" document for more details) mentions the document structure's hard-disk element; thus, the element is treated as a collection. If we did not have such a selector in the template, we could also have used a template:init attribute to have the same effect:

<p template:element="hard-disk" template:init="no">
  ...
</p>

Generally, collection elements do have selector fields providing operations on the -collection, and so the extra annotation is not usually necessary.

Selectors

As described in the "Creating Applications: Add Selectors" -document, selectors provide a means to select elements in collections +collection, and so the extra annotation is not usually necessary.

Selectors

Selectors provide a means to select elements in collections and to request that some operation be performed on those selected elements. Two common selector types are those concerning the addition -and removal of elements.

Selectors as Buttons

In the collection elements example above, we saw the usage of a selector which could be used to add elements to a document:

<input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/>

This would produce the following HTML form control:

As described in the "Using the XSLFormsResource API" document, the above selector (with the name add-hard-disk) +and removal of elements.

Selectors as Buttons

In the collection elements example above, we saw the usage of a selector which could be used to add elements to a document:

<input template:selector-field="add-hard-disk,hard-disk" type="submit" name="..." value="Add hard disk"/>

This would produce the following HTML form control:

As described in the "Using the XSLFormsResource API" document, the above selector (with the name add-hard-disk) could be obtained in the application itself, and the collection of elements associated with the selector used as a collection of places to insert new elements into the form data document. Similarly, a selector which could be used to remove elements from a document could be specified as follows:

<input template:selector-field="remove-hard-disk" type="submit" name="..." value="Remove hard disk"/>

This would produce the following HTML form control:

Again, such a selector could be obtained in the application, and the -associated elements could then be removed from the document.

Selectors as Checkboxes

Whilst +associated elements could then be removed from the document.

Selectors as Checkboxes

Whilst selectors can be modelled conveniently with buttons, since they may cause an immediate update to the form data with feedback from the operation occurring immediately, other form controls can be used to communicate the selection of form data. For example:

<input template:selector-field="select-hard-disk" type="checkbox" name="..." value="..."/>

This would produce the following HTML form control:

Such a checkbox could be used to mark a particular element in the form data document as being selected, with the application left to determine what -kind of operation should be applied to the selection.

Attribute Values

A +kind of operation should be applied to the selection.

Attribute Values

A simple attribute value is defined to be a value, freely editable set in an attribute on some element in a document. For example, in the form data document:

<element attribute="value"/>

The following sections describe ways in which the value can be viewed, edited or changed through the presentation of the attribute in the -template.

Editable Fields

If we are to permit an attribute value to be edited, we might choose the following template representation:

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

This would produce the following HTML form control:

Note +template.

Editable Fields

If we are to permit an attribute value to be edited, we might choose the following template representation:

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

This would produce the following HTML form control:

Note that the element on which the attribute is defined is not declared in the above example, although we could also add such an annotation to -the input element (as described above and in the "Template Attribute Reference" document).

Read-only Values

Where attribute values are only displayed, we can use non-form HTML elements to display them:

<span template:attribute-area="attribute">some text to be replaced with the value</span>

This would insert the value of the attribute in the document within the defined span template element.

Hidden Values

Where +the input element (as described above and in the "Template Attribute Reference" document).

Read-only Values

Where attribute values are only displayed, we can use non-form HTML elements to display them:

<span template:attribute-area="attribute">some text to be replaced with the value</span>

This would insert the value of the attribute in the document within the defined span template element.

Hidden Values

Where attribute values are to be retained and submitted again by the user, but probably not edited, we need to include them as hidden elements:

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

This keeps the contents of the document intact, but it should be noted that such values are only uneditable in the way they are presented to the user, and that a determined user could easily find a way to change -such values and send them in to the application.

Checkboxes

Sometimes, +such values and send them in to the application.

Checkboxes

Sometimes, attributes are used to retain particular values that correspond to a boolean state. Such values can be modelled as follows:

<input template:attribute-button="attribute,true,checked" name="..." value="..." type="checkbox"/>

This would produce the following HTML form control:

If selected, the checkbox would when submitted cause the attribute to contain the value true in the form data document. Moreover, the presence of the attribute with such a value would cause the checkbox to appear selected when the form -data is presented to the user again.

Radio Buttons

Unlike +data is presented to the user again.

Radio Buttons

Unlike checkboxes, radio buttons typically offer a means to select a value from a number of alternatives. However, like checkboxes the selected value would be stored on a single attribute in the form data document. @@ -95,14 +95,14 @@ and whilst such attributes typically reside in the form data document carrying a single, currently set value, the representation of the document processed by the template must somehow incorporate the list of -acceptable values; this was covered in the "Creating Applications: Adding Multiple-Choice Fields and Values" document, and involved adding new elements, each carrying a single acceptable value for the attribute concerned.

Single Selection Menus

In +acceptable values; this was covered in the "Creating Applications: Adding Multiple-Choice Fields and Values" document, and involved adding new elements, each carrying a single acceptable value for the attribute concerned.

Single Selection Menus

In certain situations, it makes more sense to present acceptable values for an attribute in a menu-like representation in the final output presented to the user. With the element on which the attribute resides now containing a list of sub-elements with each carrying an acceptable value in an attribute, a form control can be defined as follows:

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

This would produce the following HTML form control:

Note that the element on which the attribute is defined is not declared in the above example, although we could modify the template:multiple-choice-field annotation on -the select element (as described in the "Template Attribute Reference" document) and replace the - with a name such as element.

Multiple Selection Lists

In +the select element (as described in the "Template Attribute Reference" document) and replace the - with a name such as element.

Multiple Selection Lists

In other situations, where many values can be chosen, a single attribute on a single element is not sufficient to hold all such values. Consequently, a collection of elements is employed, each with an