OpenCms documentation
OpenCms documentation

Generating PDF output

OpenCms supports automatic PDF generation from XML contents. Via a special formatter-like JSP a PDF file is generated on the fly when rendering the JSP. The intended use-case is to render contents in a PDF file. But the concept is not limited to that use-case. You can also render information from different contents.

Technology for PDF generation

More on PDF generation in OpenCms

The main intention on PDF generation support is to allow rendering XML contents into PDF files. Hence use cases are:

  • Newsletters in PDF format
  • Printable contact information
  • Job offers in PDF files
  • Product information
  • ...

For very native output support, it is assumed that the information you want to render in a PDF file is stored in a single XML content. But, you are not limited to that scenario. You may also grep information from various contents and, for example, make lists of content also available in PDF format (e.g., latest news). But be aware of the caching behavior as described below. The options of placing context information, headers, footers and page numbers are also provided via CSS's page media support.

In the end, you may not have to maintain information for your website and your PDF newsletters or maybe also small booklets twice. Just generate HTML and PDF from the same XML contents.

PDF output is generated by OpenCms using the open source library "Flying Saucer". It converts XHTML marked up with CSS (2.1 + some features of version 3) to PDF. The conversion is triggered, when the PDF is requested. The link for requesting the PDF is generated by the tag <cms:pdf>.

The tag <cms:pdf> generates a link to a PDF. When the link is requested, PDF generation is triggered and the PDF is served under that link. Thus, the tag is typically used to generate the value for the href attribute of a link, e.g.:

<a   href="<cms:pdf format='%(link.weak:/system/modules/my.module/pages/mypdf.jsp'
		  content='${content.filename}' 
		  locale='en' />"
     target="pdf">
   Download as PDF
</a>

Note, that for the download link you can specify the target attribute of the anchor tag <a> as "pdf". The tag <cms:pdf> has the following three attributes.

format

VFS URI of the JSP that renders the XHTML that is translated to PDF. (See the next subsection)

content

VFS URI of the XML content that should be rendered. Typically this will be the URI of the content that is currently rendered, i.e., you can use ${content.filename} to specify the URI.

locale (optional)

The locale in which the content should be accessed. If not given, the locale from the request context is used.

For PDF generation you need a special JSP that renders to strict XHTML 1.0 and that is styled with CSS 2.1 suitable for printable, paged media. That's what Flying Saucer, the library for PDF generation, expects as input.

In the JSP you can

  • use the <cms:formatter> tag to access the content you provided via the content attribute of the <cms:pdf> tag.
  • use <cms:contentload> to access any other contents
  • use all other features as in a normal formatter JSP

But one thing you should take into account:

You should make sure to generate valid, strict XHTML 1.0 and style mainly with CSS 2.1.

The restriction is due to Flying Saucer, which expects such an input format. Here is a template for a JSP used for PDF generation. Note that the title in the HTML head section is used to generate the name of the PDF.

<%@page trimDirectiveWhitespaces="true" buffer="none" session="false" taglibs="c,cms,fmt,fn" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict //EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<cms:formatter var="content">
<head>
<title>${content.value.Title}</title>
	<link rel="stylesheet" href="<cms:link>%(link.weak:/link/to/your/pdfstyle.css)</cms:link>" type="text/css" />
</head>
<body>

     <%-- Render valid XHTML 1.0 here --%>

</body>
</cms:formatter>
</html>

PDFs are not stored in the VFS. When a <cms:pdf> tag is rendered, a special link to the, not yet present, PDF is generated. If the link is requested the first time, the PDF is rendered. If it is requested again a cached version of the PDF is served. The cached versions are stored on the server's RFS in the folder {webapp home}/WEB-INF/pdfcache.

The cache is cleared when the JSP that renders the PDF, or the XML content that is rendered are changed. Other changes do not cause the cache to be cleared.

The interesting code for the PDF generation is found in the module org.opencms.pdftools. The class for exposing the tag is found here.