1<!DOCTYPE refentry SYSTEM "tcldoc-1.0.dtd">
2
3<refentry xmlns:xlink='http://www.w3.org/XLink'>
4
5  <docinfo>
6    <author xlink:href='http://www.zveno.com/staff/Steve.Ball/'>
7      <firstname>Steve</firstname>
8      <surname>Ball</surname>
9    </author>
10    <copyright>
11      <year>2002</year>
12      <holder xlink:href='http://www.zveno.com/'>Zveno Pty Ltd</holder>
13      <legalnotice>
14        <para><!-- insert std Zveno legal notice --></para>
15      </legalnotice>
16    </copyright>
17  </docinfo>
18
19  <refmeta>
20    <refentrytitle>TclXSLT</refentrytitle>
21    <manvolnum>n</manvolnum>
22  </refmeta>
23
24  <refnamediv>
25    <refname>::xslt::compile</refname>
26    <refname>::xslt::extension</refname>
27  </refnamediv>
28
29  <refsynopsisdiv>
30    <tclcmdsynopsis>
31      <command>package require xslt</command>
32    </tclcmdsynopsis>
33
34    <tclpkgsynopsis>
35      <package>xslt</package>
36      <version>2.5</version>
37    </tclpkgsynopsis>
38
39    <tclnamespacesynopsis>
40      <tclnamespace>::xslt</tclnamespace>
41    </tclnamespacesynopsis>
42
43    <tclcmdsynopsis>
44      <command>::xslt::compile</command>
45      <arg><replaceable>doc</replaceable></arg>
46    </tclcmdsynopsis>
47
48    <tclcmdsynopsis>
49      <command><replaceable>ssheet</replaceable></command>
50      <arg><replaceable>method</replaceable></arg>
51      <group choice='opt' rep='repeat'><arg>option</arg><arg>value</arg></group>
52      <group choice='opt' rep='repeat'><arg>args</arg></group>
53    </tclcmdsynopsis>
54
55    <tclcmdsynopsis>
56      <command>::xslt::extension</command>
57      <methodname>add</methodname>
58      <arg><replaceable>nsuri</replaceable></arg>
59      <arg><replaceable>tcl-namespace</replaceable></arg>
60    </tclcmdsynopsis>
61  </refsynopsisdiv>
62
63  <refsect1>
64    <title>Description</title>
65
66    <para>TclXSLT is a wrapper for the <ulink url='http://xmlsoft.org/'>Gnome libxslt library</ulink> that allows an application to perform XSL transformations (XSLT).  The package also provides a binding to the XSLT extension mechanism so that XSLT extension may be implemented using Tcl scripts.</para>
67
68    <para>Transformation only works with documents created by TclDOM/libxml2.</para>
69
70    <para>The TclXSLT package makes extensive use of Tcl objects.  Compiled XSL stylesheets are stored as the internal representation of a Tcl object.  Source and result documents are accessed via TclDOM's C interface as Tcl objects.  This allows the application to cache parsed XML documents and compiled XSL stylesheets for better runtime performance.</para>
71  </refsect1>
72
73  <refsect1>
74    <title>Packages and Namespaces</title>
75
76    <para>The TclXSLT package defines the <tclpackage>xslt</tclpackage> package and also a Tcl namespace using that name.</para>
77  </refsect1>
78
79  <refsect1>
80    <title>Commands</title>
81
82    <refsect2>
83      <title><tclcommand>::xslt::compile</tclcommand></title>
84
85      <para>The <tclcommand>::xslt::compile</tclcommand> command pre-compiles a stylesheet document.  It returns a compiled stylesheet object and also defines a Tcl command to access the stylesheet.  This Tcl command may be used to transform XML documents.</para>
86
87      <example>
88        <title>Example</title>
89	<programlisting>
90set source_doc [::dom::libxml2::parse $XML]
91set ssheet_doc [::dom::libxml2::parse $XSLstylesheet]
92set ssheet [::xslt::compile $ssheet_doc]
93set result [$ssheet transform $source_doc]
94</programlisting>
95      </example>
96
97      <para>NB.  It is advisable to use the <option>-baseuri</option> option when parsing the source and stylesheet documents to allow external resources to be resolved.</para>
98    </refsect2>
99
100    <refsect2>
101      <title>Stylesheet Command</title>
102
103      <para>The stylesheet command created by <tclcommand>::xslt::compile</tclcommand> command accesses a compiled stylesheet.</para>
104
105      <refsect3>
106        <title>Command Methods</title>
107
108	<para>The following command methods may be used:</para>
109
110	<variablelist>
111	  <varlistentry>
112	    <term><arg>cget</arg> <arg><replaceable>option</replaceable></arg></term>
113	    <listitem>
114	      <para>Returns the value of an option.  See below for the list of valid options.</para>
115	    </listitem>
116	  </varlistentry>
117	  <varlistentry>
118	    <term><arg>configure</arg> <arg><replaceable>option</replaceable> <replaceable>value</replaceable></arg></term>
119	    <listitem>
120	      <para>Sets the value of an option.  Available options are as follows:</para>
121	      <varlistentry>
122	        <varlistentry>
123		  <term><option>-messagecommand</option> <arg><replaceable>script</replaceable></arg></term>
124		  <para>This option specifies a Tcl command to be evaluated when a message is produced by the stylesheet.  Messages may be produced when the stylesheet detects an error during processing, or when the stylesheet uses the <sgmltag>xsl:message</sgmltag> element.</para>
125
126		  <para>It is currently not possible to distinguish between an error message and a message produced using <sgmltag>xsl:message</sgmltag>.</para>
127		</varlistentry>
128	        <varlistentry>
129		  <term><option>-method</option></term>
130		  <para>Specifies the output being produced by the stylesheet.  This is usually set by the styesheet's <sgmltag>xsl:output</sgmltag> element.  May have the value <literal>xml</literal>, <literal>html</literal>, <literal>xhtml</literal> or <literal>text</literal>.</para>
131		  <para>This is a read-only option.</para>
132		</varlistentry>
133	      </varlistentry>
134	    </listitem>
135	  </varlistentry>
136	  <varlistentry>
137	    <term><arg>transform</arg> <arg><replaceable>source</replaceable></arg> <group opt='repeat'><arg><replaceable>name</replaceable></arg> <arg><replaceable>value</replaceable></arg></group></term>
138	    <listitem>
139	      <para>Performs an XSL transformation on the given source document.  Stylesheet parameters may be specified as name-value pairs.  The return result is the DOM token for the result document.</para>
140	    </listitem>
141	  </varlistentry>
142	</variablelist>
143      </refsect3>
144
145      <refsect3>
146        <title>Stylesheet Parameters</title>
147
148	<para>Any number of name-value pairs may be specified as arguments to the <tclcommand><replaceable>stylesheet</replaceable> transform</tclcommand> method.  These are passed as values for parameters in the stylesheet.  <application>libxslt</application> interprets the values as XPath expressions, where the context node is the root node for the source document.  To pass a value as a string it must be XPath-quoted, for example</para>
149
150	<informalexample>
151	  <programlisting>
152set library "Gnome libxslt"
153$ssheet transform $source_doc \
154	library '$library' \
155	author "'Daniel Veillard'" \
156	node {/*/Element[3]}
157</programlisting>
158	</informalexample>
159      </refsect3>
160
161      <para>Following is an example of how to use the <tclcommand><replaceable>stylesheet</replaceable> transform</tclcommand> method.</para>
162
163      <example>
164        <title>Example</title>
165	<programlisting>
166set source_doc [::dom::libxml2::parse $XML]
167set ssheet_doc [::dom::libxml2::parse $XSLstylesheet]
168set ssheet [::xslt::compile $ssheet_doc]
169set result_doc [$ssheet transform $source_doc]
170set result_xml [::dom::libxml2::serialize $result_doc \
171    -method [$ssheet cget -method]]
172</programlisting>
173      </example>
174    </refsect2>
175
176    <refsect2>
177      <title><tclcommand>::xslt::extension</tclcommand></title>
178
179      <para>The <tclcommand>::xslt::extension</tclcommand> command is used to manage extensions of the <application>libxslt</application> library.  The <methodname>add</methodname> is used to register an extension.  The <methodname>remove</methodname> is used to unregister an extension.  See <link>EXTENSIONS</link> for more detail.</para>
180    </refsect2>
181  </refsect1>
182
183  <refsect1>
184    <title>Extensions</title>
185
186    <para>The TclXSLT package allows an application to bind Tcl scripts to the extension mechanism of <application>libxslt</application>.  This means that Tcl scripts may provide the implementation of an XSLT extension element or function.  The binding is achieved to associating a Tcl namespace with an XML namespace.</para>
187
188    <refsect2>
189      <title>Implementing An Extension</title>
190
191      <para>The Tcl application uses the <tclcommand>::xslt::extension add</tclcommand> command to register an extension.  An XML Namespace for the extension is specified as an argument, along with a Tcl namespace that will provide implementations of extension elements and functions.  For example,</para>
192
193      <informalexample>
194        <programlisting>
195::xslt::extension add http://www.zveno.com/Example ::example
196</programlisting>
197      </informalexample>
198
199      <para>Everytime the <tclcommand>::xslt::transform</tclcommand> command is executed, a newly-created XSLT engine is initialized.  For each registered extension, every procedure in the associated Tcl namespace is defined in the XSLT engine as either an extension element or an extension function.  The procedure is defined as an extension function if it has a variable argument list, otherwise it is defined as an extension element.  The procedure name is used as the local part of the extension name.  For example,</para>
200
201      <informalexample>
202        <programlisting>
203namespace eval example {
204    namespace export myfunc myelement
205}
206
207proc example::myfunc {name args} {
208    global app
209    return $app($name)
210}
211proc example::myelement {node} {
212    global app
213    return $app([dom::libxml2::node cget $node -nodeName])
214}
215</programlisting>
216      </informalexample>
217
218      <para>"myfunc" is defined as an extension function and "myelement" is defined as an extension element.</para>
219
220      <refsect3>
221        <title>Extension Functions</title>
222
223	<para>The arguments to an extension function are converted to a string value and then passed as parameters to the Tcl procedure.</para>
224
225	<para>The return result of the Tcl procedure becomes the return value of the extension function.  The type of the result is preserved where possible, otherwise it is converted to a string value.</para>
226      </refsect3>
227
228      <refsect3>
229        <title>Extension Elements</title>
230
231	<para>Extension elements have not been implemented in TclXSLT v1.1.</para>
232      </refsect3>
233    </refsect2>
234
235    <refsect2>
236      <title>Using An Extension</title>
237
238      <para>To invoke an extension in an XSL stylesheet, use the normal XSLT extension mechanism.  The XML Namespace matches the extension to the registered Tcl namespace (NB. the stylesheet author is free to choose any prefix for the extension namespace).  For example,</para>
239
240      <informalexample>
241        <programlisting><![CDATA[
242<xsl:stylesheet version='1.0'
243	xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
244	xmlns:eg='http://www.zveno.com/Example'>
245
246  <xsl:template match='/'>
247    <xsl:text>Result of calling extension is "</xsl:text>
248    <xsl:value-of select='eg:myfunc("foo")'/>
249    <xsl:text>".
250</xsl:text>
251  </xsl:template>
252
253</xsl:stylesheet>
254]]></programlisting>
255      </informalexample>
256
257      <para>This stylesheet would result in the following Tcl script being evaluated:</para>
258
259      <informalexample>
260        <programlisting>
261::example::myfunc foo
262</programlisting>
263      </informalexample>
264    </refsect2>
265  </refsect1>
266</refentry>
267