For more information on usage, bugs, features etc, please visit the forum thread. For other software by me, or to make a donation, see the software page.
Requires smd_lib v0.31 to be installed and activated.
Yeah, yeah another lightbox-style image gallery! But this time using Christophe Beyl's ultra-lightweight Slimbox (diet coke version of lightbox) and mootools.
Features:
Ensure that the contents of the js folder (mootools.js and slimbox.js) and the css folder (slimbox.css and 4 images) are uploaded to your server. You can put the directories in the textpattern root folder or somewhere else of your choice. It doesn't really matter where you put them, you just have to tell the plugin where it is.
Then make sure that smd_lib is installed and activated. Finally, install the smd_slimbox plugin and activate it.
Once installed, this plugin adds two tags. The first (smd_slimbox_inc) usually goes in the <head> section of your page and loads the required libraries – the js/css files you just uploaded to your server. The second (smd_slimbox) is the actual plugin that displays your image gallery (or galleries if you're feeling adventurous).
A quick word about how it all works: the plugin options govern which thumbnails to use and how they are displayed only. Once the thumbs are clicked, control is handed over to slimbox and mootools to do the fancy work. Therefore, if you wish to configure the look of the "lightbox" part, you need to edit slimbox.js and/or slimbox.css. More info can be found on Christophe Beyl's page.
Also, if you already use mootools for your page you don't need to upload it again. Just make sure the version you use has the core functionality plus the "fx" and "window" modules listed on Christophe's page. Be careful if you use other javascript libraries such as jQuery because they may clash. See how to use jQuery with other libraries for an example of integrating the two.
Before you can use smd_slimbox you have to ensure that the plugin knows where to find the external include/library files. You do this with smd_slimbox_inc. Note that the plugin does not check that you have given it correct file locations to valid, readable files so if you have problems making it work, check the source code of the page to see if you're loading what you think you're loading from the correct places!
jsdir / cssdirAssuming you've put the js and css directories in your textpattern root (i.e. at the same level as the images, files and textpattern directories), add this somewhere in the <head> of the page that you want your gallery:
<txp:smd_slimbox_inc jsdir="/js" cssdir="/css" />
If you have the libraries elsewhere, change where the plugin looks for the libraries by adjusting the two options. Pay attention to the forward slash at the start; without it, the script will look for the files relative to the current article/section which may (or may not) be what you want.
scriptsIf you want more control over the file locations, you have two more options available. The first is scripts. This takes a comma-separated list of up to 3 arguments in this order:
The order is important: mootools must appear on the page before slimbox.js! So if you have your scripts in different directories or have renamed the files, you could do this instead of the cssdir and jsdir options:
<txp:smd_slimbox_inc scripts="/scripts/mootools.js,
/sbox/slimbox.js, /sbcss/slimbox.css" />
The three options can either be direct file paths, as in the example above, or full XHTML tags including <script> or <link>tags. You can mix and match the options in any way you like, as long as the total number of scripts you tell the tag to load doesn't exceed 3. So an equivalent to the above is:
<txp:smd_slimbox_inc scripts="/scripts/mootools.js,
/sbox/slimbox.js" cssdir="/sbcss" />
skipIf you wish to load some or all of the scripts "outside" the smd_slimbox_inc function you can use the skip option to tell it how many you have loaded. If, for example, you have stm_javascript installed you could do:
<txp:js n="mootools" />
<txp:smd_slimbox_inc skip="1" scripts=", /sbox/slimbox.js,
/sbcss/slimbox.css" />
Note the empty option at the start before the comma. You don't have to do that (because skip will jump over it for you) but if you like to make it obvious, it does no harm. Using the sole option skip="3" means "I've loaded them all myself, I know what I'm doing" :-)
One more thing with this feature: TXP does not allow you to directly embed other tags as attributes (so unfortunately scripts="<txp:css />" fails). If you absolutely must do it, you can cheat (see Wet's excellent post on tags in tags for more details) by dropping into PHP and doing something like the following:
<txp:smd_slimbox_inc cssdir="/css" scripts="/scripts/mootools.js,
<txp:php>echo js(array( 'n' => 'slimbox'));</txp:php> />
If you supply thumbnails in RSS feeds or just don't want to use smd_slimbox_inc, you can turn it off by using the libcheck="0" to the smd_slimbox tag.
Once the scripts are loaded, you are free to use <txp:smd_slimbox /> to display an image gallery. Without any options it displays every image in your entire collection and won't look very pretty (though you can help a bit by starting with the example CSS given later). The following options tame the plugin a little:
categoryA comma-separated list of image category names to show.
?c!c?s!s?t!t?idID. Useful to make a per-article image gallery!id?fieldname?custom1), it could also be any other field (or fields) from your articles (e.g. ?excerpt or ?category1 or ?keywords or ?authorid, etc). Be warned: if you use ?body or something equally outrageous, chances are the plugin will explodeTo negate any category selection, use !category or !field_name. If you list specific image categories (e.g. !landscape, !birds) those categories will be excluded. If you specify a field name such as !keywords or !custom1, 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 ?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.
subcatsAutomatically includes all sub-categories of the chosen image categories.
1catlabelthe label used in front of the category if the "?id" or "!id" category option is used; default: "article-"
imageidA comma-separated list of image IDs to show. These are added to any images from the category option BEFORE any exclusions are applied.
As with the category option, you can also use "?id" and "?fieldname" which will pick up image IDs from the given fieldname of the currently displayed article. Interesting if you choose ?article_image because you can make your article image viewable in a lightbox! It also supports ID and field negation using the same terminology as the category option.
imagecaptionThe text to display under the large slimbox image. It can be any fixed string (rather pointless!) or a combination of fixed text and one or more of the following options to pull the relevant field from the image.
?caption?alt?name?id?date?category?author?ext?width?heightFor example:
imagecaption="?alt"
would show the alt text under the main image instead of the caption (which it uses by default).
Or, for the adventurous:
imagecaption="?caption by ?author
[ ?ext picture: ?width x ?height ]"
might show a caption such as "Lake Windermere at night by Stef [ jpg picture: 800 x 600 ]".
There is one limitation insofar as each ?variable must be alone, surrounded by whitespace. So, ?caption: photographed by ?author. won't work.
thumbIf you wish the fullsize images displayed in the slimbox window to be the thumbnails instead.
1limitThe number of image thumbnails to show per page. 0 (or omitted)=essentially unlimited.
maxlimitThe absolute maximum number of images to pull from the database. 0 (or omitted)=essentially unlimited.
orderbyA comma-separated list of ways to order the results.
categorynameiddatealtcaptionauthorextwidthheightrandomfixedYou can also specify the direction of the sort order by adding :asc or :desc to any value. For example:
category, date:desc
would sort by category first, then descending date.
The special, overriding, option fixed forces thumbs to be output in the order given in the imageid tag.
Note that 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.
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. fixed is still honoured, however). See the examples for more on this feature.
groupnameThe name to append to the [rel] argument in order to logically group images. Default: "smd".
Once a visitor clicks a thumbnail and control is passed to the slimbox code, navigation is via the Next/Prev links (or the 'n'/'p' or arrow keys). Without supplying a groupname, all lightboxable images from all 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".
To bypass this feature, give each slimbox tag a unique groupname; that will limit the navigation only to the group of images that match. It can be anything you like, or you can supply one of the following options to pull the groupname from the relevant field:
?c?id?author?date?name?ext?alt?caption?width?height?fieldname?excerpt, ?custom1, ?article-image) to pull the groupname from that fieldSee the examples for more.
showpagelinksDisplays clickable next/previous links under the thumbnails. On by default (if limit is greater than 0).
10galleryidIf 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 musthave 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="MyGal1"); or a question mark followed by up to two numbers separated by a colon. In the latter mode, the plugin generates a unique (32-character) string based on the other attributes given. You use the two numbers 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) |
thumbsizeEither 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 the thumbsize option will.
Simply specify up to two values separated by a comma to define the width and height of your thumbnails (in pixels by default). For example: thumbsize="40, 60" to 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 "px".
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%").
thumbtextYou can place text around each thumbnail. Similar to the imagecaption option, enter any fixed text to add it below every thumbnail (inside a <span> tag with a class of thumbtextclass).
You can also combine fixed text with codes to pull out information from each image. The codes can be any of the following:
?caption?alt?name (for the image filename)?id?date?category?author?ext (for the file extension)?width?heightAdditionally, you can specify that this information is placed in any of 5 locations around the image. There are 4 general purpose positions:
abovebelowbeforeafterAnd there is one special position defined by: onchange. This is placed above every image but will only trigger if its contents changes from the image before it. This is very useful for applying headers when the category changes. See Example 6.
Specify text using the standard ? notation, e.g. thumbtext="Filed in ?category [ ?name ]" would put (below each thumbnail) the text "Filed in" and then the category name of the image, followed by its filename in square brackets. If you wanted the information to appear above the thumbnails instead, use:
thumbtext="above:Filed in ?category [ ?name ]"
You can add more than one of these 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, with one limitation: each ?variable must be alone, surrounded by whitespace. So, ?caption; photographed by ?author. won't work because of the punctuation.
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.
paramdelimBy default, 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. This attribute currently only affects the thumbtext option.
prevlabelLabel for the 'previous page' of pictures when using showpagelinks. Default: "Prev" and customisable in different languages via MLP.
nextlabelLabel for the 'next page' of pictures when using showpagelinks. Default: "Next" and customisable in different languages via MLP.
wraptagXHTML 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).
cellclassCSS class for each 'cell' that displays a thumbnail. Default: empty (i.e. no class).
thumbtextclassCSS class for all the bits of text associated with the thumbnail. Default: empty (i.e. no class).
navclassCSS class for the next/prev container. Default: empty (i.e. no class).
prevclassCSS class for the 'prev' link. Default: smd_slimbox_prev.
nextclassCSS class for the 'next' link. Default: smd_slimbox_next.
libcheckSet this to 0 to bypass the library check. Useful if you want the thumbs to be included in an RSS feed without the plugin complaining the libraries are missing. Default: 1 (on).
10Example 1<txp:smd_slimbox category="landscape" limit="10" />
Show all images in the landscape category, ten at a time.
Example 2<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 orderby="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.
Switching the sort to: orderby="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 orderby, you probably want to disable paging by setting showpagelinks="0".
Example 3<txp:smd_slimbox imageid="48, 25, 4"
category="dogs, ?custom1" subcats="1" limit="20"
prevlabel="Back" orderby="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" (without the quotes) you'd get pictures from all three categories and all their subcategories). Limit the number per page to 20, change the previous page label to "Back" and sort the images in descending order of name, then category.
Example 4<txp:smd_slimbox category="static, ?id"
imageid="!article_image" limit="6" groupname="?c"
showpagelinks="0" />
If the person is currently viewing article ID 67, show all images from the 'static' category and the 'article-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 Slimbox 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 article-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 orderby.
Example 5<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.
Example 6<txp:smd_slimbox category="?Photo country" subcats="1"
thumbtext="onchange: <h4> ?category </h4>"
groupname="?c" />
A work-saving tag! Pulls out all pictures from the category given in the custom field labelled Photo country, including any subcategories. 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) 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 Next/Prev on the image.
If you wanted to show category headings that grouped pictures by author as well you could use:
orderby="category, author" thumbtext="onchange: <h4> ?category ( by ?author )</h4>"
Add a little bit of CSS and your single slimbox tag can look like it's creating multiple galleries, all automatically.
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:
<img> tagUsing 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;
}
li.smd_slimbox_nav {
clear:both;
width:500px;
padding:20px;
}
.smd_slimbox_prev {
float:left;
}
.smd_slimbox_next {
float:right;
}
This plugin plagiarises ideas from Rob Sable's rss_thumbpop and various TXPers in the community who have suggested features and improvements. 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 Team TextPattern.