This recipe is for you if you have a download section for PDF files like flyers or booklets and want to output a nice thumbnail for the download link instead of the filename or a an icon. Using a hook or a custom file method, we can auto-generate preview images either at file upload or on the fly.
For this purpose, we are going to use the ImageMagick command line tool, as it allows us to convert single pages or a complete PDF document to images. And the cool thing is that we can leverage Kirby's ImageMagick class and extend it for our purposes.
The requirements are the same as for using Kirby's
im thumb driver, namely:
- ImageMagick must be installed on your server.
- Calling PHP's
exec()method must not be disabled.
- If the ImageMagic convert binary is not correctly linked, you might have to set the path to the
convertbinary in your config.
Let's start with creating a plugin folder
/site/plugins and add the obligatory
index.php with the Kirby plugin wrapper:
Our next step is to extend Kirby's
ImageMagick class, which is a great starting point for our own. When using the
im driver for thumbs, Kirby calls ImageMagick's
convert binary via PHP's
exec() method. The
convert command to create a preview from a PDF looks like this in its most basic form.
However, without any option settings, the output is usually not very great.
process() function of the
Kirby\Image\Darkroom\ImageMagick class creates this command from the given options and then calls
exec() with this command as parameter. We will modify this method in our new extended class.
Create a new subfolder
classes and inside it a PHP class file named
PdfPreview.php with the folling code:
In this class we bascially modify the
process() method to apply the parameters we need to convert
Back in our
index.php, we load the new class via the
We are all set to use the new class.
In our first example, we create the preview image when a user uploads a PDF through the Panel and store it next to the PDF file in the page folder.
For this purpose, we register a
file.create:after hook within the
hooks extension we added in the
index.php earlier. Within this hook, we will create a new instance of the
PdfPreview class and then call the
process() method to generate the preview image.
Set the options as required, for the available options see the
default() method in the
Since we are not creating thumbs but images in the content folder, you can still call Kirby's thumbnail methods on the preview file, as you can see in the example below.
In your template code, you can now render the preview for the given PDF based on the filename:
Our second option is to create the image "on the fly" when the file method we will create is called. Using a file method is much more versatile, because you can pass options as parameters and you only create the preview files when needed.
preview() file method accepts two parameters: an
$options array and a boolean
$force which determines if the file should be recreated when the method is called.
As options you can pass the same options as before.
The method returns a new
Kirby\Cms\File object, which means that we can call Kirby's thumbnail methods on it as well.
Or by passing parameters to the method:
Since the method returns a
Kirby\Cms\File object, we can also create thumbs:
That's it. Feels free to optimize the above code as required.