For more information on usage, bugs, features etc, please visit the forum thread.
Requires smd_lib v0.21d 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:
It plagiarises ideas from Rob Sable's rss_thumbpop and various TXPers in the community who have suggested features and improvements. Many thanks to all who have helped craft this plugin.
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 t ofind 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!
Assuming 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.
If 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" />
If 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 supplying 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.
limitThe 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.
showcaptionDisplay the image's caption with the image. Off by default. See textpos for positioning.
01showaltDisplay the image's alt text with the image. Off by default. See textpos for positioning.
01textposPosition of the alt/caption information.
abovebelowbeforeaftershowpagelinksDisplays 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) |
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).
captionclassCSS class for the caption text. Default: empty (i.e. no class).
altclassCSS class for the alt text. 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).
10<txp:smd_slimbox category="landscape" limit="10" />
Show all images in the landscape category, ten at a time.
<txp:smd_slimbox category="dogs, birds" limit="9" showcaptions="1" textpos="after" 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".
<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.
<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.
<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.
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;
}