# HG changeset patch # User paulb # Date 1131155061 0 # Node ID e79dda7b3fcb4d820eac468b5c3110bfdb966c61 # Parent cf1cf5e5bf6d9d5c2401e5fec1af31476da97708 [project @ 2005-11-05 01:44:21 by paulb] Updated the overview, adding a link to the XSLForms.Output module documentation. Corrected an example in the template attribute reference. Added descriptions of more attributes and controls in the template design document. diff -r cf1cf5e5bf6d -r e79dda7b3fcb docs/overview.html --- a/docs/overview.html Sat Nov 05 01:43:09 2005 +0000 +++ b/docs/overview.html Sat Nov 05 01:44:21 2005 +0000 @@ -20,5 +20,5 @@
  • Adding multivalued fields
  • Recommendations and advice
  • Adding in-page updates
    • -

    A topic-by-topic guide to XSLTools:

    Some other resources:

    +

    A topic-by-topic guide to XSLTools:

    Some other resources:

    \ No newline at end of file diff -r cf1cf5e5bf6d -r e79dda7b3fcb docs/reference.html --- a/docs/reference.html Sat Nov 05 01:43:09 2005 +0000 +++ b/docs/reference.html Sat Nov 05 01:44:21 2005 +0000 @@ -8,7 +8,7 @@ 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>

    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 diff -r cf1cf5e5bf6d -r e79dda7b3fcb docs/template-design.html --- a/docs/template-design.html Sat Nov 05 01:43:09 2005 +0000 +++ b/docs/template-design.html Sat Nov 05 01:44:21 2005 +0000 @@ -21,14 +21,14 @@ 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 -document structure which maintain some kind of organisation or grouping +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 are elements in the document structure which represent a +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 elements are treated as collection elements in the document @@ -45,14 +45,70 @@ document, 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.

    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"/>

    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 and the associated collection of elements used to insert new elements within the specified elements. 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"/>

    Again, such a selector could be obtained and its associated elements removed from the document.

    Simple Attribute Values

    A +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 and its associated elements 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 simple attribute value is defined to be a value, freely editable set in -an attribute on some element in a document. For example:

    <element attribute="value"/>

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

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

    Note that element is not declared in the above example, although we could also add such an annotation to the input element (as described 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>

    However, if such values are to be retained and submitted again by the user, we also need to include them as hidden elements:

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

    This +an attribute on some element in a document. For example, in an XML 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 +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 +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.

    \ No newline at end of file +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 +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. +For example:

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

    This would produce the following HTML form control:

    If +selected, the radio button when submitted would cause the attribute to +contain the stated value in the form data document, which would be some-choice +for the button in the above example. Should a different button +associated with the same attribute be pressed, the value stated in the +definition of that button would be stored in the attribute. Like the +checkbox, the selected radio button would remain selected when the form +data is presented to the user again.

    Attributes Set from Lists of Choices

    Certain +attributes may have a list of acceptable values associated with them, +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 +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 +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 +attribute defined to hold a single value. With each value-bearing +element 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 name="..." template:multiple-choice-list-field="-,element-enum,attribute" multiple="multiple">
      <option template:multiple-choice-list-value="element-enum,value,selected" value="..."></option>
    </select>

    This would produce the following HTML form control:

    Note that unlike the single selection menu example, an additional parameter is present in the template:multiple-choice-list-field annotation, but the first parameter is given as the placeholder value - (and is regarded as not having been stated). However, had the first parameter been stated (as opposed to being given as -) +the consequence would merely have been that upon submission of the +form, the elements in the collection would have been enclosed +within a single named element. In the above example, we assume that a +suitable element has already been defined in a template element and +that the above select element resides within that template element, thus providing the necessary enclosure (as recommended in the "Creating Applications: Recommendations and Advice" document).

    \ No newline at end of file