PDF Output

Introduction

Davisor Chart supports Portable Document Format (PDF) output through the use of World Wide Web Consortium (W3C) eXtendable Stylesheet Language Formatted Objects (XSL-FO) and Scalable Vector Graphics (SVG). The process to produce PDF documents out of XSL-FO data and SVG images is straighforward, but it requires some external software and some initial setup work. The following chapters tell what is needed, and how the process is set up.

PDF Production

Davisor Chart PDF document production process is in many ways identical to Davisor Chart process of producing HTML web content, except that for PDF output, the content layout language of choice is not HTML or XHTML, but XSL-FO. Another important difference to HTML production is that the XSL-FO is not typically served forward as such, but it is instead rendered to PDF first.

The whole PDF production process consists of the following steps:

  1. Define a XSL-FO document template with Davisor Chart placeholders and other dynamic references to information outside the template.
  2. At the moment someone requests the document, instantiate the template by replacing all placeholders with actual, fresh content.
  3. Render the instantiated XSL-FO document as PDF.
  4. Deliver the resulting PDF document.

XSL-FO Templates

XSL-FO templates are identical in principle to corresponding HTML and XHTML templates. In particular, a XSL-FO template defines the positions of Davisor Chart images and tables within a XSL-FO document, as well as all the other content, just like a HTML template would do for a HTML document.

XSL-FO is in many ways more powerfull a layout language than HTML and XHTML, and therefore it is somewhat more complex, too. Fortunately, this complexity does not complicate the production process or the basic operation principle of the XSL-FO templates in any way. Indeed, Davisor Chart content can be embedded inside XSL-FO document templates in exactly the same manner as they are embedded inside HTML or XHTML documents.

PDF Rendering

After a XSL-FO document template has been instantiated and filled with appropriate dynamic content, the XSL-FO content is ready to be rendered as PDF. Davisor Chart example web application uses a slighly modified Apache FOP FOPServlet which may be used to transfer any XSL-FO content to PDF. In Davisor Chart example web application, this servlet is bound to /fop address, relative to web application root. In terms of standard web application configuration, this means that the Davisor Chart web application deployment descriptor file /WEB-INF/web.xml contains the following lines:

<servlet>
  <servlet-name>fop</servlet-name>
  <servlet-class>FOPServlet</servlet-class>
</servlet>

<servlet-mapping>
  <servlet-name>fop</servlet-name>
  <url-pattern>/fop</url-pattern>
</servlet-mapping>

In order to use Apache FOPServlet in your own web applications, all you need to do is to copy the WEB-INF/classes/FOPServlet.class file from Davisor Chart example web application into your own web application, and add the corresponding entries into you own web application deployment description file. You must also make sure that you have Apache FOP installed into you system, as described in the PDF Renderers chapter below. Of course, you may also choose to use any other XSL-FO rendering tool, but in that case you can not use the Apache FOP specific FOPServlet anymore.

Specifying File to Render for FOPServlet

When FOPServlet is called, the file that the servlet should render is specified with a fo parameter. For example, if the file to be rendered were pie.jsp, the FOPServlet should be called with

/chart/fop?fo=pie.jsp

Note that some browsers do not necessarily recognize the type of the file that the FOPServlet produces correctly and therefore fail to show the resulting PDF file. This kind of a problem and solutions for it are described in Apache FOP Servlets documentation.

Configuring FOPServlet

The transforming of XLS-FO to PDF with Apache FOPServlet can be affected with a few configuration parameters. The configuration parameters are collected to a properties file named as fopconfig.properties and it resides in WEB-INF/classes/ directory. If you copy the WEB-INF/classes/FOPServlet.class file from Davisor Chart example web application into your own web application, remember to copy the fopconfig.properties file to the same directory into which you copy the FOPServlet.class. The configurations in the fopconfig.properties file are read before the first file is rendered by FOPServlet after the starting of a web application.

You may change the values of configuration parameters in the fopconfig.properties file to be what you want. Probably the most interesting parameters for you are the setting of fonts and rendering text in SVG as text in PDF.

The modified FOPServlet can also read configurations from a given property file. The property file to read is given to the FOPServlet with a config parameter that is given in addition to the file that should be rendered. If a configuration file were myconfig.properties and the file to render were pie.jsp, the FOPServlet should be called with

/chart/fop?fo=pie.jsp&config=myconfig.properties

The given configuration file myconfig.properties should be somewhere in the classpath of your web application. When a user specified configuration file is read, the settings of the configuration file are in effect until some other configuration file is read.

For more details and examples about (Apache FOP specific) PDF rendering servlets, please see Apache FOP Servlets documentation.

PDF and SVG

XSL-FO has full support for various raster image formats, and therefore it is perfectly possible to place basic Davisor Chart raster images inside any XSL-FO templates, and then render the results as PDF. However, PDF is often used in printing and printing-like applications, and in these cases the documents get often scaled a lot. The unfortunate problem with this is that raster images react often badly to scaling. This problem has already been described in more detail in the Units chapter.

The use of SVG images insteads of raster images completely solves all problems with image scaling. After all, the SVG acronym stands for Scalable Vector Graphics. SVG image file sizes may also be in some cases hundreds of times smaller that the file sizes of corresponding raster images. This has various performance benefits which is some cases may be very significant.

The use of SVG images with Davisor Chart requires the purchase of a separate Davisor SVG Extension. Once installed, a new image/svg+xml image contentType value is enabled, after which any Davisor Chart image output may be expressed as a SVG image.

PDF Renderers

As described by the W3C XSL-FO introductionary documentation, the process of converting XSL-FO/SVG content to a PDF document (or to any other alternative graphics format) is called rendering. This rendering must be done by some suitable XSL-FO renderer application. The following XSL-FO rendering applications have been explicitly recognized by W3C. There may certainly be other similar suitable applications, too.

Apache FOP

All Davisor Chart PDF demonstrations use Apache Formatting Objects Processor (FOP). Davisor Chart is however not in any way dependent on Apache FOP. Indeed, any standard compliant XSL-FO renderer could be used instead, and Apache FOP has been selected only because it is free and open software, as described in more detail by Apache FOP License. For those willing to conform to the license conditions, the Apache FOP software is available for immediate download.

FOP is also still very much a work in progress: as of fall of 2003, the latest available FOP version is 0.20.5, and with it, many finer details of XSL-FO rendering do not yet work properly. Some do not work at all.

Installing FOP

The best source for information of how to install Apache FOP is always the installation document inside the corresponding Apache FOP download package. Apache FOP installation typically requires some straigforward file copying so that the FOP software functions can be located and invoked by applications that need them.

The details of what FOP installation files go where depend on the application environment in question. A typical example case would be Davisor Chart packed in a web application run by a Apache Tomcat web application container. In such a case and with FOP version 0.20.5 and Tomcat version 4.1.27, the most convenient way to install FOP would be to copy the following FOP files into Tomcat common/lib/ directory.

PDF Limitations

PDF output has the following known limitations and problems:

PDF Examples

The red buttons below expect that Apache FOP has been locally installed. If not, the operations invoked by these buttons will fail.

A pie chart with legend.
A table chart.