[requires smd_lib 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. Also plagiarises ideas from Rob Sable's rss_thumbpop. Supports the Multi-Lingual Pack (MLP) for image caption/alt and internal string localisation. Many thanks to the original authors.
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.
When installed, this plugin adds two tags. The first (smd_slimbox_inc) goes in the <head> section of your page and loads the required libraries. 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.
Somewhere in the <head> of the page that you want your gallery on, add:
<txp:smd_slimbox_inc jsdir="/js" cssdir="/css" />
If you have the libraries in the js and css folders in your textpattern root folder, that will be fine. If not, you can change where the plugin looks for the libraries by adjusting the two options.
If you want more control, you have two more options available. The first is scripts. This takes a comma-separated list of up to 3 arguments in this order: mootoolsJSLocation, slimboxJSLocation, slimboxCSSLocation. 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, instead of the cssdir and jsdir options you could do:
<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. 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> />
Unfortunately, the plugin does not check that you have given it the 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!
If you are using RSS feeds or just don't want to use smd_slimbox_inc, you can turn it off. Just add libcheck="0" to the smd_slimbox tag. See the next section.
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:
catlabel option and the ID field. By default this will be "article-ID". You may negate the article ID by using "!id".
category option BEFORE any exclusions are applied.
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!
category option.
<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) 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 exclude images from categories listed in custom2 and also exclude 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;
}