Add a page about XSL:FO rendering

eXist-db · Jan 7, 2022 · 84ecb62 · 84ecb62
1 parent 798be9b
commit 84ecb62
Show file tree

Hide file tree

Showing 5 changed files with 221 additions and 0 deletions.
diff --git a/src/main/xar-resources/data/fo-render/fo-render.xml b/src/main/xar-resources/data/fo-render/fo-render.xml
@@ -0,0 +1,196 @@
+<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
+<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
+<article version="5.0" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <info>
+    <title>FO Rendering</title>
+    <date>1Q22</date>
+    <keywordset>
+      <keyword>application-development</keyword>
+    </keywordset>
+  </info>
+
+  <!-- ================================================================== -->
+
+  <para>eXist-db can perform FO (Formatting Objects) rendering inside XQuery code. The FO can be
+    generated used XSL (i.e. XSL:FO) if desired. For this you need to use the <code>xslfo</code>
+    module.</para>
+
+  <!-- ================================================================== -->
+
+  <sect1 xml:id="render-module">
+    <title>The <code>xslfo</code> module</title>
+
+    <para>eXist-db XSL:FO module allows you to do FO rendering from XQuery code using an appropriate
+      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
+      for AntennaHouse, but that was removed as it was unmaintained, we would welcome a new
+      contribution to support AntennaHouse again.</para>
+    <para>Selection of the renderer is configured in eXist-db's <filename>conf.xml</filename> file.
+      By default eXist-db ships with and is configured to use Apache FOP, see: <link linkend="renderx">Using
+        the Apache FOP Renderer</link></para>
+    <para>If you wish to use RenderX XEP instead, see <link linkend="renderx">Using
+        the RenderX XEP FO Renderer</link>. </para>
+    <para>Its function namespace is <literal>http://exist-db.org/xquery/xslfo</literal>.</para>
+
+    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+
+    <sect2 xml:id="render">
+      <title>
+        <code>xsl:render()</code>
+      </title>
+
+      <para>The <code>xsl:render</code> function renders an FO document and returns you the result.
+        It has two signatures:</para>
+      <programlisting language="xquery" xlink:href="listings/listing-1.txt"/>
+      <programlisting language="xquery" xlink:href="listings/listing-2.txt"/>
+
+      <variablelist>
+        <varlistentry>
+          <term>
+            <code>$document</code>
+          </term>
+          <listitem>
+            <para>The FO document to be rendered.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>
+            <code>$media-type</code>
+          </term>
+          <listitem>
+            <para>The Internet Media Type of the desired result. This provides a hint to the renderer as to what format it should render</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>
+            <code>$parameters</code>
+          </term>
+          <listitem>
+            <para>Specify any optional parameters for the rendering of the FO document, these are processor specific.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>$processor-config</term>
+          <listitem>
+            <para>An optional configuration document for the processor, this is processor specific.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect2>
+
+    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+
+    <sect2 xml:id="stream-render">
+      <title>
+        <code>Streaming the result to a Web Browser</code>
+      </title>
+
+      <para>If you wish to Stream the result of <code>xslfo:render</code> directly to the Web Browser (i.e. HTTP Response), you
+        can send the output of <code>xslfo:render</code> directly to the function <code>response:stream-binary</code>. This can be
+        useful for example when you want an XQuery to download a PDF directly to the Web Browser.</para>
+    </sect2>
+
+  </sect1>
+
+  <sect1 xml:id="apachefop">
+    <title>Using the Apache FOP Renderer</title>
+    <para>By default eXist-db ships with and is configured to use Apache FOP. It is configured in eXist-db's <filename>conf.xml</filename> file through the following configuration option:
+      <programlisting language="xml"><![CDATA[<module uri="http://exist-db.org/xquery/xslfo" class="org.exist.xquery.modules.xslfo.XSLFOModule">
+  <parameter name="processorAdapter" value="org.exist.xquery.modules.xslfo.ApacheFopProcessorAdapter"/>
+</module>]]></programlisting></para>
+    <para>
+      An example of using Apache FOP to transform FO and save the result to a PDF file in the database.
+      <example>
+        <title>Using Apache FOP from XQuery</title>
+        <programlisting language="xquery" xlink:href="listings/listing-3.txt"/>
+      </example>
+    </para>
+
+  </sect1>
+
+  <sect1 xml:id="renderx">
+    <title>Using the RenderX XEP FO Renderer</title>
+    <para>To configure eXist-db to use RenderX XEP instead of Apache FOP, follow these steps:
+      <orderedlist>
+        <listitem>
+          <para>From a RenderX distribution, copy the files <filename>lib/xep.jar</filename> and <filename>lib/xt.jar</filename> into the folder <filename>$EXIST_HOME/lib</filename>.</para>
+        </listitem>
+        <listitem>
+          <para>eXist-db uses a number of configuration files, one per script, to determine which <filename>jar</filename> files to load. You should edit the XML files in the folder <filename>$EXIST_HOME/etc</filename> to add the following configuration (adjust the <emphasis>version</emphasis> numbers appropriately):
+            <programlisting language="xml"><![CDATA[[<dependency>
+  <groupId>com.renderx.xep</groupId>
+  <artifactId>xep</artifactId>
+  <version>4.30.961</version>
+  <relativePath>xep.jar</relativePath>
+</dependency>
+<dependency>
+  <groupId>com.renderx.xep.thirdparty.com.jclark.xsl</groupId>
+  <artifactId>xt</artifactId>
+  <version>4.30.961</version>
+  <relativePath>xt.jar</relativePath>
+</dependency>]]></programlisting>
+          </para>
+        </listitem>
+        <listitem>
+          <para>Create the folder <filename>$EXIST_HOME/renderx</filename></para>
+        </listitem>
+        <listitem>
+          <para>From a RenderX distribution, copy the files <filename>xep.xml</filename> and <filename>rolemap.xml</filename>, and the folders <filename>fonts</filename>, <filename>hyphen</filename>, and <filename>images</filename> into the folder <filename>$EXIST_HOME/renderx</filename>.</para>
+        </listitem>
+        <listitem>
+          <para>Edit the file <filename>$EXIST_HOME/renderx/xep.xml</filename> to make the following changes:
+            <itemizedlist>
+              <listitem>
+                <para>From: <programlisting language="xml"><![CDATA[<option name="LICENSE" value="license.xml"/>]]></programlisting></para>
+                <para>To: <programlisting language="xml"><![CDATA[<option name="LICENSE" value="renderx/license.xml"/>]]></programlisting></para>
+              </listitem>
+              <listitem>
+                <para>From: <programlisting language="xml"><![CDATA[<option name="BROKENIMAGE" value="images/404.gif"/>
+<option name="LOGO" value="images/logo-renderx.svg"/>
+<option name="STAMP_PNG" value="images/stamp-renderx.png"/>
+<option name="ROLE_MAP" value="rolemap.xml"/>]]></programlisting></para>
+                <para>To: <programlisting language="xml"><![CDATA[<option name="BROKENIMAGE" value="renderx/images/404.gif"/>
+<option name="LOGO" value="renderx/images/logo-renderx.svg"/>
+<option name="STAMP_PNG" value="renderx/images/stamp-renderx.png"/>
+<option name="ROLE_MAP" value="renderx/rolemap.xml"/>]]></programlisting></para>
+              </listitem>
+              <listitem>
+                <para>From: <programlisting language="xml"><![CDATA[<fonts xml:base="fonts/" default-family="Helvetica">]]></programlisting></para>
+                <para>To: <programlisting language="xml"><![CDATA[<fonts xml:base="renderx/fonts/" default-family="Helvetica">]]></programlisting></para>
+              </listitem>
+              <listitem>
+                <para>From: <programlisting language="xml"><![CDATA[<languages default-language="en-US" xml:base="hyphen/">]]></programlisting></para>
+                <para>To: <programlisting language="xml"><![CDATA[<languages default-language="en-US" xml:base="renderx/hyphen/">]]></programlisting></para>
+              </listitem>
+            </itemizedlist>
+          </para>
+        </listitem>
+        <listitem>
+          <para>Copy your RenderX XEP license file (<filename>license.xml</filename>) that you have been provided by RenderX into <filename>$EXIST_HOME/renderx</filename>.</para>
+        </listitem>
+        <listitem>
+          <para>Edit the file <filename>$EXIST_HOME/conf.xml</filename> to make the following changes:</para>
+          <para>From: <programlisting language="xml"><![CDATA[<module uri="http://exist-db.org/xquery/xslfo" class="org.exist.xquery.modules.xslfo.XSLFOModule">
+  <parameter name="processorAdapter" value="org.exist.xquery.modules.xslfo.ApacheFopProcessorAdapter"/>
+</module>]]></programlisting></para>
+          <para>To: <programlisting language="xml"><![CDATA[<module uri="http://exist-db.org/xquery/xslfo" class="org.exist.xquery.modules.xslfo.XSLFOModule">
+  <parameter name="processorAdapter" value="org.exist.xquery.modules.xslfo.RenderXXepProcessorAdapter"/>
+</module>]]></programlisting></para>
+        </listitem>
+        <listitem>
+          <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>
+        </listitem>
+      </orderedlist>
+    </para>
+    <para>
+      An example of using RenderX XEP to transform FO and save the result to a PDF file on the filesystem.
+      <example>
+        <title>Using RenderX XEP from XQuery</title>
+        <programlisting language="xquery" xlink:href="listings/listing-4.txt"/>
+      </example>
+    </para>
+
+  </sect1>
+
+  <!-- ================================================================== -->
+
+</article>
diff --git a/src/main/xar-resources/data/fo-render/listings/listing-1.txt b/src/main/xar-resources/data/fo-render/listings/listing-1.txt
@@ -0,0 +1 @@
+xslfo:render($document as node(), $media-type as xs:string, $parameters as node()?) as xs:base64Binary
diff --git a/src/main/xar-resources/data/fo-render/listings/listing-2.txt b/src/main/xar-resources/data/fo-render/listings/listing-2.txt
@@ -0,0 +1 @@
+xslfo:render($document as node(), $media-type as xs:string, $parameters as node()?, $processor-config as node()?) as xs:base64Binary
diff --git a/src/main/xar-resources/data/fo-render/listings/listing-3.txt b/src/main/xar-resources/data/fo-render/listings/listing-3.txt
@@ -0,0 +1,10 @@
+xquery version "1.0";
+
+declare namespace file = "http://exist-db.org/xquery/file";
+declare namespace xmldb = "http://exist-db.org/xquery/xmldb";
+declare namespace xslfo = "http://exist-db.org/xquery/xslfo";
+
+let $fo := fn:doc('/db/test-fo.xml')
+let $pdf := xslfo:render($fo, "application/pdf", (), ())
+return
+  xmldb:store("/db", "result.pdf", $pdf, "application/pdf")
diff --git a/src/main/xar-resources/data/fo-render/listings/listing-4.txt b/src/main/xar-resources/data/fo-render/listings/listing-4.txt
@@ -0,0 +1,13 @@
+xquery version "3.0";
+
+declare namespace file = "http://exist-db.org/xquery/file";
+declare namespace system = "http://exist-db.org/xquery/system";
+declare namespace xslfo = "http://exist-db.org/xquery/xslfo";
+
+let $config := fn:parse-xml(file:read(system:get-exist-home() || "/renderx/xep.xml"))
+return
+
+  let $fo := fn:doc('/db/test-fo.xml')
+  let $pdf := xslfo:render($fo, "application/pdf", (), $config)
+  return
+  file:serialize-binary($pdf, "/tmp/fop.pdf")
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		xslfo:render($document as node(), $media-type as xs:string, $parameters as node()?) as xs:base64Binary