Directus Dynamic Thumbnailer
You likely have a growing number of images and photos within your Directus File Library — and many of these full-sized images also require one or more thumbnails to represent them throughout your applications. From product images to staff headshots, it’s not uncommon to need hi-res photos for detail pages as well as smaller versions for a listing page. In this article I’ll describe how Directus can make generating on-the-fly thumbnails simple, speedy, and secure.
Configuration
The first step is to set up your thumbnail parameters within the Directus configuration file (/api/configuration.php
). Even though these settings are fairly intuitive, let’s go through them in depth:
404imageLocation
This is the path to the image that will be shown if a requested thumbnail is not available or allowed. There is a default value here, so you only need to update this if you want to use something custom.
supportedThumbnailDimensions
The bread-and-butter of the component, here you choose which global thumbnail sizes will be allowed within this instance of Directus. For safety reasons, none are enabled by default — but you can whitelist any number of thumbnail sizes for your project. The syntax is: 200x300
(pixels of width/height respectively).
supportedQualityTags
You can also enable different compression qualities, each of which determines the JPG quality percentage. By default, four options are available: poor
(25%), good
(50%), better
(75%), and best
(100%).
supportedActions
Since the aspect ratio of full-sized images may differ from the requested thumbnail, two options are available depending on your needs:
contain
: The image will be shrunk to fit completely inside of the thumbnail size bounds. The aspect ratio is maintained and no cropping occurs. For example, a 100x100 thumbnail request of a 600x300 original image would result in 100x50.
resizeCanvas
: If you set this option totrue
, your thumbnail canvas will be set to the configured thumbnail dimension and any blank canvas will be filled with thecanvasBackground
color. See documentation here.position
: Set a point from where the image resizing is going to happen. For example if you are setting the anchor tobottom-left
this side is pinned and the values of width/height will be added or subtracted to the top-right corner of the image. This should remaincenter
for standard usage.resizeRelative
: The values of width or height will be added or subtracted from the current height of the image. This should remainfalse
for standard usage.canvasBackground
: The background color to be used if needed. See color formats.
crop
: The image will be shrunk to fill the thumbnail size bounds — similar to the “cover” CSS attribute. Thumbnails are always the same size, but edges of the original image may be trimmed to fit the new aspect ratio. For example, a 100x100 thumbnail request of a 600x300 original image would result in 100x100.
position
: Set a point from where the image resizing is going to happen. For example if you are setting the anchor tobottom-left
this side is pinned and the excess image data will be cropped from the top-right corner of the image.
Note: The thumbnail image is never stretched or distorted.
Generating Thumbs
Once you have your configuration finished and at least one image in your File Library, you’re ready to go. You can now turn any existing full-sized image into a thumbnail simply by using the following URL convention:
Original Imagehttp://directus.example.com/storage/uploads/original.jpg
Thumbnail Imagehttp://directus.example.com/thumbnail/300/200/crop/best/original.jpg
Now let’s break down the different segments of the URL here:
/thumbnail
: Tells Directus that we’re using the thumbnailer300
: This is the width of the thumbnail200
: This is the height of the thumbnailcrop
: Optional. This is the processing action for aspect ratio. If excluded, the default ofcontain
is used.best
: Optional. This is the processing quality. If excluded, the default ofgood
is used.original.jpg
: This is the file name of the original image you’d like to process into a thumbnail.
Behind the Scenes
All thumbnail URL requests are intercepted by the .htaccess file (or nginx equivalent) which performs the following checks:
File Already Exists
The thumbnail is simply returned.
File Does Not Exist
We check the config to ensure the requested size, action, and quality are all supported. If they are, then the thumbnail is generated and returned.
With this method, you can easily generate any number of thumbnails by referencing them within your application. This avoids the need to manually generate and manage many thumbnails within the CMS, thereby simplifying your asset/content workflow.
At first glance this may seem like something that could be exploited by someone trying to maliciously fill your server’s storage — however it is important to remember that only the thumbnail sizes that you allow can be generated. Therefore you should always appropriately limit your configuration (specifically the supportedThumbnailDimensions
parameter) to avoid any risk of unwanted thumbnails.
As of now our Dynamic Thumbnailer is only available from within the Directus CMS, but we plan on releasing a standalone version (open source) in the near future. We hope you enjoy it — feel free to leave any thoughts in the comments below.
Happy coding!
Your friends at Directus
🐰