# HG changeset patch # User paulb # Date 1169245371 0 # Node ID 60371d21572e5a1a6bbc715e91230055cdd6a299 # Parent 2a8d1311249803f89b95bd9d824835bc01085182 [project @ 2007-01-19 22:22:51 by paulb] Documented expr-prefix and the xslform_fix.py script. Updated release information. diff -r 2a8d13112498 -r 60371d21572e docs/index.html --- a/docs/index.html Fri Jan 19 22:22:33 2007 +0000 +++ b/docs/index.html Fri Jan 19 22:22:51 2007 +0000 @@ -10,23 +10,23 @@ libxml2, libxslt and (optionally) WebStack.

Setting Up

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

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

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

cd XSLTools-0.4.3
python setup.py install

cd XSLTools-0.4.4
python setup.py install

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

Viewing the API Documentation

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

diff -r 2a8d13112498 -r 60371d21572e docs/reference.html --- a/docs/reference.html Fri Jan 19 22:22:33 2007 +0000 +++ b/docs/reference.html Fri Jan 19 22:22:51 2007 +0000 @@ -80,4 +80,23 @@ 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:

template:multiple-choice-list-element
template:attribute-button

Implementing attributes:

template:attribute
template:expr
template:expr-attr

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 +in the final output, should the expression evaluate to a true value.

Housekeeping Annotations

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

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

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

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

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

Fixing Annotations

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

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

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

xslform_fix.py template.xhtml template_fixed.xhtml

Since +namespace declarations may be moved to the root element of the new +template document, it is possible that some problems may result +with documents using namespaces in advanced ways, but the tool +should provide a reasonable solution for most documents.

\ No newline at end of file