Documentation for the Textpattern plugin smd_slimbox by Stef Dawson follows this short message from our sponsor ;-)

smd_slimbox

Features

Generates a list of thumbnails that can be styled any way you like
Flexible way of extracting images from the TXP database; arbitrary inclusion/exclusion of categories or image IDs
Lists of categories and IDs can be pulled from any field in the current article, including custom fields
Supports glz_custom_fields for even greater flexibility (currently requires a small mod to publish.php)
Subcategories: specify a parent and all child categories are automatically included
Show associated image text in various locations around the thumbnails
Paging and multiple galleries per page
Supports Slimbox, Lightbox, Litebox, Moonbox, Thickbox and perhaps some more besides. For a wider range, see smd_gallery

Author

Stef Dawson>. For other software by me, or to make a donation, see the software page.

Originally based on slimbox, a lightweight Lightbox clone by Christophe Beyls. For more info or troubleshooting on the lightbox side of things (as opposed to the thumbnail generation side of things) see Christophe’s forum.

Installation / Uninstallation

Requires smd_lib to be installed and activated.

Download the plugin from either textpattern.org, or the “software page:“http://stefdawson.com/sw, paste the code into the TXP Admin -> Plugins pane, install and enable the plugin.

You will also need a javascript library to perform the lightbox effect, which you must load on your page as per the instructions for that library. Although the examples in this page are for Slimbox, the plugin will work with a number of freely-available javascript libraries — often without modification. Some libraries (e.g. Thickbox) simply require an additional class to be set on the image tags.

Visit the forum thread for more info or to report on the success or otherwise of the plugin.

To remove the plugin, simply delete it from the Admin->Plugins tab and remove your third party libraries.

Usage

The plugin options govern which thumbnails to use and how they are displayed. Once a thumb is clicked, control is handed over to mootools/jQuery/prototype to do the fancy work. Therefore, if you wish to configure the look of the “lightbox” part, you need to edit its javascript and/or associated CSS.

Before you can use smd_slimbox you have to ensure that the page can read the external library files. You do this by putting <script> and <link> tags as usual in your page <head>.

Changes from 0.2x versions

Experienced users of smd_slimbox, please note these important changes to the plugin:

After overwhelming support from the poll, smd_slimbox_inc is now removed. If you use it, a warning will be issued
Accordingly, libcheck has been removed
catlabel has been removed. With more ? and ! article field codes now available, and the ability to combine them (e.g. ?s-?c) you can now perform the same function as catlabel by using category="article-?id"
subcats improved. Now takes an integer “level” that specifies how far down the tree to go. For the same behaviour as before, use subcats="all"
showalt/showcaption/altclass/captionclass/textpos have been removed. Use thumbtext, thumbtextwrap and thumbtextclass instead
orderby is now called sort in line with other TXP tags, and takes a space-delimited direction modifier instead of the old colon delimiter. orderby is still supported for now and will be converted to the new sort tag but will issue a warning in production/debug modes
thumb is now enhanced to allow you to specify whether the full-size image and/or the thumbnail are displayed using the ‘t’ image or not. So you can now swap thumbnail and full-size if you wish, or make them show identical images
trigger added. This defaults to “lightbox-” which is what slimbox uses in the rel attribute of the anchors. Other libraries may use other words to identify themselves, so this allows you to modify the string to suit
delim added. If you don’t like using a comma as a delimiter, change it. Set delim="|" if using checkboxes and multi-selects with glz_custom_fields
navwraptag added so the navigation block can be wrapped in a different tag to each image
linkclass added so you can specify a separate class for the image anchors if you wish

Attributes

Without any options the plugin displays every image in your entire collection and won’t look very pretty (though you can help a bit by starting with the CSS). The following options tame the plugin a little:

Filters

category : a list of image categories. By default the list should be comma-separated but this can be changed with the delim option. This attribute may take any of the special field codes by giving its name after a ? (to include that field) or ! (to exclude that field)
imageid : a list of image IDs. Takes exactly the same syntax as the category attribute
subcats : how far ‘down’ to traverse image sub-categories. Takes an integer value or ‘all’. 0 (the default) means no child categories; 1 uses the main categories and the first level of children; 2 uses the main categories and up to two child sub-categories; and so on
sort : a list of ways to order the results; by default it is by category. Specify the sort order by adding asc or desc to any value, e.g. sort="category, date desc" would sort by category first, then descending date. Takes any of the image field codes plus two special codes:
fixed forces thumbs to be output in the order given in imageid.
random acts slightly differently from the others: if it appears as the first item in the list, random images will be pulled from the database and they will then be sorted according to the options listed after it. However, if it appears anywhere else in the list, any sort items before it will determine the order of data pulled from the database, and the results will then be ordered randomly (in that case, any items listed after random will be ignored, though fixed is still honoured). See example 2 for more

Limits / sizes

limit : the number of image thumbnails to show per page. 0 (or omitted) means essentially unlimited
maxlimit : the absolute maximum number of images to pull from the database. 0 (or omitted) means essentially unlimited
thumbsize : either for special effects, or in order to validate against XHTML, the image thumbnails should have width and height attributes. TXP cannot supply this automatically, but this attribute will.
Simply specify up to two values separated by a comma (you can override this with delim) to define the width and height of your thumbnails (in pixels by default). For example: thumbsize="40, 60" will set 40-pixel x 60-pixel thumbnails. Supplying only one value will set both width and height to the same value. Adding units after each value (“px”, “em”, “%” etc) will use those units instead of the default pixels.
To specify just the width, put the comma in but leave the second parameter empty (e.g. thumbsize="2em,"). Similarly to specify the height only, leave the first value empty by starting with a comma (e.g. thumbsize=",10%")

Grouping / paging images

groupname : when making multiple galleries or for special behaviours, this attribute allows you to logically “group” thumbnails. Once a visitor clicks a thumbnail and control is passed to the javascript code, navigation is via the Next/Prev links. Without supplying a groupname, all lightboxable images from all smd_slimbox tags will be included in the navigation. So if you had 3 slimbox tags on the page, each with 20 images in them, the lightbox would show “Image 1 of 60” and allow you to navigate among all of them.
On article list pages, this is often undesirable so to change this behaviour, give each slimbox tag a unique groupname; that will limit the navigation only to the group of images in that tag. groupname can be any text you like (it defaults to “smd”), or you can supply any of the image field codes to slice and dice the thumbnails any way you choose. See example 4 for more
trigger : in order to indicate to the javascript library that images are to be “lightboxed” the ‘rel’ attriute of anchor images is often used (thickbox is the exception and uses its own class). Since the method of indicating how to lightbox an image varies, this attribute can be tailored to match whichever javascript library you are using (see their instructions). By default, it is set to “lightbox-” which should cover most major lightbox gallery effects. If you wish to remove the rel, empty both trigger and groupname attributes
showpagelinks : displays clickable next/previous links under the thumbnails, allowing you to navigate from page to page and only show limit thumbs per page. It is on (1) by default if limit is greater than 0. Use showpagelinks="0" to turn it off

Adding text to images

imagecaption : the text to display under the large lightbox image. It can be any fixed string (rather pointless!) or a combination of fixed text and image field codes
thumbtext : you can place text around each thumbnail. Like imagecaption, give any fixed text and/or image field codes to add it below every thumbnail (inside tag thumbtextwrap with a class of thumbtextclass). By default, text is placed below the image but can be placed in any of 5 positions, as given in the table below. onchange is very useful for applying headers when the category changes. See example 6. Can take the following options:
- above : above the thumbnail, not clickable
- below : below the thumbnail, not clickable (default)
- before : immediately in front of the thumbnail, clickable as part of the link
- after : immediately following the thumbnail, clickable as part of the link
- onchange : above every thumbnail but only if its contents changes from the image before it
thumbtextwrap : (X)HTML tag to wrap around each thumbtext item. Do not specify the < or > characters. Default: span
thumbtextclass : CSS class to apply to every thumbtext item. Default: empty (i.e. no class)

Tag / class / formatting attributes

wraptag : (X)HTML tag to wrap each ‘cell’ (effectively a thumbnail image) with. Do not specify the < or > characters. For a valid page, the only useful options are “div”, “li” or “p”. Default: empty (i.e. no tag)
cellclass : CSS class for each ‘cell’ that displays a thumbnail. Default: empty (i.e. no class)
linkclass : CSS class for the anchor tag of each image. Default: empty (i.e. no class)
imgclass : CSS class for each img tag. Default: empty (i.e. no class)
navwraptag : when showpagelinks is on, some next/prev links are placed under each gallery to page through limit thumbnails at a time. This attribute specifies the (X)HTML tag to wrap around the whole navigation block. Do not specify the < or > characters. Default: empty (i.e. no tag)
navclass : CSS class for the next/prev container. Default: empty (i.e. no class)
prevlabel : Label for the ‘previous page’ of pictures when using showpagelinks. Default: “Prev”. Customisable in different languages via MLP
nextlabel : Label for the ‘next page’ of pictures when using showpagelinks. Default: “Next”. Customisable in different languages via MLP
prevclass : CSS class for the ‘prev’ link. Default: smd_slimbox_prev
nextclass : CSS class for the ‘next’ link. Default: smd_slimbox_next

Plugin customisation

delim : The delimiter to use between items in lists (category, imageid, thumbtext etc). If using glz_custom_fields — especially with checkboxes or a multi select — you should change delim to a pipe ‘|’ character
paramdelim : by default in the thumbtext attribute, you separate parameters from option names using the colon. In some case you may wish to use the colon in your string of text so you will need to set the delimiter to something else. It can be pretty much any string you like (e.g. paramdelim="[[SQUID"), just make sure it doesn’t appear anywhere else in your text
galleryid : if using showpagelinks, this is the string that is used to differentiate between multiple slimbox galleries on a single page. It allows paging to be controlled on a per-gallery basis, so clicking Next/Prev in one gallery won’t affect the thumbnails in other galleries on the same page. Each gallery on a page must have a unique galleryid in order for paging to work. The good news is you’ll probably never have to use this attribute because it works automatically for you. In the (very) unlikely event it generates two identical strings, you can use this option to override the default behaviour.
It takes either a fixed string (e.g. galleryid="myGallery1"); or a ‘?’ followed by up to two numbers separated by a colon (the colon can be changed with paramdelim). See using galleryid for more
thumb : under normal operation, thumbnails use the ‘t’ image in your images directory and the full size pictures don’t. If you wish to redefine this you may specify up to two values separated by a colon. The first indicates the state of the full size image, and the second is the state of the thumbnail:
- thumb=0:1 — fullsize = regular image : thumbnail = thumb (the default)
- thumb=1:0 — fullsize = thumb : thumbnail = regular image
- thumb=0:0 (or thumb=0) — fullsize = regular image : thumbnail = regular image
- thumb=1:1 (or thumb=1) — fullsize = thumb : thumbnail = thumb

Article field codes

Use these codes to grab items from the currently displayed article and inject them into smd_slimbox tag attributes. All of the tags can be combined with fixed text (e.g. category="mycat-?article_image_?s" might choose images from the category “mycat-12_lion” if the current article was in section ‘lion’ and had an article image of ‘12’). Note that any article or custom fields — including those utilising glz_custom_fields — may contain lists of items.

?c : use the current global (article) category
!c : uses everything except the current global category
?s : use the current TXP section
!s : uses everything except the current section
?t : use the current article’s url-title
!t : uses all url-titles except the current article (probably not much use!)
?id : use the current article’s ID as the name of an image category. Useful to make a per-article image gallery (e.g. category="article-?id")
!id : uses all image IDs except the current article
?fieldname : looks in the given fieldname of the current article. Designed primarily for use with custom fields (e.g. imageid="?custom1"), it can also be any other field from your article. Common fields are ?excerpt @?category1@ ?keywords @?article_image@ or ?authorid.

To negate any category selection, use !category or !field_name. If you list specific image categories (e.g. category="!landscape, !birds") those categories will be excluded. If you specify a field name such as !keywords, the contents of that field will be read and the list of image categories found there will be excluded.

Note that if you specify a field name and that field in the article is empty, the name will be treated as if it was an actual image category. So if you specified category="?keywords" and the ‘keywords’ field in the current article was empty, it would look for an image category named “keywords”.

Also note that, regardless of the order you list them, all ‘positives’ will be processed first, then any exclusions applied.

Image field codes

Like article field codes, these can be specified to grab pieces of information from the current image. Note that the ‘negation’ versions don’t make sense here so the codes are ‘include only’:

?category : image category
?caption : image caption
?alt : image alt text
?name : image (usually file) name
?id : image ID
?date : image upload datestamp
?author : image author (who uploaded it to TXP)
?ext : image file extension
?width : image width in pixels
?height : image height in pixels
?url : the URL of the full-size image — can only be used with imagecaption or thumbtext

For example, to show the alt text under the main image instead of the caption (which it otherwise uses by default) :

imagecaption="?alt"

For the adventurous:

imagecaption="?caption by ?author
     [?ext picture: ?widthx?heightpx]"

That might show a caption such as “Lake Windermere at night by Stef [jpg picture: 800×600px]”.

To put (above each thumbnail) the text “Filed in” and then the category name of the image, followed by its filename in square brackets:

thumbtext="above: Filed in ?category [?name]">

You can combine definitions, each separated by a comma, for example:

thumbtext="above:Filed in ?category [?name (?width x ?height)],
     below:?author"

That would add the category, filename, width and height above the image and the author (the person who uploaded it) below the thumbnail. You can get as creative as you like.

Note that if you want to use a colon in the text itself, you will need to override the default and set it to any string of characters you prefer using the paramdelim option.

Using `galleryid`

Internally, the plugin generates a unique (32-character) string based on the other attributes given. You can use two numbers in galleryid to control which characters from this string to use in your unique code. The first number is the length of the string to generate and the 2nd number is how many characters to skip each time it picks one from the string (wrapping back to the start of the string if it falls off the end).

An example: suppose the tag generated this string internally: 2cb5bbf8b0c2c028d8f234b4bd46fdde. These are the results of various values:

galleryid=	result	remarks
`""` or `"?4:6"`	2fcf	the default
`"?8"`	2cb5bbf8	the first 8 characters
`"?7:3"`	25f0c8f	length 7, choosing every 3rd character
`"?8:7"`	2824f5c8	length 8, choosing every 7th character (wraps)

Examples

Example 1: simple slimbox gallery

Show all images in the landscape category, ten at a time:

<txp:smd_slimbox category="landscape" limit="10" />

Example 2: adding captions

<txp:smd_slimbox category="dogs, birds" limit="9"
     thumbtext="after:?caption" wraptag="li"
     cellclass="cell" />

Show all images in the dogs and birds categories, 9 per page. Add the captions under the thumbnails and make them clickable too. Wrap each image in a li tag and give each a class of ‘cell’ (implies you must manually add a corresponding <ul> tag around the plugin in order to maintain page validity).

If you added sort="date desc, random" to the above tag, you would get the most recent 9 images on the first page, but shown in a random order. The next page would show the next most-recent 9 images, again sorted randomly within themselves.

However, switching the attributes to: sort="random, date desc" would change the output. You would then get 9 random images on the first page, with the most recent ones of the group shown first. Clicking ‘Next’ would show another 9 random images (some may be the same as page 1), again sorted in descending order of date. For this reason (unless you’re simply using the plugin to pretty up a page with random images) if you’re using random as the first argument to sort, you probably want to disable paging by setting showpagelinks="0".

Example 3: using `imageid`

<txp:smd_slimbox imageid="48, 25, 4"
     category="dogs, ?custom1" subcats="all" limit="20"
     prevlabel="Back" sort="name desc, category" />

Show images with IDs 48, 25 and 4 as well as all images in the dogs category and also pull the image category names from the current article’s custom1 field (if custom1 held birds, landscapes you’d get pictures from all three categories and all their sub-categories). The tag also limits the number of thumbs per page to 20, changes the previous page label to “Back” and sorts the images in descending order of name, then category.

Example 4: image negation

<txp:smd_slimbox category="static, cat-?id"
     imageid="!article_image" limit="6" groupname="?c"
     showpagelinks="0" />

If the visitor is currently viewing article ID 67, show all images from the ‘static’ category and the ‘cat-67’ category. If any image in either of those categories is found to have an ID of the article image from the current article, that picture will be ignored. Only show 6 pictures and don’t show the next/prev links on the page.

Also, group the lightbox pictures by image category. This means that if someone clicks on a picture from the “static” category, the Slimbox next/prev links only navigate between those pictures. The user will have to close the lightbox and click a picture in the cat-67 category to show pictures from the other group.

On the surface the groupname option may seem a little superfluous but it can be useful to allow people to only flick through a subset of the pictures on each page, based on their category, file name, author, width/height, alt/caption, even ID if you want them to all be unique entities. You can also use a fixed value read from a field in the current article, e.g. groupname="?custom2". Useful when used in conjunction with sort.

Example 5: combining field variables

<txp:smd_slimbox category="?c, ?custom1, !custom2, !static"
     limit="8" maxlimit="32" />

A bit of a contrived example that shows how crazy you can get: This will show a maximum of 32 images from an image category with the same name as the current global category, plus all images from categories listed in the custom1 field of the current article but excluding images from categories listed in custom2 and also excluding the ‘static’ category. Show 8 image thumbnails at a time (i.e. 4 pages).

Example 6: using `onchange`

<txp:smd_slimbox category="?Photo country" subcats="all"
     thumbtext="onchange: <h4>?category</h4>"
     groupname="?c" thumbtextwrap="" />

A work-saving tag! Pulls out all pictures from the category given in the custom field labelled ‘Photo country’, including any sub-categories. By default it sorts them by category, which is perfect. The clever bit is thumbtext, which tells the plugin to display the category name above the images but only when the category changes. The result is category headings (surrounded by h4 tags, without the default thumbtextwrap span) above each group of images. Note that if you want to include simple HTML tags you can, but they must be encoded with their character code equivalents or TXP gets mad.

The groupname option tells slimbox to only permit stepping through each image in each category. You cannot ‘fall off’ the end of one category into the next when using the Next/Prev links in the lightbox.

If you wanted to show category headings that grouped pictures by author as well you could use:

sort="category, author"
     thumbtext="onchange: &amp;amp;lt;h4&amp;amp;gt;?category
     (by ?author)&amp;amp;lt;/h4&amp;amp;gt;"

Add a little bit of CSS and your single slimbox tag can look like it’s creating multiple galleries, all automatically.

Styling with CSS

There are (deliberately) very few layout attributes for the plugin because pretty much everything can be accessed from CSS to lay your images out however you like them. Want to change the number of images per row? Change the width of the containing <div> and set the width of each thumbnail space to a particular size.

The following logical structure applies:

An optional wraptag and cellclass around each “cell” (i.e. linked thumbnail)
A link element containing the thumbnail’s <img> tag with an optional imgclass
The thumbtext is a with an optional thumbtextclass and can appear above, below or within the link element
The next/prev links are wrapped in the optional navwraptag container and can be given an optional navclass
The next link has a (default) class of “smd_slimbox_next” and prev has “smd_slimbox_prev”. These can be changed or removed if you wish

Using CSS selectors you can access every part of the structure. An example CSS layout is given here to get you started (assumes a wraptag of ‘li’, a containing ‘ul’ around the plugin tag with a class of smd_slimbox and navclass="smd_slimbox_nav"). Paste it into your CSS template and you’re good to go.

.smd_slimbox {
	float:left;
	width:600px;
	margin:1em 0;
	clear:both;
	list-style:none;
}
.smd_slimbox li {
	width:150px;
	height:150px;
	float:left;
	margin:1em auto;
	text-align:center;
}
.smd_slimbox img {
	margin:0 auto;
}
.smd_slimbox span {
	float:left;
	width:140px;
	padding:2px 0 0 5px;
}
.smd_slimbox_nav {
	clear:both;
	width:500px;
	padding:20px;
}
.smd_slimbox_prev {
	float:left;
}
.smd_slimbox_next {
	float:right;
}

Changelog

19 Jan 07 | 0.10 | Initial release
20 Jan 07 | 0.11 | Added !category (negation) support. Thanks Vitruvius
02 Feb 07 | 0.12 | Added imageid, with negation support (thanks wouaren) and textpos option (thanks lee)
06 Feb 07 | 0.20 | js and css can now be loaded elsewhere (thanks jstubbs). Added wraptag and changed defaults to make output less like tag-soup (thanks wouaren)
13 Feb 07 | 0.21 | Added orderby=‘fixed’ (thanks lee) and minor warnfix (thanks benjibot)
04 Mar 07 | 0.22 | Added MLP support, subcategory support and extended the category/imageid options. Now requires smd_lib (included in the zip file for convenience but available separately as well)
04 Mar 07 | 0.23 | Fixed orderby when using random (thanks mrdale) and added ability to override maxlimit
19 Mar 07 | 0.24 | Allowed smd_slimbox_inc to be ignored via libcheck="0" (thanks papuass)
30 Jun 07 | 0.24b | Fixed paging in sub-directory installations (thanks ultramega and Qwest)
28 Jul 07 | 0.25 | Supercharged the groupname option (thanks [Axel])
31 Jul 07 | 0.25a | Maintenance upgrade only. No features, just bundled the latest slimbox/mootools library and fixed the help file
04 Aug 07 | 0.26 | Fixed paging to allow multiple slimbox tags per page to co-exist (thanks wheaticus)
22 Aug 07 | 0.27 | Added thumbnails-as-main-image option (thanks progre55)
30 Aug 07 | 0.28 | Added customisable captions under the main image (thanks Adam_V) and consolidated orderby (internal code)
14 Sep 07 | 0.29 | Added the thumbsize option to set thumbnail dimensions (thanks Simanek)
20 Sep 07 | 0.29a | Fixed undeclared index warnings (thanks Ambitiouslemon)
20 Oct 07 | 0.29b | Fixed the fix that broke in v0.24 (thanks Mr.Smith) and the ‘px’ thumbsize issue (thanks robin746)
03 Nov 07 | 0.210 | Uses smd_lib v0.3 so integer ranges are now only allowed in imageid. Added thumbtext/thumbtextclass/paramdelim. Deprecated showalt/showcaption/altclass/captionclass/textpos
28 Nov 07 | 0.211 | Uses smd_lib v0.31. Fixed some warnings and added onchange heading support (thanks karl.spencer, decoderltd)
20 Jan 08 | 0.212 | Added thumbtextwrap (thanks jodeci) and ?url (thanks markusfalk) ; fixed whitespace around ‘?’ codes
01 Apr 08 | 0.30 | Uses smd_lib. Backported features and refactorisation from smd_gallery ; added trigger, delim, navwraptag and linkclass (thanks marios) ; changed subcats and thumb (thanks fangonk) ; deprecated smd_slimbox_inc ; removed catlabel, libcheck and the deprecated atts from v0.210 ; renamed orderby as sort ; Moonbox, Lightbox, Litebox, Imagebox and Thickbox (jQuery) now supported ; also works with glz_custom_fields (thanks progre55 and gerhard)
09 Jun 08 | 0.31 | Fixed sort when using limit and saved a query (thanks robin746)
19 Dec 08 | 0.32 | Fixed MLP string bug
22 Feb 09 | 0.33 | Allowed rel removal (thanks OMGChris)
09 Feb 11 | 0.34 | Fixed PHP 5.3+ compatibilty (ereg_replace) and thumb attribute (both thanks akurei77)

Credits

This plugin originally plagiarised ideas from Rob Sable’s rss_thumbpop and has been built up from there with suggestions from various TXPers in the community. It also wouldn’t exist without the hard work of Christophe Beyls’ original implementation of Slimbox. Many thanks to all who have helped craft this plugin, and of course to the awesome Textpattern.

Source code

If you’d rather dig for buried treasure, you’ll need to step into the view source page.

Legacy software

If, for some inexplicable reason, you need a legacy version of a plugin, it can probably be found on the plugin archive page.

Experimental software

If you’re feeling brave, or fancy skateboarding into volcanos, you can test out some of my beta code. It can be found on the plugin beta page.

smd_slimbox

smd_slimbox

Features

Author

Installation / Uninstallation

Usage

Changes from 0.2x versions

Attributes

Filters

Limits / sizes

Grouping / paging images

Adding text to images

Tag / class / formatting attributes

Plugin customisation

Article field codes

Image field codes

Using galleryid

Examples

Example 1: simple slimbox gallery

Example 2: adding captions

Example 3: using imageid

Example 4: image negation

Example 5: combining field variables

Example 6: using onchange

Styling with CSS

Changelog

Credits

Source code

Legacy software

Experimental software

Textpattern plugin links

Using `galleryid`

Example 3: using `imageid`

Example 6: using `onchange`