The Image Slenderizer, for MODX.
Tired of clients junking up content areas and richtext TVs with enormous images? Simply follow these 3 easy steps!
- Download from the Extras Repository.
- Apply a generous helping of imageSlim™ to the affected area:
[[*content:imageSlim]] - Watch that excess page weight melt away.
imageSlim looks through an HTML fragment for <img> tags, compares each image's natural size to its desired size and if needed calls phpThumbOf to size it down.
- Runs as a snippet or output filter, so it's fully cacheable
- Targets only the areas you tell it to
- Reads and writes inline CSS as well as <img> tag width/height attributes (works fine with both TinyMCE and CKEditor)
- Offers a variety of paramaters for controlling image size: display size, max width/height, scale (for retina images), or any combination
- Fixes stretched images (optional)
- Processes links to offsite images (optional)
- Resaves pngs and gifs larger than a given file size as jpegs (optional)
- Runs any user-specified phpthumb options on all images in its input
- MODX Revolution
- The phpThumbOf extra
- PHP: DOM Extension. imageSlim's installer will tell you whether your server has it. Most do.
- PHP: allow_url_fopen set to On, for imageSlim to be able to process remote images (local images work regardless). The installer will let you know about this one too.
- As an output filter:
[[*content:imageSlim]]or[[*someRichTextTV:imageSlim=`scale=1.5&maxWidth=800&fixAspect=1`]] - As a snippet:
[[imageSlim? &input=`[[*content]]` &remoteImages=`1` &phpthumbof=`fltr[]=gray`]]
- Natural Size – The intrisic dimensions of the image. That is, the pixel dimensions you'd see if you opened up the file in an image editor and checked its size.
- Display Size – The dimensions of the image when it's displayed in a browser. By using the width/height attributes on the <img> tag or inline CSS you can make the display size different from the natural size.
- Aspect Ratio – The ratio of the image's width to its height (i.e. width / height). For example, an image 400px wide and 200px tall has an aspect ratio of 2.
| Property | Description | Default |
|---|---|---|
| &input | The HTML fragment to check Required when calling imageSlim as a snippet |
|
| &maxWidth | Maximum display width of an image. Maximum natural width will be &maxWidth * &scale. See this section below if you're confused. Units: pixels |
|
| &maxHeight | Maximum display height of an image. Maximum natural height will be &maxHeight * &scale. See this section below if you're confused. Units: pixels |
|
| &scale | Allow the natural size of the image to exceed its display size by this factor. Use a value between 1.5 and 2 for retina displays. A scale of 1 will keep the image's natural size the same as its display size. |
1 |
| &convertThreshold | Convert any other image format (png, gif, bmp, etc) with a file size larger than this value to a jpeg, whether or not it's also being sized down. Units: kilobytes Setting this to 0 will convert all lossless formats to jpeg. |
|
| &fixAspect | If an image is being stretched, fix it by keeping its display dimensions and zoom cropping the image to display dimensions * &scale. Stretching occurs when its display aspect ratio is different from its natural aspect ratio (i.e. sombody unchecked 'Constrain proportions'). |
Yes |
| &remoteImages | Allow imageSlim to work with images from other servers. Requires cURL and proper settings for phpthumb_nohotlink_enabled and phpthumb_nohotlink_valid_domains in the MODX system settings (core > phpthumb) Remote images take longer to process than local ones obviously, but imageSlim does cache them locally in assets/components/imageslim/cache/, so it's only a one-time performance hit. |
No |
| &remoteTimeout | Maximum amount of time to allow for a remote image download. Units: seconds |
5 |
| &q | JPEG quality: 1 (worst) – 95 (best) | 75 |
| &phpthumbof | An optional string of parameters to pass to phpThumbOf. Be careful with this one though, since phpThumbOf will be run on every image in the input, not just the oversized ones. Certain parameters–w, h, f, q, zc–may be overridden by imageSlim depending on the image and other settings. |
|
| &debug | Output debug info in an HTML comment. | No |
If you're finding it hard to grasp how natural size, display size, max size and scale all relate to one another, let's do an example. Suppose some blissfully unaware user sticks a giant image into Content. It's got a natural size, say, of 2000px x 1600px. That's way too big for the page, so he's set the dimensions to be 900px x 720px (hey, at least the aspect ratio is the same for both (1.25) and it won't be stretched). Done and dusted. Only why is that image loading so darned slow? Time for a little imageSlim™.
On the front end, the container [[*content]] is going into is semi-fluid, but you know it's a maximum of 800px wide. So we'll set &maxWidth to 800. Then we might as well take advantage of any extra resolution to make sharper images for retina displays; let's set &scale to 1.5. Apply some imageSlim....
I.S. quickly discovers that monstrous image and jumps into action. Had no &maxWidth been set, it'd use the indicated display size of 900 x 720. But in our case that's still too big and imageSlim will change the display width to 800 px (update the inline CSS or width/heigh attributes and everything, nice). Then it calls phpThumbOf to create an image with a natural width of 1200 pixels (800 x 1.5). Since the aspect ratios matched to begin with, the height gets scaled proportionally. The final image has a display size of 800 x 640 and a natural size of 1200 x 960.
- CSS – imageSlim only works with inline CSS. If you're affecting image sizes somewhere else in your CSS, it won't see that. Also if the dimensions in the inline CSS are given in a unit other than pixels (% or em, for instance) it'll ignore those, since it'd be potentially quite involved to translate those values into pixels.
- Resizing – If imageSlim needs to change the display size of an image, it'll use the same method as the image initially had (either inline CSS or <img> tag attributes).
- Vector graphics – imageSlim knows better than to mess with SVG. There's no point!
- Caching - Please don't do this:
[[!imageSlim? &input=`...`]](that is, call it uncached), especially on an area which might have more than a few images. I spent a bunch of time making imageSlim as light and efficient as possible, but phpthumb is a lumbering beast. Though phpthumb does cache its output, so after the first run it only has to regenerate images when the filename, or parameters (or resource) changes, or you go to Site > Clear Cache in the Manager. - Image formats – imageSlim will convert any non-jpegs (gifs, bmps, tiffs, etc) it has to resize into pngs by default.
- Stretched images – if you have &fixAspect on, imageSlim will fix them if it has enough resolution to work with. If the display size exceeds the natural size, it's not going to interpolate images up to fix the aspect ratio. However if the image is being sized down because of &maxWidth or &maxHeight, imageSlim will still try to fix it, even lowering the scale some if it needs to (just not lower than 1).
- Image filenames – phpThumbOf 1.4.0 has some problems with image names. In particular, with Hash Thumbnail Names set to off (the default, in System Settings under phpThumbOf) and multiple images with the same name (in different directories) on the same page getting called with the same phpThumbOf options, phpThumbOf will mistakenly use the first image for all the rest. Also, if you have the exact same image used on different pages with the same phpThumbOf options it'll create separate files for each one, which means more work for the server and messes up caching in visitor's browsers. See my pull request for a simple way to fix both problems.
- Cache – by default phpThumbOf caches images in assets/components/phpthumbof/cache/. Clearing the site cache (via Site > Clear Cache in the Manager) will remove all these images and make phpThumbOf rebuild everthing. If you don't want this to happen, disable the phpThumbOfCacheManager plugin. You can always clean out the cache manually.
- Cache cleanup - phpThumb by default is set to clean up its cache directory: to delete files not accessed within a certain number of days, or delete the least recently used ones if the cache grows beyond a set number of images or megabytes. The only problem is it does this cleanup every time it's called, so if you have a page with 30 images it'll run its cleanup method 30 times while the page is being built, and that can start to affect performance. If you'd like to disable this, go to System > System Settings and under core > phpThumb set Max Cache Age, Max Cache Files, and Max Cache Size (three settings) all to 0. If you do this it'd be a good idea to periodically check the cache and make sure it hasn't grown to enormous size :-)