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 automated PDF generation. It's mainly intended to render your content in a PDF file. Here, we show you how to render a demo article as PDF.

The result

If you click on the "PDF"-icon in the demo article below, a the article is rendered into a pdf file.

 

PDF generation

You can render me as pdf. If I'm formatted with the correct formatter you see a button to generate the PDF. Just go for it.

 

Example resources and the interesting spots

To enable PDF generation as shown in the above example, we have

  • Used the tag <cms:pdf> in the article's formatter
  • Added a JSP that renders the content to XHTML and includes styles that are used for the styling in the PDF.

All the work of transforming the XHTML to PDF is done by the open source Java library "Flying Saucer". It can handle XHTML 1.0 documents and CSS conformant with the 2.1 specification plus some extensions (that are part of CSS 3).

Using the <cms:pdf> tag

The <cms:pdf> tag is used to create the link target for downloading the PDF. The PDF is created on the fly, when the link is requested. Here's the formatter of the demo article as used above:

<%@page buffer="none" session="false" taglibs="c,cms" %>
<cms:formatter var="content" val="value">
<div style="margin-bottom:30px;">
    <div class="headline">
		<h3>${value.Title}</h3>       
	</div>
	<c:if test="${value.Image.isSet}">
		<div style="float:left;">
			<cms:img src="${value.Image}" height="100" width="300" />
		</div>
	</c:if>
    <div>
        ${value.Text}
    </div>
    <div style="padding-top:10px;">
         <a href="<cms:pdf format='%(link.weak:/system/modules/com.alkacon.opencms.documentation/pages/demo/demo-article-pdf.jsp:d53aaf1c-64d2-11e4-9296-005056b61161)'
		                   content='${content.filename}' 
						   locale='en' />"
			target="pdf">
            <cms:img height="32" src="%(link.strong:/system/modules/com.alkacon.opencms.documentation/resources/demo/img/218-PDFPage.png:a1ddf340-64d0-11e4-9296-005056b61161)" alt="Download PDF" title="Download as PDF" />
        </a>
    </div>
	<div style="clear:left;"></div>
</div>
</cms:formatter>

Watch out for the <cms:pdf> tag. It is used to create the value of the href attribute of the link for PDF generation. The tag itself has three attributes:

format

VFS URI of the JSP that renders the XHTML that is translated to PDF.

content

VFS URI of the XML content that should be rendered. Here its the VFS URI of the content that's rendered by the formatter.

locale (optional)

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

The JSP for formatting the PDF

The JSP that generates the XHTML for PDF generation is very similar to the content's formatter. That's how it looks:

<%@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:/system/modules/com.alkacon.opencms.documentation/resources/demo/css/pdf.css:243ee99e-64f7-11e4-9296-005056b61161)</cms:link>" type="text/css" />
</head>
<body>
<div>
	<h1>
		${content.value.Title}
	</h1>
	<c:if test="${content.value.Image.isSet}">
		<div style="float:left; padding-right:20px;">
			<cms:img src="${content.value.Image}" width="200" />
		</div>
	</c:if>
    <div>
        ${content.value.Text}
    </div>
	<div style="clear:left;"></div>
</div>
</body>
</cms:formatter>
</html>

The JSP is very similar to the formatter (at least if you want to print the same content elements as you render in the formatter). The main difference is that you have to add the frame of an XHTML 1.0 document. That is in particular:

  • the DOCTYPE information
  • the basic HTML structure with <html>, <head> and <body>
  • typically, special stylesheets that should be used during PDF generation.

You should be aware that CSS 2.1 has also special styles for paged media as PDF is. Here we used just a very simple example stylesheet:

@page {
	margin: 3cm;
	font-family: Times, serif;
	border: 1px dotted gray;
}

h1 {
	text-decoration: underline;
	color: red;
}

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.