XSLTools

Annotated docs/advanced.html

687:ae7bdbf61e32
2009-06-22 Paul Boddie Added some error handling to the questionnaire application.
paulb@615 1
<?xml version="1.0" encoding="iso-8859-1"?>
paulb@397 2
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
paulb@397 3
<html xmlns="http://www.w3.org/1999/xhtml"><head>
paulb@397 4
  <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
paulb@615 5
  <title>Advanced Template Design</title>
paulb@397 6
  <link href="styles.css" rel="stylesheet" type="text/css" /></head>
paulb@397 7
<body>
paulb@397 8
<h1>Advanced Template Design</h1>
paulb@399 9
<p>In the <a href="template-design.html">"Template Design"</a> document, the special XSLForms annotations
paulb@397 10
were presented as a means to display the information contained in form
paulb@397 11
data documents (or just general XML documents with no special
paulb@397 12
connection to Web forms). However, since XSLForms templates build upon
paulb@397 13
XSL transformations, it is also possible to employ certain XSL
paulb@632 14
techniques to present the information in various different ways.</p>
paulb@632 15
paulb@632 16
<h2>Templates and Transformations</h2>
paulb@632 17
paulb@632 18
<p>When prepared, XSLForms templates are converted to XSL stylesheets, and
paulb@615 19
when form data is displayed, such XSL stylesheets are used to
paulb@397 20
transform the form data to a representation which looks like the
paulb@397 21
original template, but with different parts of the template populated
paulb@615 22
with the form data. The process can be illustrated as
paulb@615 23
follows:</p>
paulb@632 24
paulb@615 25
<table style="text-align: left; width: 80%;" align="center" border="0" cellpadding="5" cellspacing="5">
paulb@397 26
  <tbody>
paulb@397 27
    <tr>
paulb@397 28
      <th style="border: 1px solid rgb(0, 0, 0); background-color: rgb(193, 255, 102); text-align: center; vertical-align: top;">Template<br />
paulb@397 29
      <span class="method">A template presents the general form of the final output.</span></th>
paulb@397 30
      <th style="border-style: solid; border-width: 1px; text-align: center; vertical-align: top;">Stylesheet<br />
paulb@397 31
      <span class="method">Templates are converted to stylesheets, which are like programs specially designed to present XML information.</span></th>
paulb@397 32
      <th style="border: 1px solid rgb(0, 0, 0); background-color: rgb(255, 204, 255); text-align: center; vertical-align: top;">Output<br />
paulb@397 33
      <span class="method">The final output is produced when a stylesheet is combined with an XML document.</span></th>
paulb@397 34
    </tr>
paulb@397 35
  </tbody>
paulb@615 36
</table>
paulb@632 37
paulb@615 38
<p>Since the stylesheet is based on XSL, which is a rich
paulb@397 39
language in its own right, advanced template design techniques can
paulb@397 40
involve some of the features of XSL - at least those which do not
paulb@632 41
affect the simplicity or general structure of our templates.</p>
paulb@632 42
paulb@632 43
<h2>Template Extension Functions and Variables</h2>
paulb@632 44
paulb@632 45
<p>One
paulb@397 46
area where XSL features are already employed to affect the final output
paulb@615 47
in XSLForms is in the toolkit's use of template extension
paulb@397 48
functions and special variables - the latter being used in the output
paulb@397 49
production process. For example, we might decide to use the lower level
paulb@632 50
template functions to present the value of an attribute:</p>
paulb@632 51
paulb@632 52
<pre>&lt;span template:attribute="some-attribute" template:value="$this-value"&gt;xxx&lt;/span&gt;</pre>
paulb@632 53
paulb@632 54
<p>In the above example, we reference the special variable <code>$this-value</code> which refers to the value of <code>some-attribute</code>. An example of template functions in use looks like this:</p>
paulb@632 55
paulb@632 56
<pre>&lt;span id="{template:this-element()}"&gt;xxx&lt;/span&gt;</pre>
paulb@632 57
paulb@632 58
<p>In the above example, we invoke the template function <code>template:this-element</code>
paulb@397 59
in order to create a unique identifier in the final output. Since we
paulb@632 60
use the function inside an attribute which is not prefixed with <code>template</code>, we must enclose the expression between <code>{</code> and <code>}</code> characters.</p>
paulb@632 61
paulb@632 62
<h2>Beyond Template Extension Functions</h2>
paulb@632 63
paulb@632 64
<p>Since
paulb@397 65
the above template extension functions and variables are merely special in the
paulb@397 66
sense that XSLForms provides them to produce its output, and since they
paulb@397 67
are accessed in the stylesheet using normal XSL-based mechanisms, there
paulb@397 68
is no technical barrier to using other kinds of valid XSL (or more
paulb@397 69
precisely, XPath) expressions in cases such as those given above. The
paulb@632 70
rules for using such expressions in attributes are straightforward:</p>
paulb@632 71
paulb@632 72
<ul><li>Attributes prefixed with <code>template</code> can contain expressions as one would write them normally.</li><li>Other attributes must have their expressions enclosed between <code>{</code> and <code>}</code> characters so that the expression is evaluated and replaced with the result in the final output.</li></ul>
paulb@632 73
paulb@632 74
<p>Here is a trivial example of the usage of an XPath expression, based on one of the above examples:</p>
paulb@632 75
paulb@632 76
<pre>&lt;span template:attribute="some-attribute" template:value="string-length($this-value)"&gt;xxx&lt;/span&gt;</pre>
paulb@632 77
paulb@632 78
<p>In the above example, we invoke the standard XPath function <code>string-length</code> in order to produce within the <code>span</code> element the length of the value of <code>some-attribute</code> (instead of the actual value).</p>
paulb@632 79
paulb@632 80
<p>More
paulb@397 81
interesting applications of XPath expressions and non-XSLForms
paulb@397 82
functions arise when using more of the potential of XPath to select
paulb@397 83
arbitrary elements and attributes and to perform calculations on the
paulb@397 84
selected nodes. The following example originates from the Configurator
paulb@632 85
example application:</p>
paulb@632 86
paulb@632 87
<pre>&lt;span template:value="sum(/configuration//*[@value-is-set]/@price) + sum(/configuration//*[@value = ../@value]/@price)"&gt;&lt;/span&gt;</pre>
paulb@632 88
paulb@632 89
<p>This complicated expression, to be inserted within the <code>span</code> element, finds all elements in the system configuration having the <code>value-is-set</code>
paulb@397 90
attribute and adds their prices together; this total is combined with
paulb@397 91
the sum of the prices from all elements marked as selected in their
paulb@397 92
respective lists. In other words, it gets the total of all selected
paulb@632 93
components and inserts it into the final output.</p>
paulb@632 94
paulb@632 95
<h3>Using XSLT Extension Function Libraries</h3>
paulb@632 96
paulb@632 97
<p>Unlike the standard XPath functions, the XSLT extension functions supported
paulb@632 98
by libxslt must have their library namespace declared within the template. For
paulb@632 99
example:</p>
paulb@632 100
paulb@632 101
<pre>&lt;span xmlns:math="http://exslt.org/math" math:expr-prefix="math http://exslt.org/math"
paulb@632 102
  template:value="math:max(product/@price)"&gt;highest price&lt;/span&gt;</pre>
paulb@632 103
paulb@632 104
<p>Here, the <code>math</code> namespace is declared so that the
paulb@632 105
<code>math:max</code> function can be used. In addition, the
paulb@632 106
<code>math:expr-prefix</code> attribute ensures that such declarations are
paulb@632 107
preserved not only within the XSLForms framework and in the preparation of the
paulb@632 108
output stylesheet, but also as a measure to prevent potentially damaging edits
paulb@632 109
to the template. See the <a
paulb@632 110
href="reference.html#housekeeping-annotations">"Housekeeping Annotations"</a>
paulb@632 111
section of the attribute reference guide for details.</p>
paulb@632 112
paulb@632 113
</body></html>