Documentation for the Textpattern plugin smd_thumbnail by Stef Dawson follows this short message from our sponsor ;-)
If you like my code and it makes your site better, feel free to show your appreciation with something from my UK Amazon wish list (or US) or donate to the Stef Dawson community coding pot by following the Donate button below to PayPal. Thanks!
- Assign any number of thumbnails to Txp’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 Txp’s thumbs if you wish
- Conditional thumbnail check available
Installation / upgrading / uninstallation
Requires Txp 4.5.0+
Download the plugin from either textpattern.org, or the software page, paste the code into the Txp Admin -> Plugins pane, install and enable the plugin. Visit the forum thread for more info or to report on the success or otherwise of the plugin.
When upgrading froim v0.1x to v0.20, your preferences for Keep Txp thumbnails in sync with default profile will be removed. Please visit the Tools/Prefs area to reinstate the behaviour you desire.
To uninstall, delete from the Admin -> Plugins page.
Usage — admin side
Visit the Content->Images tab. Above the list of images is an area labelled Thumbnail Profiles. Click it to reveal the control panel. You can toggle this panel on and off 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 dimension. You are limited to usual non-weird characters in the name
- 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 jpg or png(24) 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 heading row to toggle the status of all profiles. Note that this setting 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 Txp’s thumbs is on, it will also become Txp’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, hit the [Delete] button and confirm. All thumbnails associated with that profile will be deleted.
At this point, no thumbnails have been created. Let’s rectify that.
Pick one of your images and click to edit it.
Beneath the main picture you will see an area labelled Thumbnails. You can toggle this panel on and off by clicking the heading.
Inside the panel 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 hit Delete to remove the selected thumbnail(s).
Once created, the thumbnails appear in the panel; remember they can be tucked away if you don’t want to look at them.
If you select All sizes and hit Create, you will get one thumbnail for each active profile. Similarly, if you hit 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.
- 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 Txp’s multi-edit tool to delete images, all corresponding thumbnails for the selected images (including inactive ones) will be removed.
If you prefer to make your own thumbs 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… / Choose…) 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:
- the thumbnail must be of the same file type as the original image or the upload will be ignored
- you can click a highlighted image to deselect it
- 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 ‘Tools / Prefs’ if you have sufficient rights) in the top-right hand corner of the smd_thumbnail control panel. From there you will see an area that allows you to create thumbnails for:
- Only the selected images (the checkboxes next to each image)
- All images of a particular category
- All images uploaded by a particular user
- 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), hit Create. Once you confirm your action, the plugin will go away and 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.
If you have sufficient privileges, in the lower portion of the Tools 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 (Txp) thumbnail. If you have elected not to have Txp thumbnails created then it’ll probably not work very well :-)
This preference applies:
- when you use any of the batch tools to mass-produce smd_thumbnails
- if you upload a new image
- if you reupload a main image and Recreate thumbnails on re-upload of main image is checked
Keep Txp thumbnails in sync with default profile
(This option only appears if you have set a profile as default)
Ordinarily, smd_thumbnail works independently of Txp’s thumbs. 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 Txp’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 Txp 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 Txp’s thumbnails. This has a few effects worth highlighting.
When the Creation checkbox is ticked:
- if you batch create thumbs, upload a new image, or replace an existing image, a new Txp thumbnail will be created at the default size. Any existing thumbs will be overwritten
- if you change default profile, any Txp 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:
- if you delete a single thumb that corresponds to the default profile, both the profile thumb and Txp’s thumb will be deleted
- if you delete an entire profile, all its thumbnails and all Txp’s thumbs will be removed
- if you have no default profile, the checkboxes disappear and the settings have no effect. Choose a default profile to reinstate the behaviour
- 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: Txp thumbnails are NOT covered by this option — they are governed by the Keep Txp thumbs in sync’s ‘Creation’ checkbox. Thus, if you upload a replacement image and the ‘Creation’ checkbox is on, you will replace Txp’s thumb regardless of the setting of the Recreate thumbnails… option.
A direct replacement for the built in txp:thumbnail tag with exactly the same functionality and attributes apart from these exceptions:
- type : use this attribute to display thumbnails of the given profile name. e.g.
type="large". If you do not specify this attribute, the default profile will be used. If there is no default profile you’ll see warning messages
- class : 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
- align : this attribute has been removed
- add_stamp : 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 thumbs properly thus increasing bandwidth usage. Default: 0
- force_size : 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
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
height. Comma-separate as required. Default: unset
- display : 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
- form : you can construct your own
<img>tags using the given form. If not specified, you may use the tag as a container.
The tag works inside
<txp:images> or can be used standalone by specifying the
name attribute. If using it as a container or with the
form attribute you display the various pieces of thumbnail information using the
Display various information from the current
<txp:smd_thumbnail> tag (in either its form or container). Attributes:
- item : list of things you wish to display. Choose from:
url: full image URL of the thumbnail
type: thumbnail profile name
name: image name
id: thumbnail ID
ext: thumbnail file extension
category: image category name
category_title: image category title
alt: image alt text
title: image title / caption
author: image author
class: class applied to thumbnail (if not supplied, is same as type)
date: raw datestamp of when the image was uploaded
w: thumbnail width (pixels)
h: thumbnail height (pixels)
html_w: HTML-formatted width attribute
html_h: HTML-formatted height attribute
- wraptag : HTML tag, without angle brackets, to wrap all the items with. e.g.
- class : CSS class name to apply to the wraptag
- break : HTML tag, without angle brackets, to wrap each item with. e.g.
A direct replacement for the built in
<txp:if_thumbnail /> tag with exactly the same functionality. It has one attribute:
- 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
How it works
For reference, when you create a profile a directory is created with that name inside your Txp
images folder. Inside this folder you will find images of the format
ext match the corresponding image IDs in the Txp 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.
Author / credits
Written by Stef Dawson. Many thanks to the beta test crew who offered feature and workflow advice, especially thebombsite, jakob, jstubbs and maniqui.
- 06 Aug 2010 | 0.10beta | Initial beta release
- 04 Oct 2010 | 0.10 | Official public release
- 09 Nov 2010 | 0.11 | Added
add_stamp(both thanks zero) ; removed unnecessary DB call
- 10 Nov 2010 | 0.12 | Added ability to sync default profile thumbs with the corresponding Txp thumbnails (thanks zero)
- 10 Nov 2010 | 0.13 | Added confirmation on Create all ; relabelled upload box (thank uli) ; tamed styles ; silenced chmod warnings (thanks zero)
- 21 Nov 2010 | 0.14 | Permitted thumbs to be larger than the original images (thanks maniqui) ; fixed callbacks for image uploading and deleting
- 26 Jan 2011 | 0.20 | Tools / prefs separated from profile list ; permitted batch creation via 1) selected images 2) category 3) author (thanks jpdupont) ; added smd_thumb_auto_replace option and altered default behaviour (thanks maniqui) ; fixed Txp thumbnail creation on thumbnail replace and made prefs global — and only available to site admins (all thanks jstubbs) ; fixed New Profile button wrapping (thanks jpdupont)
- 12 May 2011 | 0.21 | Added
smd_thumb_get_profiles()for other plugins to find which profiles are available
- 12 Oct 2011 | 0.22 | Added
displayattribute ; added ‘create from’ preference (thanks the blue dragon/maniqui) ; fixed plugin for dashboard use ; fixed jQuery attr/prop in prefs ; fixed Txp menu interference (thanks maniqui)
- 14 Jan 2013 | 0.30 | For Txp 4.5.0 ; added mem_moderation_image support ; smd_thumbnail tag has form/container support ; added smd_thumbnail_info tag ; fixed image <-> select list interaction (damn you attr/prop!) ; added better tooltip on thumb hover ; fixed invalid markup ; added width & height attributes (thanks jstubbs)
If you’d rather frolic in the raw code halls, you’ll need to step into the view source page.
If, for some inexplicable reason, you need an old version of a plugin, it can probably be found on the plugin archive page.
If you’re feeling brave, or fancy chucking your keys in the bowl, you can test out some of my beta code. It can be found on the plugin beta page.