Skip to content

Commit 7db2b52

Browse files
duncdrumduncdrum
committed
fix(xsl-transform): add -it and catalog info
close #234
1 parent bd8539e commit 7db2b52

File tree

6 files changed

+169
-142
lines changed

6 files changed

+169
-142
lines changed

‎src/main/xar-resources/data/xsl-transform/listings/listing-1.txt‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1 @@
1-
transform:transform($input as node()?, $stylesheet as item(),
2-
$parameters as node()?) as node()?
1+
transform:transform($input as node()?, $stylesheet as item(), $parameters as node()?) as node()?

‎src/main/xar-resources/data/xsl-transform/listings/listing-2.txt‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1 @@
1-
transform:transform($node-tree as node()*, $stylesheet as item(),
2-
$parameters as node()?, $attributes as node()?,
3-
$serialization-options as xs:string?) as node()?
1+
transform:transform($node-tree as node()*, $stylesheet as item(), $parameters as node()?, $attributes as node()?, $serialization-options as xs:string?) as node()?

‎src/main/xar-resources/data/xsl-transform/listings/listing-3.txt‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
declare function obe:make-catalog($col as item()*, $docs as xs:string*) as item() {
2+
<collection stable="true" xml:base="xmldb:exist://">
3+
{
4+
if (exists($docs)) then
5+
for $doc in $docs
6+
return
7+
<doc href="{$config:data-root || "/" || $doc}"/>
8+
else
9+
for $doc in collection($col)//tei:TEI
10+
return
11+
<doc href="{document-uri(root($doc))}"/>
12+
}
13+
</collection>
14+
};

‎src/main/xar-resources/data/xsl-transform/listings/listing-7.xml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
<parameters>
2-
<param name="param1" value="value1"/>
3-
<param name="param2" value="value2"/>
4-
</parameters>
2+
<param name="param1" value="value1"/>
3+
<param name="param2" value="value2"/>
4+
</parameters>

‎src/main/xar-resources/data/xsl-transform/listings/listing-9.xml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
<attributes>
2-
<attr name="param1" value="value1"/>
3-
<attr name="param2" value="value2"/>
4-
</attributes>
2+
<attr name="param1" value="value1"/>
3+
<attr name="param2" value="value2"/>
4+
<attr name="http://saxon.sf.net/feature/initialTemplate" value="main"/>
5+
</attributes>

‎src/main/xar-resources/data/xsl-transform/xsl-transform.xml‎

Lines changed: 146 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,148 @@
1-
<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng"
2-
schematypens="http://relaxng.org/ns/structure/1.0"?><?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml"
3-
schematypens="http://purl.oclc.org/dsdl/schematron"?>
4-
<article version="5.0" xmlns="http://docbook.org/ns/docbook"
5-
xmlns:xlink="http://www.w3.org/1999/xlink">
6-
<info>
7-
<title>XSL transformations</title>
8-
<date>2Q19</date>
9-
<keywordset>
10-
<keyword>application-development</keyword>
11-
</keywordset>
12-
</info>
13-
14-
<!-- ================================================================== -->
15-
16-
<para>eXist-db can perform XSLT transformations inside XQuery code. For this you need to use the
17-
<code>transform</code> module.</para>
18-
19-
<!-- ================================================================== -->
20-
21-
<sect1 xml:id="transform-module">
22-
<title>The <code>transform</code> module</title>
23-
24-
<para>eXist-db transform module allows you to do XSLT transformations from XQuery
25-
code.</para>
26-
<para>Its function namespace is
27-
<literal>http://exist-db.org/xquery/transform</literal>.</para>
28-
29-
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
30-
31-
<sect2 xml:id="transform">
32-
<title><code>transform:transform()</code></title>
33-
34-
<para>The transform:transform function performs an XSLT transformation and returns you
35-
the result:. It has two signatures:</para>
36-
<programlisting language="xquery" xlink:href="listings/listing-1.txt"/>
37-
<programlisting language="xquery" xlink:href="listings/listing-2.txt"/>
38-
39-
<variablelist>
40-
<varlistentry>
41-
<term><code>$input</code></term>
42-
<listitem>
43-
<para>The node to be transformed. If <literal>$input</literal> is an empty
44-
sequence, the function returns immediately.</para>
45-
</listitem>
46-
</varlistentry>
47-
<varlistentry>
48-
<term><code>$stylesheet</code></term>
49-
<listitem>
50-
<para>The stylesheet to use. This must either be a URI or a node.</para>
51-
<para> If <code>$stylesheet</code> is a URI, the stylesheet is loaded from
52-
the specified location. Watch out: A relative URI is interpreted as a
53-
file path!</para>
54-
<para>Loading a stylesheet from the database is done best by creating a full
55-
absolute path, including an <code>xmldb:exist://</code> prefix.</para>
56-
<para>The stylesheet is compiled into a template (using the standard Java
57-
APIs <literal>javax.xml.transform</literal>). The result is shared
58-
between all instances of the function and will only reload if modified
59-
since last invocation.</para>
60-
<para>Some examples for referencing the stylesheet:</para>
61-
<itemizedlist>
62-
<listitem>
63-
<programlisting>transform:transform($root, doc("/db/styles/style.xsl"), ())</programlisting>
64-
<para>Create the stylesheet from a document node.</para>
65-
</listitem>
66-
<listitem>
67-
<programlisting>transform:transform($root, xs:anyURI("http:exist-db.org/style.xsl"), ())</programlisting>
68-
<programlisting>transform:transform($root, xs:anyURI("xmldb:exist:///db/styles/style.xsl"), ())</programlisting>
69-
<para>Load the stylesheet from the specified URI. </para>
70-
</listitem>
71-
</itemizedlist>
72-
73-
</listitem>
74-
</varlistentry>
75-
<varlistentry>
76-
<term><code>$parameters</code></term>
77-
<listitem>
78-
<para>Specify any stylesheet parameters. This must be an XML fragment like
79-
the following example:</para>
80-
<programlisting language="xml" xlink:href="listings/listing-7.xml"/>
81-
<para>The stylesheet can now reference parameter <code>param1</code> as
82-
follows:</para>
83-
<programlisting>&lt;xsl:param name="param1"/&gt;</programlisting>
84-
<para> There are two special parameters named
85-
<code>exist:stop-on-warn</code> and <code>exist:stop-on-error</code>. If
86-
set to <code>yes</code>, eXist will generate an XQuery error if the XSL
87-
processor reports a warning or error. </para>
88-
</listitem>
89-
</varlistentry>
90-
<varlistentry>
91-
<term>$attributes</term>
92-
<listitem>
93-
<para>Pass attributes to the transformation factory. Verify the <link
94-
xlink:href="https://docs.oracle.com/javase/8/docs/api/javax/xml/transform/TransformerFactory.html#setAttribute-java.lang.String-java.lang.Object-"
95-
>Java</link> or <link
96-
xlink:href="https://www.saxonica.com/html/documentation/javadoc/net/sf/saxon/lib/FeatureKeys.html"
97-
>Saxon</link> documentation for more details.</para>
98-
<para>Its contents must be an XML fragment, like this:</para>
99-
<programlisting language="xml" xlink:href="listings/listing-9.xml"/>
100-
</listitem>
101-
</varlistentry>
102-
<varlistentry>
103-
<term><code>$serialization</code></term>
104-
<listitem>
105-
<para>Specifies serialization options in the same way as passed to the
106-
<code>declare option exist:serialize</code> expression. </para>
107-
<para>An additional serialization option, <code>xinclude-path</code>, is
108-
supported. This specifies the base path against which XInclude-s will be
109-
expanded. A relative path is relative to the current module load
110-
path.</para>
111-
</listitem>
112-
</varlistentry>
113-
</variablelist>
114-
115-
</sect2>
116-
117-
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
118-
119-
<sect2 xml:id="stream-transform">
120-
<title><code>transform:stream-transform()</code></title>
121-
122-
<para>Performs an XSLT transformation like the <literal>transform:transform</literal>
123-
function, but directly streams the transformation result to the HTTP request output
124-
stream. It doesn't return anything. The function is therefore only usable in a web
125-
context. </para>
126-
<para>The servlet output stream will be closed afterwards.</para>
127-
</sect2>
128-
</sect1>
129-
130-
<!-- ================================================================== -->
131-
1+
<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
2+
<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
3+
<article version="5.0" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4+
<info>
5+
<title>XSL transformations</title>
6+
<date>1Q20</date>
7+
<keywordset>
8+
<keyword>application-development</keyword>
9+
</keywordset>
10+
</info>
11+
12+
<!-- ================================================================== -->
13+
14+
<para>eXist-db can perform XSLT transformations inside XQuery code. For this you need to use the
15+
<code>transform</code>
16+
module.</para>
17+
18+
<!-- ================================================================== -->
19+
20+
<sect1 xml:id="transform-module">
21+
<title>The
22+
<code>transform</code>
23+
module</title>
24+
25+
<para>eXist-db transform module allows you to do XSLT transformations from XQuery code using Saxon.</para>
26+
<para>Its function namespace is
27+
<literal>http://exist-db.org/xquery/transform</literal>.</para>
28+
29+
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
30+
31+
<sect2 xml:id="transform">
32+
<title>
33+
<code>transform:transform()</code>
34+
</title>
35+
36+
<para>The <code>transform:transform</code> function performs an XSLT transformation and returns you the result:. It has two signatures:</para>
37+
<programlisting language="xquery" xlink:href="listings/listing-1.txt"/>
38+
<programlisting language="xquery" xlink:href="listings/listing-2.txt"/>
39+
40+
<variablelist>
41+
<varlistentry>
42+
<term>
43+
<code>$input</code>
44+
</term>
45+
<listitem>
46+
<para>The node to be transformed. If
47+
<literal>$input</literal>
48+
is an empty sequence, the function returns immediately.</para>
49+
</listitem>
50+
</varlistentry>
51+
<varlistentry>
52+
<term>
53+
<code>$stylesheet</code>
54+
</term>
55+
<listitem>
56+
<para>The stylesheet to use. This must either be a URI or a node.</para>
57+
<para>
58+
If
59+
<code>$stylesheet</code>
60+
is a URI, the stylesheet is loaded from the specified location. Watch out: A relative URI is interpreted as a file path!</para>
61+
<para>Loading a stylesheet from the database is done best by creating a full absolute path, including an
62+
<code>xmldb:exist://</code>
63+
prefix.</para>
64+
<para>The stylesheet is compiled into a template (using the standard Java APIs
65+
<literal>javax.xml.transform</literal>). The result is shared between all instances of the function and will only reload if modified since last invocation.</para>
66+
<para>Some examples for referencing the stylesheet:</para>
67+
<itemizedlist>
68+
<listitem>
69+
<programlisting language="xquery">transform:transform($root, doc("/db/styles/style.xsl"), ())</programlisting>
70+
<para>Create the stylesheet from a document node.</para>
71+
</listitem>
72+
<listitem>
73+
<programlisting language="xquery">transform:transform($root, xs:anyURI("http:exist-db.org/style.xsl"), ())</programlisting>
74+
<programlisting language="xquery">transform:transform($root, xs:anyURI("xmldb:exist:///db/styles/style.xsl"), ())</programlisting>
75+
<para>Load the stylesheet from the specified URI.
76+
</para>
77+
</listitem>
78+
</itemizedlist>
79+
80+
</listitem>
81+
</varlistentry>
82+
<varlistentry>
83+
<term>
84+
<code>$parameters</code>
85+
</term>
86+
<listitem>
87+
<para>Specify any stylesheet parameters. This must be an XML fragment like the following example:</para>
88+
<programlisting language="xml" xlink:href="listings/listing-7.xml"/>
89+
<para>The stylesheet can now reference parameter
90+
<code>param1</code>
91+
as follows:</para>
92+
<programlisting>&lt;xsl:param name="param1"/&gt;</programlisting>
93+
<para>
94+
There are two special parameters named
95+
<code>exist:stop-on-warn</code>
96+
and
97+
<code>exist:stop-on-error</code>. If set to
98+
<code>yes</code>, eXist will generate an XQuery error if the XSL processor reports a warning or error.
99+
</para>
100+
</listitem>
101+
</varlistentry>
102+
<varlistentry>
103+
<term>$attributes</term>
104+
<listitem>
105+
<para>Pass attributes to the transformation factory. Verify the
106+
<link xlink:href="https://docs.oracle.com/javase/8/docs/api/javax/xml/transform/TransformerFactory.html#setAttribute-java.lang.String-java.lang.Object-">Java</link>
107+
or
108+
<link xlink:href="https://www.saxonica.com/html/documentation/javadoc/net/sf/saxon/lib/FeatureKeys.html">Saxon</link>
109+
documentation for more details. Its contents must be an XML fragment, below you see how <code>-it:main</code> type transformations are handled:</para>
110+
<programlisting language="xml" xlink:href="listings/listing-9.xml"/>
111+
</listitem>
112+
</varlistentry>
113+
<varlistentry>
114+
<term>
115+
<code>$serialization</code>
116+
</term>
117+
<listitem>
118+
<para>Specifies serialization options in the same way as passed to the
119+
<code>declare option exist:serialize</code>
120+
expression.
121+
</para>
122+
<para>An additional serialization option,
123+
<code>xinclude-path</code>, is supported. This specifies the base path against which XInclude-s will be expanded. A relative path is relative to the current module load path.</para>
124+
</listitem>
125+
</varlistentry>
126+
</variablelist>
127+
<para>A common trap is the use of <code>fn:doc()</code> these are not identical inside eXist-db's xquery processing and Saxon's XSL handling. Therefore, for transformation of mutiple XML files stored inside the dababase, you might wish to construct a temporary catalog file for use by the transformation and immediate removal, like this:</para>
128+
<programlisting language="xquery" xlink:href="listings/listing-3.txt"/>
129+
</sect2>
130+
131+
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
132+
133+
<sect2 xml:id="stream-transform">
134+
<title>
135+
<code>transform:stream-transform()</code>
136+
</title>
137+
138+
<para>Performs an XSLT transformation like the
139+
<literal>transform:transform</literal>
140+
function, but directly streams the transformation result to the HTTP request output stream. It doesn't return anything. The function is therefore only usable in a web context.
141+
</para>
142+
<para>The servlet output stream will be closed afterwards.</para>
143+
</sect2>
144+
</sect1>
145+
146+
<!-- ================================================================== -->
132147

133148
</article>

0 commit comments

Comments
 (0)