smd_thumbnail

Download | Packagist

If you’re bored of one Textpattern thumbnail per image and don’t fancy using an auto-resizing script or relying on the browser to stretch your thumbnails, smd_thumbnail could be the answer! It allows you to create profiles for as many Textpattern thumbnail sizes as you like and will automatically create physical thumbnails at those dimensions for any/all of your images.

Please report bugs and problems with this plugin at the GitHub project’s issues page.

Features

• Assign any number of thumbnails to Textpattern’s images.
• Batch assign thumbnails to existing images.
• Set one thumbnail size as default.
• Display any of the thumbnail sizes on your site.
• Keep thumbs in sync with Textpattern’s thumbs if you wish.
• Conditional thumbnail check available.

Installing

Requires Textpattern 4.7.0+

Download the plugin from either GitHub, or the software page, paste the code into the Plugins administration panel, install and enable the plugin. Visit the forum thread for more info or to report on the success or otherwise of the plugin.

Note: When upgrading from v0.1x to v0.20, your preferences for ‘Keep Textpattern thumbnails in sync with default profile’ will be removed. Please visit the ‘Setup’ area to reinstate the behaviour you desire.

Alternatively, this plugin can be installed using Composer:

$ composer require bloke/smd_thumbnail:*

Usage

Visit the Images panel. Above the list of images is an area labelled Thumbnail profiles. Click it to reveal the control panel. You can toggle this panel open and closed by clicking the heading.

You must define at least one profile to begin with, so click the New profile button. This will reveal edit boxes where you can enter:

• Name: some descriptive name for this thumbnail profile. You are limited to usual non-weird characters in the name.
• Description: a brief summary of this thumbnail profile, to jog your memory or inform other users of its purpose.
• Width: thumbnail width, in pixels. If left blank (or set to 0) and height is specified, the width will be computed in proportion to the height.
• Height: thumbnail height, in pixels. If left blank (or set to 0) and width is specified, the height will be computed in proportion to the width.
• Quality (%): The quality of the resulting thumbnail. Generally only of use for JPEG or 24-bit PNG images. The higher the value the better the quality and the bigger the file size. Default: 75.
• Crop: whether to crop the image when the thumbnail is created, or scale it to fit.
• Sharpen: whether to apply a sharpening filter to the thumbnail when it is created. Useful for very small images.
• Active: Enable/disable this thumbnail size so it will/won’t be automatically generated when the next image is uploaded. Click the checkbox to instantly switch the profile on/off. Click the ‘Active’ word in the column heading to toggle the status of all active profiles. Note that the active state governs how the All sizes dropdown entry interacts with the Create and Delete buttons.
• Default: set this thumbnail profile as the default. The default image will be displayed in the ‘Images’ list and will also be used as the default size to be displayed using <txp:smd_thumbnail/>. If the option to sync with Textpattern’s thumbs is on, it will also become Textpattern’s standard (built-in) thumbnail size from this point forward.

Once you’ve configured your profile, click ‘Save’ to store it. You can always edit it again by clicking its name. Go ahead and create some more profiles for thumbnails of different sizes/parameters. If you wish to delete a profile, click the ‘x’ button and confirm. All thumbnails associated with that profile will be deleted.

At this point, no thumbnails have been created. Let’s rectify that…

Creating thumbnails

Pick one of your images and click to edit it. Beneath the main picture you will see an area labelled ‘Create thumbnail’.

Inside this area is a simple select list containing one entry for each thumbnail profile you have configured, plus the special entry ‘All sizes’. You can select one of these entries and click ‘Create’ to create thumbnail(s) in the selected size or click ‘Delete’ to remove the selected thumbnail(s).

Once created, the thumbnails appear in the panel.

If you select ‘All sizes’ and click ‘Create’, you will get one thumbnail for each active profile. Similarly, if you click ‘Delete’ any thumbnails stored against an active profile for the current image will be removed. By toggling certain thumbnail profiles on/off you can control which ones are created or deleted – by default:

• When you upload a new image, thumbnails will be automatically created for any active profiles.
• When you replace an existing image, thumbnails will only be automatically created for active profiles if thumbs do not already exist. This option can be altered with the prefs.

Note that if you use Textpattern’s multi-edit tool to delete images, all corresponding thumbnails for the selected images (including inactive ones) will be removed.

Custom thumbnails

If you prefer to make your own thumbmails in an external program, you can still set up the profiles as normal but instead of clicking ‘Create’ in the ‘Image edit’ screen, you can pick a profile size from the dropdown and use the file picker facility ‘Browse…’ to select a thumbnail from your hard drive. When you click ‘Upload’ the image will be inserted against the selected profile.

At any time you can click one of the thumbnails (or select a size from the dropdown) and choose for another image to replace the existing thumbnail – even ones that have been auto-created. Some things to note about this feature:

1. The thumbnail must be of the same file type as the original image or the upload will be ignored.
2. You can click a highlighted image to deselect it.
3. You cannot ‘Browse…’ for an image (the file upload box is greyed out) unless you have chosen one profile.

Batch thumbnail creation

You can also create thumbnails en-masse. Click the ‘Tools’ button (labelled ‘Setup’ if you have sufficient rights) in the right hand corner of the smd_thumbnail control panel. From there you will see an area that allows you to create thumbnails for:

1. Only the selected images (the checkboxes next to each image).
2. All images of a particular category.
3. All images uploaded by a particular user.
4. All images.

After selecting the desired option (and if you choose category or author, select one of the entries from the secondary list that apears), click ‘Create’. Once you confirm your action, the plugin will create thumbnails for every active profile for all images that match your criteria. This is a quick way to generate thumbs for your existing images. Note that if you choose the first (empty) category entry, then all images that have not been assigned a category are manipulated.

Because of the nature of this tool – especially with large image pools – the process is done as a background task via AJAX. After clicking the ‘Create’ button (and confirming you are sure) a counter will appear in the top-right of the prefs panel showing how many images it has processed out of the total number of images in the set. When it’s done, if you then refresh your ‘Images’ tab (e.g. click to the ‘Profiles’ pane) you will see your chosen default thumbnails in the list – assuming you’ve set one as default.

Preferences

If you have sufficient privileges, in the lower portion of the ‘Setup’ panel are some options that govern how thumbnails are created for all users. There is no ‘Save’ action here: the checkmarks are stored in real-time and always reflect the current state.

Create smd_thumbnails from

Governs whether the smd_thumbnails are created from the full size image or its (Textpattern) thumbnail. If you have elected not to have Textpattern thumbnails created then it’ll probably not work very well! This preference applies:

1. When you use any of the batch tools to mass-produce smd_thumbnails.
2. If you upload a new image.
3. If you reupload a main image and ‘Recreate thumbnails on re-upload of main image’ is checked.

Keep Textpattern thumbnails in sync with default profile

This option only appears if you have set a profile as default.

Ordinarily, smd_thumbnail works independently of Textpattern’s thumbnails. If you disable the plugin you’ll see that everything goes back to how it was before you installed it. This is great because your hard-graft isn’t lost if you have uploaded your own thumbs. But, if you start creating thumbs with the plugin you will notice that Textpattern’s built in tags such as <txp:article_image thumbnail="1" /> and <txp:thumbnail /> won’t work for newer thumbnails. This might be confusing so you can opt to have smd_thumbnail update your Textpattern thumbnails at the same time.

By ticking either of the checkboxes, the plugin will track any changes to the default profile and mimic them with Textpattern’s thumbnails. This has a few effects worth highlighting…

When the ‘Creation’ checkbox is ticked:

1. If you batch create thumbs, upload a new image, or replace an existing image, a new Textpattern thumbnail will be created at the default size. Any existing thumbs will be overwritten.
2. If you change default profile, any Textpattern thumbnails that have been created will remain at the previous size. Only when you start creating, uploading or replacing images will the new thumbnail sizes be created.

When the ‘Deletion’ checkbox is ticked:

1. If you delete a single thumb that corresponds to the default profile, both the profile thumb and Textpattern’s thumbmail will be deleted.
2. If you delete an entire profile, all its thumbnails and all Textpattern’s thumbnails will be removed.

Further:

1. If you have no default profile, the checkboxes disappear and the settings have no effect. Choose a default profile to reinstate the behaviour.
2. If you deactivate the default profile the checkboxes have no effect unless you delete the profile (since you’re deleting it, its status is ‘lost’ and therefore the checkboxes function as normal). If there’s any doubt, uncheck the ‘Deletion’ checkbox first!

Recreate thumbnails on re-upload of main image

When this checkbox is cleared and you replace a main image (from the ‘Image edit’ screen) any thumbnails that have already been assigned to the image are left as they are – only missing thumbnails will be created from the main image. Conversely, if you set this checkbox, when you upload the replacement image ALL smd_thumbnails for active profiles will be (re)created from the main image.

Note one important exception: Textpattern thumbnails are NOT covered by this option – they are governed by the ‘Keep Textpattern thumbs in sync’ ‘Creation’ checkbox. Thus, if you upload a replacement image and the ‘Creation’ checkbox is on, you will replace Textpattern’s thumbnail regardless of the setting of the ‘Recreate thumbnails…’ option.

Tags

smd_thumbnail tag

<txp:smd_thumbnail />

A direct replacement for the built in txp:thumbnail tag with exactly the same functionality and attributes apart from the additional attributes listed below.

Attributes (in addition to standard txp:thumbnail tag attributes)

; add_stamp="boolean"
: Adds the image file modification time to the end of the thumbnail’s URL. Use add_stamp="1" to switch this feature on. This helps prevent stale images, but may prevent browsers from cacheing the thumbnails properly, thus increasing bandwidth usage.
: Default: 0.
; break="tag"
: HTML tag to apply between each thumbnail when iterating over them.
: Default: unset.
; breakclass="class name"
: HTML class to apply to the break> tag.
: Default: unset.
; class="class name"
: HTML class to apply to the <img> attribute value.
: If omitted, the name of the profile will be used as a class name for the <img> tag.
: If you specify a wraptag and omit the class, the profile name will be used as a class on both the container and the <img> tag.
; force_size="value"
: Usually when you set one or other width/height to 0 in a profile, the browser scales the missing dimension automatically. It does this by omitting the width= or height= attribute in the img tag. This may cause visual artefacts as the page is rendered and the browser calculates the sizes. If you wish the plugin to add the actual dimension to the <img> tag (the size at the time the thumbnail was created), tell the plugin with this attribute. Choose one or both of width or height. Comma-separate as required.
: Default: unset.
; form="form name"
: You can construct your own <img> tags using the given form. If not specified, you may use the tag as a container.
; format="value"
: By default, this tag outputs a full <img> tag. If you just require the image URL so you can make your own image tags, set format="url".
: Default: thumbnail.
; quiet="boolean"
: Use quiet=“1” to suppress warnings about missing images.
: Default: 0.
; size="ratio"
: Only consider images of a particular aspect ratio/size. Choose from: portrait, landscape, or square. Or specify your own aspect ratio width:height, e.g. 16:9 or 4:3, or numeric ratio such as size="1.33" or size="0.8". You may also specify just a width or height, e.g. @size="300:" (only consider images that are exactly 300px wide) or size=":800" (only consider images that are exactly 800px tall).
: Default: unset.
; sort="col dir, col dir, ..."
: Order the images by the given columns and sort direction.
: Default: width DESC, height DESC.
; type="value"
: Use this attribute to display thumbnails of the given profile name (e.g., type="large"). You may comma-separate multiple profile names to iterate over them.
: type=“SMD_ALL” will iterate over all defined profiles.
: type=“SMD_ACTIVE” will iterate over all active profiles.
: If you do not specify this attribute, the default profile will be used. If there is no default profile you’ll see warning messages.

The tag works inside <txp:images> or can be used standalone by specifying the id or name attribute. If using it as a container or with the form attribute you display the various pieces of thumbnail information using the <txp:smd_thumbnail_info> tag.

Examples

Example 1

<txp:images>
    <txp:smd_thumbnail type="big-size" />
</txp:images>

Show all images that have been generated with the ‘big-size’ smd_thumbnail profile.

Example 2: responsive images

See responsive images post in the Textpattern forum.

smd_thumbnail_info tag

<txp:smd_thumbnail_info />

Display various information from the current <txp:smd_thumbnail> tag (in either its form or container).

Attributes

• class="class name" HTML class to apply to the wraptag attribute value.
• break="value" Where value is an HTML element, specified without brackets (e.g., break="li") to separate list items.
• item="item value" List of things you wish to display. Choose from:
  • alt: image alt text.
  • author: image author.
  • category: image category name.
  • category_title: image category title.
  • class: class applied to thumbnail (if not supplied, is same as type).
  • date : raw datestamp of when the image was uploaded.
  • ext: thumbnail file extension.
  • h: thumbnail height (pixels). Note the resulting value is taken directly from your profile setup, so if you have the profile height set to 0 (variable height) then this value will be incorrectly displayed as 0.
  • html_h: HTML-formatted height attribute.
  • html_w: HTML-formatted width attribute.
  • id: thumbnail ID.
  • name: image name.
  • title: image title/caption.
  • type: thumbnail profile name.
  • url: full image URL of the thumbnail.
  • w: thumbnail width (pixels). Note the resulting value is taken directly from your profile setup, so if you have the profile width set to 0 (variable width) then this value will be incorrectly displayed as 0.
• wraptag="element" HTML element to wrap (markup) list block, specified without brackets (e.g., wraptag="ul").
• escape="transform" to apply core escape transforms such as trim, tidy, html, textile, etc to the item.

Example

<txp:images>
    <txp:smd_thumbnail type="big-size">
        <meta itemprop="image" content="<txp:smd_thumbnail_info item="url" />">
        <meta itemprop="width" content="<txp:smd_thumbnail_info item="w" />">
        <meta itemprop="height" content="<txp:smd_thumbnail_info item="h" />">
    </txp:smd_thumbnail>
</txp:images>

smd_if_thumbnail tag

<txp:smd_if_thumbnail>

A direct replacement for the built in <txp:if_thumbnail /> tag with exactly the same functionality.

Attributes

• type: use this attribute to check for thumbnails of the given profile name (e.g., type="Medium"). If you do not specify this attribute, the default profile will be tested. If there is no default profile the tag will always render the <txp:else /> portion.

Example

<txp:images>
    <txp:smd_if_thumbnail type="640w">
        <img alt="<txp:image_info type='alt' />"
            src="<txp:smd_thumbnail type='640w' format='url' />"
            srcset="<txp:image_url link='0' /> 2x, <txp:smd_thumbnail type='640w' format='url' /> 1x">
    <txp:else />
        <img alt="<txp:image_info type='alt' />" src="<txp:image_url link='0' />">
    </txp:smd_if_thumbnail>
</txp:images>

How it works

For reference, when you create a profile a directory is created with that name inside your Textpattern images folder. Inside this folder you will find images of the format id.ext: where id and ext match the corresponding image IDs in the Textpattern database. That’s pretty much it!

You can delete thumbnail files manually from any of these directories and the plugin will figure everything out. But it’s probably not advisable to delete the directories themselves – use the ‘Delete’ buttons in the control panel for that.

History

Please see the changelog on GitHub.

Authors/credits

Written by Stef Dawson. Many thanks to all additional contributors. Special thanks also to the beta test crew who offered feature and workflow advice, especially thebombsite, jakob, jstubbs and maniqui.