# HG changeset patch # User paulb # Date 1128719637 0 # Node ID dd56ae56091c1456088fc62d9d55730793c24f60 # Parent 51318c520887c95e39efbcac70bd4f33357410dc [project @ 2005-10-07 21:13:57 by paulb] Changed the reference to be a section-based guide to the different attributes. Added a link to the reference in the overview. diff -r 51318c520887 -r dd56ae56091c docs/overview.html --- a/docs/overview.html Wed Oct 05 23:24:40 2005 +0000 +++ b/docs/overview.html Fri Oct 07 21:13:57 2005 +0000 @@ -1,12 +1,10 @@ - - + - Creating Applications: An Overview - - - + + Creating Applications: An Overview + +

Creating Applications: An Overview

The following steps briefly describe how to make a new application:
@@ -23,6 +21,5 @@

  • Adding multivalued fields
  • Recommendations and advice
  • Adding in-page updates
    • - - - +

    Some other resources:

    + \ No newline at end of file diff -r 51318c520887 -r dd56ae56091c docs/reference.html --- a/docs/reference.html Wed Oct 05 23:24:40 2005 +0000 +++ b/docs/reference.html Fri Oct 07 21:13:57 2005 +0000 @@ -1,27 +1,74 @@ 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.

    AttributePurposeParameter -FormatsSuitable HTML ElementsRelated -AttributesImplementing Attributes
    template:elementMarks a section corresponding to an -element. Many element names can be given to provide a path into the -document.element-nameAlmost any
    element-name1,
    element-name2,
    ...
    template:attributeMarks a section -corresponding to an attribute.attribute-nameAlmost any
    template:attribute-fieldLets a template -element support the editing of an attribute by providing name and value -attributes on that template element.attribute-nameinput (with type -"text" or "hidden")
    		template:attribute
    template:attribute-areaLets a template element support the -editing of an attribute by providing a name attribute on that template -element, and by either inserting the value of the attribute inside the -template element, or by replacing the  template element with -the value.attribute-nametextareatemplate:attribute
    template:value
    template:effect
    attribute-name,
    -"insert" | "replace"
    template:attribute-buttonProvides support -for a template element to reflect the presence of an attribute on a -single element (having a particular value).attribute-name,
    attribute-value,
    template-attribute    		input (with type -"checkbox" or "radio")template:attribute
    template:expr
    template:expr-attr
    template:attribute-list-buttonProvides -support for a template element to reflect the presence of an attribute -value on one of a collection of elements.attribute-name,
    template-attribute    		input -(with type "checkbox" or "radio")template:multiple-choice-list-element
    		template:attribute
    template:expr
    template:expr-attr
    template:selector-fieldselector-nameinput (with type "submit", "checkbox" or "radio")template:element
    selector-name,
    affected-element-name
    template:multiple-choice-fieldelement-name | "-",
    attribute-name    		selecttemplate:multiple-choice-valuetemplate:element
    template:attribute
    element-name | "-",
    attribute-name,
    "new"
    template:multiple-choice-list-fieldelement-name | "-",
    list-element-name,
    list-attribute-name    		selecttemplate:multiple-choice-list-valuetemplate:element
    template:multiple-choice-list-elementelement-name | "-",
    list-element-name,
    list-attribute-name    		Almost anytemplate:attribute-list-buttontemplate:element
    template:multiple-choice-valueelement-name,
    attribute-name,
    template-attribute    		optiontemplate:multiple-choice-fieldtemplate:element
    template:expr
    template:expr-attr
    template:value
    template:multiple-choice-list-valueelement-name,
    attribute-name,
    template-attribute    		optiontemplate:multiple-choice-list-fieldtemplate:element
    template:expr
    template:expr-attr
    template:value
    +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>

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

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

    \ No newline at end of file