Search the documentation
 Show GitHub edit links  Hide GitHub edit links
In OpenCms since: 9.5 Documented since: 9.5 Latest revision for: 9.5 Valid for OpenCms: 10.5.3

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.

Use cases

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.

How to generate PDF output?

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>.

Using 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.

Attributes of the tag <cms:pdf>
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.

Writing the JSP for PDF rendering

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>

Technical details

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.pdfutils. The class for exposing the tag is found here.

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.