Responsive images in MODX using phpThumbsUp - Darkstar Digital

Responsive images in MODX using phpThumbsUp

20 Mar Responsive images in MODX using phpThumbsUp

Posted at 02:18h in Web Development by

Overview

phpThumbsUp is a MODX addon that manipulates source images to create thumbnails. You can use phpThumbsUp to create thumbnails images for galleries, automatically size user-uploaded images for mobile devices, or automatically add complex image filters to photos. It’s based on the popular phpThumbOf package, with a few subtle differences.

Sections

Download

Additional Resources

Features

Optimized Image Generation (v1.0.0+)

When phpThumbOf or pThumb is used on a page, uncached images are generated when the page is requested. phpThumbsUp, on the other hand, generates an image when the image is requested, or when it is uploaded to the server. This might not sound like much of a difference and it isn’t when all of your images are cached, but when there are lots of images on a page, generating those images on page load can cause a long wait for the client to see content, or even a script timeout on the server.

Assume an uncached page takes 500ms to process the request and generate the page, 10ms to download the page, 10ms to download the CSS / JS resources specified in the <head> area, 10ms to download each image, and 200ms to process each image.

phpThumbOf with 1 image on the page: 730ms total

  1. 500ms + 200ms
  2. 10ms
  3. 10ms
  4. 10ms

phpThumbsUp with 1 image on the page: 730ms total

  1. 500ms
  2. 10ms
  3. 10ms
  4. 10ms + 200ms

phpThumbOf with 5 images on the page: 1570ms total

  1. 500ms + 1000ms
  2. 10ms
  3. 10ms
  4. 50ms

phpThumbsUp with 5 images on the page: 1570ms total

  1. 500ms
  2. 10ms
  3. 10ms
  4. 50ms + 1000ms

In all of the above cases, the user will be staring at a white screen waiting on the page to load until they get to the green section of the diagram. At that point, they will see the page, but the images will still be loading. You can see that with phpThumbOf, the time spent loading the images is front loaded, meaning they will be looking at a white screen waiting on the page to load. With phpThumbsUp, they will see the page sooner, but the images won’t necessarily show up right away.

Security (v1.0.0+)

In some cases, some features of phpThumb can pose a security risk with certain server configurations, especially options that involve files. To prevent any abuse, you can change the phpthumbsup.available_options and phpthumbsup.available_filters to use only the options you need. If none of your thumbs use any options besides height, width, and zoom-crop, for example, you could change your available options to w,h,zc and prevent the use of filters, for example.

In most cases, you should avoid using phpThumbsUp for watermarking images if you are trying to prevent access to the original image, because it’s easy for users to remove that part of the generated URL to see the image without a watermark.

Responsive Images (v1.1.0+)

Starting with version 1.1.0, phpThumbsUp has an optional setting to detect the screen size of the device being used when requesting a thumb and generate smaller images for devices with smaller screen sizes. When the phpthumbsup.responsive setting is set to true, a short piece of Javascript is automatically embedded before the end of the head tag which stores the client’s screen size in a cookie. Every time an image is requested, phpThumbsUp will check the client’s screen size and automatically adjust the width/height of the image based on thresholds defined in the setting phpthumbsup.responsive_threshold.

For example, the default thresholds are 480 and 1024. So if the client is using a phone with a screen size of 320 pixels and an image was requested with a width of 800, phpThumbsUp will adjust the width to 480 (the closest threshold value greater than or equal to screen size).

If you’d like to do this for any image on your site, phpThumbsUp will work with any image even if no options are passed. You could use /phpthumbsup/images/big-picture.jpg, or /phpthumbsup/src/images/big-picture.jpg for example. This would automatically cache your threshold images if a device with a smaller screen downloads the image, but leave the original version untouched (and without a duplicate cache file).

This option is turned off by default, but if you’re using MODX on a responsive site, you can turn this on to help cut down on bandwidth for smaller devices.

Default Settings (v1.1.0+)

In version 1.1.0, we introduced a new setting called phpthumbsup.default which you can use to set default options that are applied to every image generated by phpThumbsUp. Because these options don’t show up in the URL, they can safely ignore the phpthumbsup.available_options and phpthumbsup.available_filters security settings. Any default value is automatically overwritten if a matching setting is found on a specific image.

You can use this setting to make sure every image is cropped from the top with zc=T, or to set the default JPEG quality with q=90, for example. You can also string these together: w=250&h=100&zc=T&q=90.

Other Features

  • If a cache file is older than the source file, a new cache file is automatically created. (v1.0.0+)
  • System setting to clear phpThumbsUp cache when site cache is cleared. (v1.0.0+)
  • Quickly generate thumbnails via URLs (no need for a snippet call on a page) (v1.0.0+)

Minimum Requirements

  • MODX Revolution 2.2
  • PHP 5.3.x
  • ImageMagick 6.x or GD Library

Using phpThumbsUp

phpThumbsUp generates images whenever they are requested from your base URL (default phpthumbsup/) using any of the phpThumb options.

The phpThumbsUp Output Filter

Note: this syntax is exactly the same as phpThumbOf.

If you’d like phpThumbsUp to generate URLs for you, you can use the phpThumbsUp snippet as an output filter like so:

[[*image:phpthumbsup=`w=100&h=100`]]

You can also use the phpThumbsUp snippet traditionally, like so:

[[phpthumbsup? &input=`assets/images/photo.jpg` &options=`w=100&h=100`]]

phpThumbsUp URLs

phpThumbsUp uses a specific url format to know when it needs to generate a thumb and which filters to apply. The base URL (you can customize this in system settings) is the beginning of the url that identifies it as a phpThumbsUp thumbnail. This is followed by the filters and the source image. For example…

/phpthumbsup/w/100/h/100/src/path/to/image.jpg

…generates a 100x100px thumbnail of the image at path/to/image.jpg (relative to your site root). The /src/ indicates the end of the filters, and everything immediately following the /src/ is the path to the source image. See the examples section at the bottom of the page for more.

Generating Thumbs Automatically

Generating a thumbnail when a user requests it for the first time is good, but having that thumbnail already generated before they get there is even better. If you’d like to automatically generate thumbnails when a user uploads a file through the MODX manager, you can do that using the phpthumbsup.auto_create setting.

When a file is uploaded, phpThumbsUp will parse the phpthumbsup.auto_create setting (a colon separated list of phpThumbsUp URLs) and apply the filters defined for the directory the file is being uploaded to. For example, if the setting contained…

/w/100/h/100/src/assets/images/photos:/w/800/h/800/src/assets/images/photos

…then everytime an image is uploaded to the directory assets/images/photos, phpThumbsUp will creates two thumbnails from it (100x100px and 800x800px). Notice that the URLs here DO NOT contain the base URL, but instead begin directly with the filters.

Settings

Key Description Examples
phpthumbsup.core_path The path to the phpThumbsUp component. DO NOT change this unless you have a custom MODX installation. {core_path}components/phpthumbsup/
phpthumbsup.cache_path The path to the cache directory where phpThumbsUp stores image files. If this folder doesn’t exist, phpThumbsUp will try to create it. Make sure it is writeable. {core_path}components/phpthumbsup/cache/
phpthumbsup.base_url The base URL for all images generated by phpThumbsUp. This should never be the same as an alias for one of your resources. thumbs/
phpthumbsup.auto_create If set to one or more colon-separated phpThumbsUp URLs, phpThumbsUp will automatically create thumbnails when an image is uploaded through the MODX manager. /w/100/h/100/zc/1/src/assets/images/photos:/w/350/h/350/zc/1/src/assets/images/photos
phpthumbsup.clear_cache If set to true, the phpThumbsUp image cache will be cleared when you clear your MODX cache. true / false
phpthumbsup.available_options A comma-separated list of options that phpThumbsUp will recognize and process (see the phpThumb readme for a full list of options) w,h,zc
phpthumbsup.available_filters A comma-separated list of filters (fltr[]) that phpThumbsUp will recognize and process (see the phpThumb readme for a full list of filters) bord,gray,sep
phpthumbsup.responsive If enabled, phpThumbsUp will automatically limit image sizes by screen size by the specified thresholds. true / false
phpthumbsup.responsive_threshold A comma-separated list of screen size thresholds for creating responsive images. 480,1024
phpthumbsup.default If set, these settings will apply to all thumbs if not set specifically for that thumb. For example, you could set this to zc=1&fltr[]=gray to get zoom-cropped black and white images by default. w=500&q=90

Examples

Options ThumbsUp
Snippet [[*imageTv:phpthumbsup=`w=120&h=120&zc=1`]]
phpThumbsUp URL /phpthumbsup/w/120/h/120/zc/1/src/images/bgs/conference.jpg
Description Creates a 120x120px thumbnail zoom cropped to the center.
Snippet [[*imageTv:phpthumbsup=`w=120&h=120&zc=1&fltr[]=gray`]]
phpThumbsUp URL /phpthumbsup/w/120/h/120/zc/1/fltr[]/gray/src/images/bgs/conference.jpg
Description Converts the image to gray scale.
Snippet [[*imageTv:phpthumbsup=`w=120&h=120&zc=1&fltr[]=gray&fltr[]=clr|35|990033`]]
phpThumbsUp URL /phpthumbsup/w/120/h/120/zc/1/fltr[]/gray/fltr[]/clr|35|990033/src/images/bgs/conference.jpg
Description Converts the image to gray scale then puts a transparent red overlay on top of it.
Snippet [[*imageTv:phpthumbsup=`w=120&h=120&zc=1&fltr[]=blur|10`]]
phpThumbsUp URL /phpthumbsup/w/120/h/120/zc/1/fltr[]/blur|10/src/images/bgs/conference.jpg
Description Adds a blur effect to the thumbnail.
Snippet [[*imageTv:phpthumbsup=`w=120&h=120&zc=1&f=png&fltr[]=ric|20|20`]]
phpThumbsUp URL /phpthumbsup/w/120/h/120/zc/1/f/png/fltr[]/ric|20|20/src/images/bgs/conference.jpg
Description Adds rounded corners to the thumbnail and converts it to PNG format.
Snippet [[*imageTv:phpthumbsup=`w=120&h=120&zc=1&fltr[]=bord|5|0|0|FFFFFF&ra=-15`]]
phpThumbsUp URL /phpthumbsup/w/120/h/120/zc/1/fltr[]/bord|5|0|0|FFFFFF/ra/-15/src/images/bgs/conference.jpg
Description Adds a white border to the thumbnail and rotates it negative 15 degrees.

Change Log

phpThumbsUp 1.1.1

  • Added a parse_path method for converting {core_path}, {assets_path} or {base_path} in setting values to actual paths (fixes caching issue).

phpThumbsUp 1.1.0

  • Added screen width threshold for responsive design.
  • Added “default” setting for phpThumbsUp parameters that should apply to all images by default
  • Changed phpThumbsUp to work with only a src and no options

phpThumbsUp 1.0.1

  • Added server response headers for 304 and browser caching
  • Fixed issue with spaces in image path
  • Changed cache directory to reside in MODX cache directory
  • Changed phpthumbsup.base_url settings to include {base_url} at the beginning

phpThumbsUp 1.0.0

  • Initial commit