Skip to content

Commit ed4bc34

Browse files
joewizjoewiz
authored
Merge pull request #726 from adamretter/fo-render
Add a page about XSL:FO rendering
2 parents a42d5e5 + fef8ca1 commit ed4bc34

File tree

18 files changed

+261
-0
lines changed

18 files changed

+261
-0
lines changed

‎src/main/xar-resources/data/documentation/documentation.xml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,14 @@
229229
<para>How to perform XSL Transformation with XQuery.</para>
230230
</listitem>
231231
</varlistentry>
232+
<varlistentry>
233+
<term>
234+
<link xlink:href="xsl-transform">FO Rendering</link>
235+
</term>
236+
<listitem>
237+
<para>How to perform FO (Formatting Objects) Rendering with XQuery.</para>
238+
</listitem>
239+
</varlistentry>
232240
<varlistentry>
233241
<term>
234242
<link xlink:href="indexing">Indexing</link>

‎src/main/xar-resources/data/fo-render/fo-render.xml‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
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>FO Rendering</title>
6+
<date>1Q22</date>
7+
<keywordset>
8+
<keyword>application-development</keyword>
9+
</keywordset>
10+
</info>
11+
12+
<!-- ================================================================== -->
13+
14+
<para>eXist-db can perform FO (Formatting Objects) rendering inside XQuery code. The FO can be
15+
generated used XSL (i.e. XSL:FO) if desired. For this you need to use the <code>xslfo</code>
16+
module.</para>
17+
18+
<!-- ================================================================== -->
19+
20+
<sect1 xml:id="render-module">
21+
<title>The <code>xslfo</code> module</title>
22+
23+
<para>eXist-db XSL:FO module allows you to do FO rendering from XQuery code using an appropriate
24+
FO Renderer; eXist-db supports <link xlink:href="https://xmlgraphics.apache.org/fop/">Apache FOP</link> and <link xlink:href="http://www.renderx.com/tools/xep.html">RenderX XEP</link>. Previously there was also support
25+
for AntennaHouse, but that was removed as it was unmaintained, we would welcome a new
26+
contribution to support AntennaHouse again.</para>
27+
<para>Selection of the renderer is configured in eXist-db's <code>conf.xml</code> file.
28+
By default eXist-db ships with and is configured to use Apache FOP, see: <link linkend="apachefop">Using
29+
the Apache FOP Renderer</link></para>
30+
<para>If you wish to use RenderX XEP instead, see <link linkend="renderx">Using
31+
the RenderX XEP FO Renderer</link>. </para>
32+
<para>Its function namespace is <literal>http://exist-db.org/xquery/xslfo</literal>.</para>
33+
34+
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
35+
36+
<sect2 xml:id="render">
37+
<title>
38+
<code>xslfo:render()</code>
39+
</title>
40+
41+
<para>The <code>xslfo:render</code> function renders an FO document and returns you the result.
42+
It has two signatures:</para>
43+
<programlisting language="xquery" xlink:href="listings/listing-1.txt"/>
44+
<programlisting language="xquery" xlink:href="listings/listing-2.txt"/>
45+
46+
<variablelist>
47+
<varlistentry>
48+
<term>
49+
<code>$document</code>
50+
</term>
51+
<listitem>
52+
<para>The FO document to be rendered.</para>
53+
</listitem>
54+
</varlistentry>
55+
<varlistentry>
56+
<term>
57+
<code>$media-type</code>
58+
</term>
59+
<listitem>
60+
<para>The Internet Media Type of the desired result. This provides a hint to the renderer as to what format it should render</para>
61+
</listitem>
62+
</varlistentry>
63+
<varlistentry>
64+
<term>
65+
<code>$parameters</code>
66+
</term>
67+
<listitem>
68+
<para>Specify any optional parameters for the rendering of the FO document, these are processor specific.</para>
69+
</listitem>
70+
</varlistentry>
71+
<varlistentry>
72+
<term>$processor-config</term>
73+
<listitem>
74+
<para>An optional configuration document for the processor, this is processor specific.</para>
75+
</listitem>
76+
</varlistentry>
77+
</variablelist>
78+
</sect2>
79+
80+
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
81+
82+
<sect2 xml:id="stream-render">
83+
<title>
84+
<code>Streaming the result to a Web Browser</code>
85+
</title>
86+
87+
<para>If you wish to Stream the result of <code>xslfo:render</code> directly to the Web Browser (i.e. HTTP Response), you
88+
can send the output of <code>xslfo:render</code> directly to the function <code>response:stream-binary</code>. This can be
89+
useful for example when you want an XQuery to download a PDF directly to the Web Browser.</para>
90+
</sect2>
91+
92+
</sect1>
93+
94+
<sect1 xml:id="apachefop">
95+
<title>Using the Apache FOP Renderer</title>
96+
<para>By default eXist-db ships with and is configured to use Apache FOP. It is configured in eXist-db's <code>conf.xml</code> file through the following configuration option:</para>
97+
<programlisting language="xml"><![CDATA[<module uri="http://exist-db.org/xquery/xslfo" class="org.exist.xquery.modules.xslfo.XSLFOModule">
98+
<parameter name="processorAdapter" value="org.exist.xquery.modules.xslfo.ApacheFopProcessorAdapter"/>
99+
</module>]]></programlisting>
100+
<para>
101+
An example of using Apache FOP to transform FO and save the result to a PDF file in the database.
102+
</para>
103+
<example>
104+
<title>Using Apache FOP from XQuery</title>
105+
<programlisting language="xquery" xlink:href="listings/listing-3.txt"/>
106+
</example>
107+
108+
</sect1>
109+
110+
<sect1 xml:id="renderx">
111+
<title>Using the RenderX XEP FO Renderer</title>
112+
<para>To configure eXist-db to use RenderX XEP instead of Apache FOP, follow these steps:</para>
113+
<orderedlist>
114+
<listitem>
115+
<para>From a RenderX distribution, copy the files <code>lib/xep.jar</code> and <code>lib/xt.jar</code> into the folder <code>$EXIST_HOME/lib</code>.</para>
116+
</listitem>
117+
<listitem>
118+
<para>eXist-db uses a number of configuration files, one per script, to determine which <code>jar</code> files to load. You should edit the XML files in the folder <code>$EXIST_HOME/etc</code> to add the following configuration (adjust the <emphasis>version</emphasis> numbers appropriately):</para>
119+
<programlisting language="xml"><![CDATA[[<dependency>
120+
<groupId>com.renderx.xep</groupId>
121+
<artifactId>xep</artifactId>
122+
<version>4.30.961</version>
123+
<relativePath>xep.jar</relativePath>
124+
</dependency>
125+
<dependency>
126+
<groupId>com.renderx.xep.thirdparty.com.jclark.xsl</groupId>
127+
<artifactId>xt</artifactId>
128+
<version>4.30.961</version>
129+
<relativePath>xt.jar</relativePath>
130+
</dependency>]]></programlisting>
131+
</listitem>
132+
<listitem>
133+
<para>Create the folder <code>$EXIST_HOME/renderx</code></para>
134+
</listitem>
135+
<listitem>
136+
<para>From a RenderX distribution, copy the files <code>xep.xml</code> and <code>rolemap.xml</code>, and the folders <code>fonts</code>, <code>hyphen</code>, and <code>images</code> into the folder <code>$EXIST_HOME/renderx</code>.</para>
137+
</listitem>
138+
<listitem>
139+
<para>Edit the file <code>$EXIST_HOME/renderx/xep.xml</code> to make the following changes:</para>
140+
<itemizedlist>
141+
<listitem>
142+
<para>From:</para><programlisting language="xml"><![CDATA[<option name="LICENSE" value="license.xml"/>]]></programlisting>
143+
<para>To:</para><programlisting language="xml"><![CDATA[<option name="LICENSE" value="renderx/license.xml"/>]]></programlisting>
144+
</listitem>
145+
<listitem>
146+
<para>From:</para> <programlisting language="xml"><![CDATA[<option name="BROKENIMAGE" value="images/404.gif"/>
147+
<option name="LOGO" value="images/logo-renderx.svg"/>
148+
<option name="STAMP_PNG" value="images/stamp-renderx.png"/>
149+
<option name="ROLE_MAP" value="rolemap.xml"/>]]></programlisting>
150+
<para>To:</para> <programlisting language="xml"><![CDATA[<option name="BROKENIMAGE" value="renderx/images/404.gif"/>
151+
<option name="LOGO" value="renderx/images/logo-renderx.svg"/>
152+
<option name="STAMP_PNG" value="renderx/images/stamp-renderx.png"/>
153+
<option name="ROLE_MAP" value="renderx/rolemap.xml"/>]]></programlisting>
154+
</listitem>
155+
<listitem>
156+
<para>From:</para> <programlisting language="xml"><![CDATA[<fonts xml:base="fonts/" default-family="Helvetica">]]></programlisting>
157+
<para>To:</para> <programlisting language="xml"><![CDATA[<fonts xml:base="renderx/fonts/" default-family="Helvetica">]]></programlisting>
158+
</listitem>
159+
<listitem>
160+
<para>From:</para> <programlisting language="xml"><![CDATA[<languages default-language="en-US" xml:base="hyphen/">]]></programlisting>
161+
<para>To:</para> <programlisting language="xml"><![CDATA[<languages default-language="en-US" xml:base="renderx/hyphen/">]]></programlisting>
162+
</listitem>
163+
</itemizedlist>
164+
</listitem>
165+
<listitem>
166+
<para>Copy your RenderX XEP license file (<code>license.xml</code>) that you have been provided by RenderX into <code>$EXIST_HOME/renderx</code>.</para>
167+
</listitem>
168+
<listitem>
169+
<para>Edit the file <code>$EXIST_HOME/conf.xml</code> to make the following changes:</para>
170+
<para>From:</para> <programlisting language="xml"><![CDATA[<module uri="http://exist-db.org/xquery/xslfo" class="org.exist.xquery.modules.xslfo.XSLFOModule">
171+
<parameter name="processorAdapter" value="org.exist.xquery.modules.xslfo.ApacheFopProcessorAdapter"/>
172+
</module>]]></programlisting>
173+
<para>To: </para><programlisting language="xml"><![CDATA[<module uri="http://exist-db.org/xquery/xslfo" class="org.exist.xquery.modules.xslfo.XSLFOModule">
174+
<parameter name="processorAdapter" value="org.exist.xquery.modules.xslfo.RenderXXepProcessorAdapter"/>
175+
</module>]]></programlisting>
176+
</listitem>
177+
<listitem>
178+
<para>If eXist-db was running whilst you were making these changes, then you will need to restart it for the change to take effect.</para>
179+
</listitem>
180+
</orderedlist>
181+
<para>
182+
An example of using RenderX XEP to transform FO and save the result to a PDF file on the filesystem.
183+
</para>
184+
<example>
185+
<title>Using RenderX XEP from XQuery</title>
186+
<programlisting language="xquery" xlink:href="listings/listing-4.txt"/>
187+
</example>
188+
189+
</sect1>
190+
191+
<!-- ================================================================== -->
192+
193+
</article>

‎src/main/xar-resources/data/fo-render/listings/listing-1.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
xslfo:render($document as node(), $media-type as xs:string, $parameters as node()?) as xs:base64Binary

‎src/main/xar-resources/data/fo-render/listings/listing-10.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<fonts xml:base="fonts/" default-family="Helvetica">

‎src/main/xar-resources/data/fo-render/listings/listing-11.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<fonts xml:base="renderx/fonts/" default-family="Helvetica">

‎src/main/xar-resources/data/fo-render/listings/listing-12.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<languages default-language="en-US" xml:base="hyphen/">

‎src/main/xar-resources/data/fo-render/listings/listing-13.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<languages default-language="en-US" xml:base="renderx/hyphen/">

‎src/main/xar-resources/data/fo-render/listings/listing-14.xml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
<module uri="http://exist-db.org/xquery/xslfo" class="org.exist.xquery.modules.xslfo.XSLFOModule">
2+
<parameter name="processorAdapter" value="org.exist.xquery.modules.xslfo.ApacheFopProcessorAdapter"/>
3+
</module>

‎src/main/xar-resources/data/fo-render/listings/listing-15.xml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
<module uri="http://exist-db.org/xquery/xslfo" class="org.exist.xquery.modules.xslfo.XSLFOModule">
2+
<parameter name="processorAdapter" value="org.exist.xquery.modules.xslfo.RenderXXepProcessorAdapter"/>
3+
</module>

‎src/main/xar-resources/data/fo-render/listings/listing-16.txt‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
xquery version "3.0";
2+
3+
declare namespace file = "http://exist-db.org/xquery/file";
4+
declare namespace system = "http://exist-db.org/xquery/system";
5+
declare namespace xslfo = "http://exist-db.org/xquery/xslfo";
6+
7+
let $config := fn:parse-xml(file:read(system:get-exist-home() || "/renderx/xep.xml"))
8+
return
9+
10+
let $fo := fn:doc('/db/test-fo.xml')
11+
let $pdf := xslfo:render($fo, "application/pdf", (), $config)
12+
return
13+
file:serialize-binary($pdf, "/tmp/fop.pdf")

0 commit comments

Comments
 (0)