# HG changeset patch # User Paul Boddie # Date 1227228210 -3600 # Node ID 992418d0335952e2e02bdd59ff48c032f31a55b7 # Parent ce20858ccd11ee1659aac7b009c9a3f58cfadcf6 Fix API documentation links. diff -r ce20858ccd11 -r 992418d03359 docs/JavaScript-reference.html --- a/docs/JavaScript-reference.html Fri Nov 21 01:43:03 2008 +0100 +++ b/docs/JavaScript-reference.html Fri Nov 21 01:43:30 2008 +0100 @@ -12,7 +12,7 @@

'platforms'

The above example causes an update to be sent to the location platforms relative to the current page.

sourceAreasStr

A comma-separated list of regions in the form data which affect the outcome of the update. For example:

'/package$1/platforms$1'

-Typically, one would use an template extension function to provide such information. For example:
+Typically, one would use an template extension function to provide such information. For example:

'{template:other-elements(..)}'

Selector fields may be specified in addition to regions:

'{template:selector-name('remove_platform', .)}'

@@ -20,6 +20,6 @@

requestUpdate

Parameters:

url

The URL (which may be relative to the current page or resource) to which the update shall be sent. See the description of the url parameter for the requestUpdateArea function for more details.

fieldNamesStr

A comma-separated list of fields in the form data which affect the outcome of the update. For example:

'/package$1/name'

-Typically, one would use an template extension function to provide such information. For example:
+Typically, one would use an template extension function to provide such information. For example:

'{template:other-attributes('name', .)}'

The above example causes the field associated with the name attribute on the current element to be included in the update.

targetName

The element identifier (specified by an HTML or XML id attribute) within which the outcome of the update shall appear.

targetFieldNamesStr

A comma-separated list of fields in the form data which are affected by the update. See the fieldNamesStr parameter for more details.

elementPath

A simple path into the form data, defining the scope of the update.

diff -r ce20858ccd11 -r 992418d03359 docs/XSLForms-resource.html --- a/docs/XSLForms-resource.html Fri Nov 21 01:43:03 2008 +0100 +++ b/docs/XSLForms-resource.html Fri Nov 21 01:43:30 2008 +0100 @@ -11,7 +11,7 @@ from this class, XSLFormsResource, you can derive your own application-specific resources and use the class's API to obtain, manipulate and present form data. Although the -supplied API documentation provides details of the class's API, specifically in the XSLForms.Resources.WebResources module, this document attempts to explain how the API is used in practice.

Resource Structure

The structure of a Web resource derived from XSLFormsResource should look like this:

class MyResource(XSLForms.Resources.WebResources.XSLFormsResource):

    [Resource definitions]

    def respond_to_form(self, trans, form):
        [Examine the form data, see if the user has added or removed anything.]
        [Perform additional processing and initialise the form data.]
        [Produce some kind of response to show the user the updated form data.]

Since XSLFormsResource builds on WebStack's resource mechanisms, we do have the transaction object, trans, available. However, most of the information we need to access and manipulate is generally available through the form object.

Defining Resources

Classes derived from XSLFormsResource +supplied API documentation provides details of the class's API, specifically in the XSLForms.Resources.WebResources module, this document attempts to explain how the API is used in practice.

Resource Structure

The structure of a Web resource derived from XSLFormsResource should look like this:

class MyResource(XSLForms.Resources.WebResources.XSLFormsResource):

    [Resource definitions]

    def respond_to_form(self, trans, form):
        [Examine the form data, see if the user has added or removed anything.]
        [Perform additional processing and initialise the form data.]
        [Produce some kind of response to show the user the updated form data.]

Defining Resources

Classes derived from XSLFormsResource support the concept of resources which are used to produce output, support processing and to provide access to useful information. At the class level it is essential to define at least some of these resources @@ -109,7 +109,7 @@ use the identifier in the above example together with config_template.xhtml, we would have to ensure that the identifier appeared as a value of an id node in that template document. Note that the choice of template document is not defined here, but is instead made when handling an -in-page update request.

Examining the Form Data

The form data is available through the form object which exposes the XSLForms.Fields.Form API. The most interesting operations are as follows:

Obtain the Form Data Documents

Since +in-page update request.

Examining the Form Data

The form data is available through the form object which exposes the XSLForms.Fields.Form API. The most interesting operations are as follows:

Obtain the Form Data Documents

Since XSLForms is an XML-based toolkit, the form data is available as XML documents which can be accessed and manipulated using a DOM-style API. Upon receiving submitted form data, XSLForms converts the data to such @@ -155,7 +155,7 @@ operation, we could use the DOM-style API exposed by the contents of the selectors to perform such an operation in the resource using our own code. However, the XSLForms toolkit provides some useful -convenience functions to assist in the removal or addition of elements:

# After doing this:
# import XSLForms.Utils

# Removing elements...

removed_elements = selectors.get("remove")       # this may return None
XSLForms.Utils.remove_elements(removed_elements) # this can handle None, realising that no elements are to be removed

# Adding elements...

places_to_add_elements = selectors.get("add")
XSLForms.Utils.add_elements(places_to_add_elements, "element")

See the XSLForms.Utils documentation for more information on these functions.

Document Initialisation

The initialisation of a document, using information defined in the init_resources +convenience functions to assist in the removal or addition of elements:

# After doing this:
# import XSLForms.Utils

# Removing elements...

removed_elements = selectors.get("remove")       # this may return None
XSLForms.Utils.remove_elements(removed_elements) # this can handle None, realising that no elements are to be removed

# Adding elements...

places_to_add_elements = selectors.get("add")
XSLForms.Utils.add_elements(places_to_add_elements, "element")

See the XSLForms.Utils documentation for more information on these functions.

Document Initialisation

The initialisation of a document, using information defined in the init_resources attribute, is similar to the transformation of a document as described above. First, we obtain a reference to an initialisation stylesheet:

init_stylesheet = self.prepare_initialiser("configuration")

Note that only a single stylesheet is returned. With the result of the call, diff -r ce20858ccd11 -r 992418d03359 docs/index.html --- a/docs/index.html Fri Nov 21 01:43:03 2008 +0100 +++ b/docs/index.html Fri Nov 21 01:43:30 2008 +0100 @@ -29,7 +29,7 @@ guide can be found inside the apidocs directory within the XSLTools-0.6 directory. Of course, it is always possible to view the API documentation -within Python by importing modules (such as XSLTools.XSLOutput) +within Python by importing modules (such as XSLTools.XSLOutput) and using Python's built-in help function.

About XSLForms Applications

The template:i18n attribute, as described in the "Template Attribute Reference" document.
The template:i18n extension function, as described in the extension function API documentation.

Each +and translated phrases:

The template:i18n attribute, as described in the "Template Attribute Reference" document.
The template:i18n extension function, as described in the extension function API documentation.

Each of the above mechanisms has its own specific purpose in template documents, and these purposes are described below, along with the necessary procedures for initialising and invoking the translation @@ -34,7 +34,7 @@ attributes, the expression must reside between { and } characters for the evaluation to take place. The anticipated result might resemble something like the following:

<input type="submit" name="update" value="Oppdatér"/>

Where no suitable translation can be found for the text passed to the function, the submitted text is returned as a result, producing -something resembling the original, non-translated document fragment.

See the template:i18n extension function description in the extension function API documentation for more details.

Initialising and Invoking Translations

To +something resembling the original, non-translated document fragment.

See the template:i18n extension function description in the extension function API documentation for more details.

Initialising and Invoking Translations

To permit the translation of text to occur, we must first prepare the translations themselves; then, we must change our application to make use of the translations.

Preparing the Translations

Translations diff -r ce20858ccd11 -r 992418d03359 docs/labels.html --- a/docs/labels.html Fri Nov 21 01:43:03 2008 +0100 +++ b/docs/labels.html Fri Nov 21 01:43:30 2008 +0100 @@ -42,7 +42,7 @@ to produce translated labels, we must first define a translations file as described in the "Internationalisation" document; this file can be saved alongside our other resources with the name translations.xml, and its contents can be defined as follows:

<?xml version="1.0" encoding="iso-8859-1"?>
<translations>
  <locale>
    <code value="nb"/>
    <code value="nb_NO"/>
    <translation value="(Not selected)">(Ikke valgt)</translation>
    <translation value="Important">Viktig</translation>
    <translation value="Not important">Ikke viktig</translation>
    <translation value="Personal">Personlig</translation>
  </locale>
</translations>

To make use of this file, we must add additional references in the Web resource's attributes:

    document_resources = {
        "types" : "structure_types_label.xml",
        "translations" : "translations.xml"
        }

And to introduce the translation mechanisms into the output production, we must modify the resource further:

        # Complete the response.

        stylesheet_parameters["locale"] = trans.get_content_languages()[0]
        self.send_output(trans, [trans_xsl], structure, stylesheet_parameters,
            references={"translations" : self.prepare_document("translations")})

Here, we define a locale parameter for the output stylesheet using the first language specified in each user's browser's language preferences. Then, we add a reference -to the translations document specified above.

Finally, we have to change the template to make use of the translations:

  <p>
    Item type:
    <select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple">
      <option template:multiple-choice-list-value="type-enum,value,selected,template:i18n(text())" value="..." />
    </select>
  </p>

Note that we use the template:i18n extension function to modify the text found in each type-enum element in the types document. The usage of this function is described in the extension function API documentation.

Now, upon adding items in the application, if the browser is set up appropriately - in this case using Norwegian Bokmål [nb] as the first choice of language - the item types will appear translated in the final output.

Finally, we have to change the template to make use of the translations:

  <p>
    Item type:
    <select name="..." template:multiple-choice-list-field="type,type-enum,value" multiple="multiple">
      <option template:multiple-choice-list-value="type-enum,value,selected,template:i18n(text())" value="..." />
    </select>
  </p>

requestUpdate

Resource Structure

Defining Resources

Resource Structure

Defining Resources

Examining the Form Data

Obtain the Form Data Documents

Examining the Form Data

Obtain the Form Data Documents

Document Initialisation

Document Initialisation

About XSLForms Applications

Initialising and Invoking Translations

Initialising and Invoking Translations

Preparing the Translations

Further Reading