This article was written for a legacy version of Directus. Only reference this information if you are using Directus 6 and can not upgrade to version 7.

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

Poor, Good, Better, and Best quality examples

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 to true, your thumbnail canvas will be set to the configured thumbnail dimension and any blank canvas will be filled with the canvasBackground 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 to bottom-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 remain center for standard usage.
• resizeRelative: The values of width or height will be added or subtracted from the current height of the image. This should remain false 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 to bottom-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 Image
http://directus.example.com/storage/uploads/original.jpg

The original image (1,800 × 1,200)

Thumbnail Image
http://directus.example.com/thumbnail/300/200/crop/best/original.jpg

Thumbnail (300 × 200)

Now let’s break down the different segments of the URL here:

• /thumbnail: Tells Directus that we’re using the thumbnailer
• 300: This is the width of the thumbnail
• 200: This is the height of the thumbnail
• crop: Optional. This is the processing action for aspect ratio. If excluded, the default of contain is used.
• best: Optional. This is the processing quality. If excluded, the default of good 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

🐰