Creating thumbnails for PDFs

In OpenCms since: 9.5 Valid for OpenCms: 11.0.0

OpenCms provides a special tag for PDF thumbnail generation: You just provide the PDF, the thumbnail should be generated for, the size and the format (png or jpg) of the resulting thumbnail and the thumbnail will be generated if requested, and reachable via the URL rendered by special tag.

Here we provide detailed information on how to use the tag and point to some technical details.

Use cases

The main use case of PDF thumbnails will be download options for PDF files. When providing such a download option, it's a good idea to show a thumbnail of the PDF you can download. Maybe, make the thumbnail clickable and start the download on click.

How to generate a PDF thumbnail?

Thumbnails for PDFs are generated in a JSP via the tag <cms:pdfthumbnail>. The tag takes the following attributes, specifying the PDF file used for the thumbnail generation and also some attributes of the thumbnail:

Attributes of `<pdf:thumbnail>`

file: VFS URI of the PDF for which the thumbnail should be created.
height (optional, if width is given): Height of the generated thumbnail. Given as integer value, specifying the number of pixels. By default the height is set to -1, which means that it is chosen automatically dependent on the PDF.
width (optional, if height is given): Width of the generated thumbnail. Given as integer value, specifying the number of pixels. By default the width is set to -1, which means that it is chosen automatically dependent on the PDF.
format (optional): Format of the generated thumbnail. Either jpg or png. Default: png.

The tag expands to a link to the thumbnail. Thus, it is typically used as for the value of the src attribute in an <img> tag. Here's a simple example:

<img src='<cms:pdfthumbnail file="/vfs/uri/to/file.pdf" />' alt="..." title="..." />

In the example, a png image will be generated as thumbnail. It's size is determined by the size of the PDF given as input for the generation.

Technical details

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

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.

To the wiki