1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
-
- This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
- project.
-
- Copyright (C) 1998-2018 OpenLink Software
-
- This project is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; only version 2 of the License, dated June 1991.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-->
<refentry id="fn_xslt">
<refmeta>
<refentrytitle>xslt</refentrytitle>
<refmiscinfo>xml</refmiscinfo>
</refmeta>
<refnamediv>
<refname>xslt</refname>
<refpurpose>returns an XML document transformed by an XSLT stylesheet</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_xslt">
<funcprototype id="fproto_xslt">
<funcdef>xml_entity <function>xslt</function></funcdef>
<paramdef>in <parameter>sheet_uri</parameter> varchar</paramdef>
<paramdef>in <parameter>entity</parameter> any</paramdef>
<paramdef><optional>in <parameter>sheet_params</parameter> vector</optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_xslt"><title>Description</title>
<para>
This function takes the URI of a stylesheet and an XML entity and
produces an XML entity representing the transformation result of the
given entity with the given stylesheet. The result tree is separate
from the argument tree and the only reference to it is the returned
entity. Errors occurring in the transformation will be signalled as
SQL states, with XML or XSLT specific conditions beginning with XS or
XP.
</para>
<para>
The stylesheet can be passed parameters by specifying a third argument
to <function>xslt()</function>. This will be a vector of name/value
pairs. The values can be referenced from inside XPath expressions in
the stylesheet. You may use any Virtuoso data type. The names in the
parameter vector should appear without the '$' sign. If any of the
parameter values is NULL the parameter will be ignored because NULL
has no XPath counterpart.
If the same name appears more than once in the vector, the last name/value pair is
used and all preceding pairs with this name are silently ignored.
Obviously, names should be strings that are valid XPath variable names.
</para>
<para>
<function>xslt()</function> applies the transformation in the sheet to
the specified entity. The result is the root element of the result
tree, an XML entity. This entity can be used as input to another
transformation, can be serialized and sent to an HTTP client or stored,
etc.
</para>
<para>
The URI of the sheet is used to locate the stylesheet. The protocol
can be http, file or virt. Once the stylesheet has been retrieved it
is cached and not refetched until the cache is invalidated with
<function>xslt_stale()</function>. Included or imported style sheets
will be fetched automatically, using the initial URI as base for any
relative references. The <parameter>sheet_uri</parameter> is the URI
of a stylesheet. This should be an absolute URI resolvable with
<function>xml_uri_get()</function>. If the URI has previously been
used as a stylesheet and has not been marked stale with
<function>xslt_stale()</function>, Virtuoso will use the cached data
instead of fetching and parsing the stylesheet resource.
</para>
<para>
When a resource with a .xsl extension is stored into the WebDAV,
Virtuoso marks as stale any related cached resource. The URI for such
stylesheets will be
<programlisting>virt://WS.WS.SYS_DAV_RES.RES_FULL_PATH.RES_CONTENT:<path></programlisting>. See
the section about entity references in stored text for more on this
type of URI. If the URI uses the file protocol, Virtuoso will compare
the date of the file against the date of the cached stylesheet,
automatically reloading the sheet if the file changes. This protocol
is subject to the limitations on file system access imposed by the
host operating system and the virtuoso.ini file system access control
settings.
</para>
</refsect1>
<refsect1 id="params_xslt"><title>Parameters</title>
<refsect2><title>sheet_uri</title>
<para>URI pointing to the location of an XSL stylesheet.</para></refsect2>
<refsect2><title>entity</title>
<para>parsed XML entity such as that returned by the xtree_doc() function</para></refsect2>
<refsect2><title>sheet_params</title>
<para>A vector of keyword/value parameters to be passed to the
XSLT engine for use in the transformation.</para></refsect2>
</refsect1>
<refsect1 id="ret_xslt"><title>Return Types</title><para>An XML
entity resulting from transforming the given XML entity input with
the given style sheet.</para></refsect1>
<!--
<refsect1 id="errors_xslt"><title>Errors</title>
<table><title>Errors signalled by xslt()</title>
<tgroup cols="4">
<thead>
<row><entry>SQL State</entry><entry>Error Code</entry><entry>Error Text</entry><entry>Description</entry></row>
</thead>
<tbody>
<row>
<entry><errorcode></errorcode></entry>
<entry><errorcode></errorcode></entry>
<entry><errorname></errorname></entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
-->
<refsect1 id="examples_xslt"><title>Examples</title>
<example id="ex_xslt"><title>Basic Use</title>
<programlisting>
declare sheet, xml varchar;
declare xml_entity, myparams any;
sheet := 'virt://WS.WS.SYS_DAV_RES.RES_FULL_PATH.RES_CONTENT:/DAV/stylesheets/mysheet.xsl';
xml := 'virt://WS.WS.SYS_DAV_RES.RES_FULL_PATH.RES_CONTENT:/DAV/xmlsource/myxml.xml';
xml_entity := xtree_doc(xml);
myparams := vector('chapter', 'overview', 'imgroot', '/DAV/images/');
http_value(xslt(sheet, xml_entity, myparams));
</programlisting>
<para>This code will send the resultant transformation to the
http stream. Note that the <parameter>xml_entity</parameter> must be
a parsed XML entity such as that produced by
<parameter>xtree_doc</parameter>.</para>
<programlisting>
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/TR/WD-xsl">
<xsl:param name="chapter">default</xsl:param>
<xsl:param name="imgroot"></xsl:param>
<xsl:template match="/">
<xsl:text>Value of chapter: </xsl:text><xsl:value-of select="$chapter" />
<xsl:text>Value of imgroot: </xsl:text><xsl:value-of select="$imgroot" />
</xsl:template>
</xsl:stylesheet>
</programlisting>
<para>
This style sheet illustrates using parameters. Note how default
values can be provided in the style sheet when the parameters are
declared using the <parameter>xsl:param</parameter> tag.
</para>
</example>
</refsect1>
<refsect1 id="seealso_xslt"><title>See Also</title>
<para><link linkend="fn_xtree_doc"><function>xtree_doc()</function></link></para>
<para><link linkend="fn_xper_doc"><function>xper_doc()</function></link></para>
<para><link linkend="fn_xml_tree_doc"><function>xml_tree_doc()</function></link></para>
<para><link linkend="fn_xml_tree"><function>xml_tree()</function></link></para>
<para><link linkend="fn_xslt_stale"><function>xslt_stale()</function></link></para>
<para><link linkend="fn_XMLUpdate"><function>XMLUpdate()</function></link></para>
</refsect1>
</refentry>
|
