<div id="smd_help">

	<h1 id="top">smd_gallery</h1>

	<h2 id="features">Features</h2>

	<ul>
		<li>Supports all current and (probably) future gallery scripts including thumbpop, rollover, tooltip, lightbox, litebox, slimbox, moonbox, thickbox, slideshow, fancyzoom, etc</li>
		<li>Pull images from the <span class="caps">TXP</span> database that match categories, IDs, author, extension or particular dimensions / aspect ratios</li>
		<li>Use article fields to hold lists of image categories/IDs for article-specific galleries</li>
		<li>Multi-level sub-category support</li>
		<li>Gallery layout is defined in a <span class="caps">TXP</span> form/container</li>
		<li>Direct-access pagination is supported and the layout of paging features can be controlled by a second form</li>
		<li>Uses a tag-replacement system like the wet_for_each_image plugin</li>
		<li><span class="caps">MLP</span> support</li>
	</ul>

	<h2 id="author">Author</h2>

	<p><a href="http://stefdawson.com/contact">Stef Dawson</a>. For other software by me, or to make a donation, see the <a href="http://stefdawson.com/sw">software page</a>.</p>

	<h2 id="install">Installation / Uninstallation</h2>

	<p class="required">Requires <span class="caps">TXP</span> 4.2.0+ and smd_lib v0.36+</p>

	<p>Download the plugin from either <a href="http://textpattern.org/plugins/957/smd_gallery">textpattern.org</a>, or the software page above, paste the code into the <span class="caps">TXP</span> Admin -&gt; Plugins pane, install and enable the plugin. Visit the <a href="http://forum.textpattern.com/viewtopic.php?id=26482">forum thread</a> for more info or to report on the success or otherwise of the plugin.</p>

	<p>To remove the plugin, simply delete it from the Admin-&gt;Plugins tab. If no other plugins are using smd_lib you may safely delete that too.</p>

	<h2 id="usage">Overview</h2>

	<p>The general idea is that this plugin acts as a flexible image filter; nothing more. The plugin options govern which images are pulled out of the database and they are sorted into whatever order you like.</p>

	<p>After that, each image &#8212; one by one &#8212; has all its attributes passed through the container or <code>form</code> of your choice; you simply choose to display whichever image attributes you like in this form. This means any image attributes can be &#8220;injected&#8221; directly into any markup; it could be <span class="caps">TXP</span> tags, it could be content, it could be javascript, or <span class="caps">CSS</span>; anything.</p>

	<p>Pagination works the same way, allowing you to specify how users can step through your image galleries.</p>

	<p>There is also a special &#8220;collate&#8221; mode that allows you to collect all image attributes together into a series of big long lists <em>without</em> calling the form every time. The form/container is then only processed once at the end.</p>

	<p>Between these two modes you should be able to realise any gallerying solution; now and in future.</p>

	<h2 class="tag " id="smd_gallery">smd_gallery</h2>

	<p class="tag-summary">Place one or more smd_gallery tags in an article, page or form, and supply any of the following options to configure it. The attributes are grouped by function to make it easier on your eyes / sanity.</p>

	<h3 id="attributes">Attributes</h3>

	<h4>Filters</h4>

	<ul>
		<li><span class="atnm">id</span> : list of image IDs to display. May be integers or ranges, for example <code>id=&quot;5, 42, 8-11&quot;</code> would grab images 5, 8, 9, 10, 11 and 42. Use &#8216;!&#8217; in front of a number or range to exclude those images. Use &#8216;?&#8217; and the name of a <span class="caps">TXP</span> field to read the list of image IDs from that field, e.g. <code>id=?article_image&quot;</code></li>
		<li><span class="atnm">name</span> : list of image names to display. You can either specify exact matches, e.g. <code>name=&quot;lion.jpg, tiger.jpg&quot;</code> or regular expression matches by appending <code>:regex</code> to terms. For example, <code>name=&quot;lion:regex&quot;</code> would match lion.jpg, lioness.jpg and megalion.jpg. Alternatively, <code>name=&quot;^lion:regex&quot;</code> would only match images that start with &#8216;lion&#8217;. Use &#8216;!&#8217; in front of names to exclude those images. Use &#8216;?&#8217; and the name of a <span class="caps">TXP</span> field to read the list of image names/regexes from that field, e.g. <code>name=?filenames&quot;</code> to read them from a custom field of that name.<div class="break">If you want to negate a regular expression, things may get tricky if you are using meta characters; in this case it is better to set your regular expression up in, say, a txp:variable (or an article field) and use <code>name=&quot;!var_name:regex&quot;</code>.</div><div class="break">You can mix exact matches and regex matches in the same <code>name</code> attribute if you wish. The colon can be altered with <code>paramdelim</code> &#8212; this is sometimes necessary if you are using character classes such as <code>[[:digit:]]</code> in your regular expression.</div></li>
		<li><span class="atnm">category</span> : list of image categories to display. You may specify fixed-name categories (e.g. &#8220;animals&#8221;) or a&#8217;?&#8217; followed by an article field name. e.g. <code>category=&quot;animals, art-?thisid&quot;</code> would grab all images from category &#8220;animals&#8221; and category &#8220;art-42&#8221; (assuming the current article has an id of 42). Use &#8216;!&#8217; to <em>exclude</em> the given category or field.<div class="break">Fields may themselves contain lists of categories. The &#8216;?&#8217; field names may be combined (e.g. ?s-?article_image) but be aware that custom field names may contain spaces if <code>strictfields=&quot;0&quot;</code></div></li>
		<li><span class="atnm">sublevel</span> : an integer that specifies how many &#8216;levels&#8217; down to traverse each matching category. <code>sublevel=&quot;0&quot;</code> (the default) is only the top-level; 1 = top-level plus the 1st sub-cat; 2 = top-level plus the next 2 sub-cats, and so on. <code>sublevel=&quot;all&quot;</code> is all sub-cats</li>
		<li><span class="atnm">author</span> : filter images by this list of author login names</li>
		<li><span class="atnm">extension</span> : filter images by this list of file extensions (without the leading dot)</li>
		<li><span class="atnm">aspect</span> : filter images by this list of aspect ratios. Choose from any of <code>portrait</code>, <code>landscape</code> or <code>square</code></li>
		<li><span class="atnm">dimensions</span> : filter images matching the given dimensions. Specify up to two values. The first is the width and the second is the height. If you wish to specify minimum or maximum dimensions, add <code>&gt;</code>, <code>&gt;=</code>, <code>&lt;</code> or <code>&lt;=</code> before the value. For example, <code>dimensions=&quot;&gt;=1024, &gt;=768&quot;</code> would only show images greater than or equal to 1024 &#215; 768 pixels</li>
		<li><span class="atnm">sort</span> : re-order the images by <code>category</code> (the default), <code>name</code>, <code>date</code>, <code>id</code> (the default if using an id), file <code>ext</code>ension, <code>alt</code>, <code>caption</code>, <code>author</code>, <code>width</code>, <code>height</code>, <code>thumb_width</code>, <code>thumb_height</code>, <code>hasthumb</code> in either <code>asc</code>ending or <code>desc</code>ending order. Two special cases exist: <code>fixed</code> maintains the order you specified in the id and/or category attribute, while <code>random</code> shuffles the order.<div class="break">Note that if <code>random</code> 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 order listed after it. If <code>random</code> 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 the 2nd case, any items listed after &#8216;random&#8217; will be ignored, but <code>fixed</code> is still honoured</div></li>
	</ul>

	<h4>Limits / offsets / sizes</h4>

	<ul>
		<li><span class="atnm">limit</span> : the maximum number of images to show <em>per page</em>. 0 (the default) or omitted = unlimited</li>
		<li><span class="atnm">maxlimit</span> : the absolute maximum number of image to pull from the database. Must be greater than 0</li>
		<li><span class="atnm">offset</span> : skip this many images and start displaying them thereafter</li>
		<li><span class="atnm">thumblimit</span> : the maximum number of thumbnails to show. 0 or omitted = all thumbs. Note that this differs from limit; you can launch a 20-image gallery but only show 1 thumbnail on the page. Be aware that if you are showing multiple categories from a single tag, you will see <code>thumblimit</code> thumbnails <em>at each change in category</em>. If you don&#8217;t want this, set <code>onchange</code> to something else. See the <code>{object}</code> <a href="#rep_gallery">replacement tag</a></li>
		<li><span class="atnm">grouplimit</span> : the maximum number of images to put on the page, <em>per group</em>. A group is considered any set of images (e.g. all images from one category) so this can be used to only display N images at each change in category. A concrete example is displaying a thumbnail that launches a gallery showing the 5 most recent works from each author. Without <code>thumblimit=&quot;1&quot; grouplimit=&quot;5&quot;</code> the number of images in the group would be unlimited. See <a href="#eg12">example 12</a> for more</li>
		<li><span class="atnm">thumboffset</span> : skip this many thumbs before displaying <code>thumblimit</code> thumbnails</li>
		<li><span class="atnm">thumbsize</span> : takes one or two comma-separated numbers to specify width and/or height of all your gallery thumbnails. The default is in pixels if you don&#8217;t specify units. Missing out one or the other parameter (i.e. having an &#8220;empty&#8221; parameter before or after the comma) will only set one of the dimensions. Use a single value to make square thumbs. If you omit either or both, the corresponding value will be read from the database</li>
		<li><span class="atnm">imgsize</span> : identical to <code>thumbsize</code> but for the full size images</li>
	</ul>

	<h4>Forms and paging</h4>

	<ul>
		<li><span class="atnm">form</span> : the <span class="caps">TXP</span> form used to layout your matching images. Without this attribute the plugin acts as a container tag. Without a container, the plugin displays each full-size image, hyperlinked</li>
		<li><span class="atnm">pageform</span> : the <span class="caps">TXP</span> form used to specify the layout of your paging navigation</li>
		<li><span class="atnm">paging</span> : switch paging on without having to specify a pageform. When this is used, all <a href="#rep_paging">page replacement tags</a> become available in the <a href="#rep_gallery">gallery replacement tags</a> as well</li>
		<li><span class="atnm">pagepos</span> : the position of the paging block. Options are <code>below</code> (the default), <code>above</code>, or both of them separated by <code>delim</code></li>
		<li><span class="atnm">objectform</span> : the <span class="caps">TXP</span> form used to specify the layout of your <code>{object}</code> replacement tag. You can use all the standard <a href="#rep_gallery">gallery replacement tags</a> with the exception of <code>{object}</code> itself! Uses a hyperlinked image if no form is specified</li>
		<li><span class="atnm">countform</span> : list of <span class="caps">TXP</span> forms to use when certain numbered images are reached. See <a href="#countform">count forms</a> and <a href="#eg10">example 10</a>. This has no effect in collate mode</li>
		<li><span class="atnm">countpos</span> : default position of the <code>countform</code>s. Either <code>above</code> (the default), <code>below</code>, or both of them separated by <code>delim</code>. Can be overridden on a per-form basis</li>
	</ul>

	<h4>Grouping images</h4>

	<ul>
		<li><span class="atnm">onchange</span> : a list of attributes to &#8220;watch&#8221;. It tells the plugin that you want to be notified when items in this list change compared to the previous image. Under normal circumstances this should be the same as your <code>sort</code> parameter or you may get some freaky results! It defaults to <code>category</code>.<div class="break">This is very useful for splitting galleries at every change in category and displaying the category title above each group. Items you watch are added to the list of replacement tags and are available by putting &#8220;onchange:&#8221; in front of their name (e.g. <code>{onchange:category}</code> &#8212; see <a href="#eg6">example 6</a> for more). The colon delimiter can be changed with <code>paramdelim</code>.</div><div class="break">You can also elect to defer processing of onchange events to a form. To do so, specify a form after your watch item like this <code>category_title:my_form</code>. In my_form you can put any markup and replacement tags. See <a href="#eg11">example 11</a> for more.</div><div class="break">Another way of using this attribute is with the special prefix <code>smd_every:n</code> which will trigger a group change every Nth image. Note it can&#8217;t be used to watch specific things in this mode; it is only used to trigger <code>grouptag</code> changes</div></li>
		<li><span class="atnm">onchangewraptag</span> : the (X)HTML tag to surround any <code>onchange</code> elements you are watching, e.g. <code>onchangewraptag=&quot;h3&quot;</code></li>
		<li><span class="atnm">onchangeclass</span> : the <span class="caps">CSS</span> class name tro apply to the wraptag of any onchange elements you are watching</li>
		<li><span class="atnm">grouptag</span> : the (X)HTML tag to make available as a replacement so you can wrap groups of elements at each <code>onchange</code>. Default: unset. See <a href="#eg6">examples 6</a> for more on the <code>grouptagstart</code> / <code>grouptagend</code> replacement tags</li>
		<li><span class="atnm">groupclass</span> : the <span class="caps">CSS</span> class name applied to any <code>grouptag</code></li>
	</ul>

	<h4>Tag/class/formatting attributes</h4>

	<ul>
		<li><span class="atnm">wraptag</span> : the (X)HTML tag to surround the entire gallery, e.g. <code>wraptag=&quot;div&quot;</code></li>
		<li><span class="atnm">break</span> : the (X)HTML tag to surround each thumbnail</li>
		<li><span class="atnm">class</span> : the <span class="caps">CSS</span> class name applied to the <code>wraptag</code></li>
		<li><span class="atnm">breakclass</span> : the <span class="caps">CSS</span> class name applied to the <code>break</code> elements</li>
		<li><span class="atnm">html_id</span> : the name of an <span class="caps">HTML</span> <code>id</code> attribute to apply to the wraptag</li>
		<li><span class="atnm">navwraptag</span> : the (X)HTML tag to surround the entire <code>pageform</code>, e.g. <code>wraptag=&quot;div&quot;</code>. Default: <code>ul</code></li>
		<li><span class="atnm">navbreak</span> : the (X)HTML tag to surround each item within the <code>pageform</code>. Default: <code>li</code></li>
		<li><span class="atnm">navclass</span> : the <span class="caps">CSS</span> class name of the navigation wraptag. Default: <code>smd_gallery_nav</code></li>
		<li><span class="atnm">emptyclass</span> : the <span class="caps">CSS</span> class name of the navigation items that are <em>not</em> links. Default: <code>empty</code></li>
		<li><span class="atnm">format</span> (<span class="required">only if using <code>{date}</code></span>) : allows you to change the date format used. Can take any <a href="http://uk.php.net/strftime">strftime()</a> values. Defaults to the date system as set in the site&#8217;s prefs</li>
		<li><span class="atnm">lang</span> (<span class="required">only if using <code>{date}</code></span>) : sets the language code of the date format</li>
		<li><span class="atnm">gmt</span> (<span class="required">only if using <code>{date}</code></span>) : returns either local time according to the set time zone preferences (0), or <span class="caps">GMT</span> time (1). Default: 0</li>
	</ul>

	<h4>Plugin customisation</h4>

	<ul>
		<li><span class="atnm">delim</span> : change the delimiter for specifying attribute lists. Default is comma (,)</li>
		<li><span class="atnm">paramdelim</span> : change the delimiter for specifying inter-parameter attributes. Default is colon (:)</li>
		<li><span class="atnm">collate</span> : switch the plugin into <a href="#collate_mode">collate mode</a></li>
		<li><span class="atnm">collatedelim</span> : change the delimiter between each collated item. Default is comma (,)</li>
		<li><span class="atnm">combo</span> : specify your own <a href="#combos">custom replacement tags</a></li>
		<li><span class="atnm">escape</span> : list of replacement variable names to &#8216;escape&#8217;, in other words convert any <span class="caps">HTML</span> tags to their character entity equivalents. Set to <code>escape=&quot;&quot;</code> to turn this feature off. You can escape your own combos. Default: <code>alt, title, caption</code></li>
		<li><span class="atnm">strictfields</span> : when using &#8216;?&#8217; or &#8216;!&#8217; fields, spaces are allowed in field names. Set <code>strictfields=&quot;1&quot;</code> to forbid spaces. Default: 0</li>
		<li><span class="atnm">galleryid</span> : under normal circumstances you should never need this. Each gallery is assigned a unique ID based on the supplied attributes so you may use more than one gallery on a page and navigate them independently. In the unlikely event that two identical IDs are generated you can override the ID for a gallery by using this attribute.<div class="break">Internally the plugin generates a 32-character hash string for each tag, then picks a 4-char code from this string (it takes every 6th character by default). You can supply a unique fixed string (e.g. <code>galleryid=&quot;MyGal&quot;</code>) or give it a question mark and 2 numbers separated by a colon (e.g. <code>galleryid=&quot;?5:4&quot;</code>). The first number is the length of the final string to generate, the second number is how many characters to skip in the 32-char string each time it picks one.</div><div class="break">In this case it generates a 5-character string from the characters it finds at positions 1,5,9,13, and 17. If you omit the 2nd number (e.g. <code>galleryid=&quot;?6&quot;</code>) it will assume it&#8217;s an increment of 1</div></li>
		<li><span class="atnm">thumb</span> : under normal operation, thumbnails use the &#8216;t&#8217; image in your <code>images</code> directory and the full size pictures don&#8217;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:
	<ul>
		<li>thumb=0:1 &#8212; fullsize = regular image : thumbnail = thumb</li>
		<li>thumb=1:0 &#8212; fullsize = thumb : thumbnail = regular image</li>
		<li>thumb=0:0 (or thumb=0) &#8212; fullsize = regular image : thumbnail = regular image</li>
		<li>thumb=1:1 (or thumb=1) &#8212; fullsize = thumb : thumbnail = thumb</li>
	</ul></li>
		<li><span class="atnm">text</span> : display the given text instead of thumbnails. The text can contain <code>?</code> article fields</li>
	</ul>

	<h4>Special attributes</h4>

	<ul>
		<li><span class="atnm">columns</span> : give a comma-separated list of additional columns you would like to pull from the database. Each item you specify is split into three parts: <code>table.column:replacement name</code>. The only mandatory part is the replacement name, since <code>table</code> defaults to txp_image, and the <code>column</code> defaults to the same name as the replacement you specify.<div class="break">For example, if you have installed the cno_image_order plugin you could use <code>columns=&quot;position&quot;</code>, since the plugin adds the &#8216;position&#8217; column to txp_image. You could then sort by <code>position</code> and also display the image&#8217;s <code>{position}</code>. If you wished to rename the variable to, say, <code>imgpos</code> you would use <code>columns=&quot;position:imgpos&quot;</code>. Note that if you specify the table name you must also include the table prefix if you have used one.</div></li>
		<li><span class="atnm">directory</span> : (<span class="required">experimental</span>) read images from a list of directories (or <span class="caps">URL</span>s) instead of the <span class="caps">TXP</span> database</li>
		<li><span class="atnm">match</span> : limit the images and directories chosen in <code>directory</code> mode. Give a list of words to include or !exclude and any matching files or directories will be chosen or ignored, respectively. The match terms are automatically assumed to be &#8220;wild&#8221; so any part of the file name / path will trigger the match</li>
		<li><span class="atnm">debug</span> : turn on diagnostics. Varying levels of verbosity from 0 (none) to 4 (a lot)</li>
	</ul>

	<h2 id="gallery_form">Gallery form</h2>

	<p>The <code>form</code> is where you design what every thumbnail will look like on the screen. You do this by specifying <span class="caps">HTML</span> markup or <span class="caps">TXP</span> tags as normal. In key places where you want, for example, an image ID / alt tag / image width to be displayed, you specify special replacement tags, detailed below. These are replaced for each image in turn, thus building up the gallery.</p>

	<p>In collate mode, the image details are instead made into lists. The form is only processed once and the replacement tags output the entire list.</p>

	<h3 class="atts " id="rep_gallery">Replacement tags: gallery</h3>

	<ul>
		<li><span class="atnm">{id}</span> : image ID (or, in directory mode, the filename without its extension)</li>
		<li><span class="atnm">{name}</span> : full image filename as defined in the database, usually including extension</li>
		<li><span class="atnm">{ext}</span> : file extension, including dot</li>
		<li><span class="atnm">{category}</span> : image category name</li>
		<li><span class="atnm">{category_title}</span> : image category title</li>
		<li><span class="atnm">{author}</span> : who uploaded the image</li>
		<li><span class="atnm">{url}</span> : <span class="caps">URL</span> of the fullsize image</li>
		<li><span class="atnm">{thumburl}</span> : <span class="caps">URL</span> of the thumbnail</li>
		<li><span class="atnm">{imagepath}</span> : directory the image is in</li>
		<li><span class="atnm">{imagedef}</span> : just the file name part of the image (e.g. 5.jpg)</li>
		<li><span class="atnm">{thumbdef}</span> : just the file name part of the thumbnail (e.g. 5t.jpg)</li>
		<li><span class="atnm">{alt}</span> : alt text</li>
		<li><span class="atnm">{title} or {caption}</span> : caption</li>
		<li><span class="atnm">{date}</span> : image upload date</li>
		<li><span class="atnm">{width}</span> : image width</li>
		<li><span class="atnm">{height}</span> : image height</li>
		<li><span class="atnm">{wunits}</span> : image width units (e.g. px, %, em, etc.)</li>
		<li><span class="atnm">{hunits}</span> : image height units</li>
		<li><span class="atnm">{thumbwidth}</span> : thumbnail width</li>
		<li><span class="atnm">{thumbheight}</span> : thumbnail height</li>
		<li><span class="atnm">{thumbwunits}</span> : thumbnail width units (e.g. px, %, em, etc.)</li>
		<li><span class="atnm">{thumbhunits}</span> : thumbnail height units</li>
		<li><span class="atnm">{hasthumb}</span> : if the image has an associated thumbnail or not</li>
		<li><span class="atnm">{galleryid}</span> : gallery id that you or the plugin assigned</li>
		<li><span class="atnm">{object}</span> : a special item containing either the <code>text</code> OR the image tag of the corresponding thumbnail, but <em>only</em> if <code>thumblimit</code> allows it. e.g. if <code>thumblimit=&quot;1&quot;</code> this variable is only set for the first thumbnail in the list; every other time it is empty</li>
		<li><span class="atnm">{counter}</span> : image counter, starting from 1 and incrementing each time</li>
		<li><span class="atnm">{index}</span> : index counter (zero-based &#8212; probably not much use)</li>
		<li><span class="atnm">{thumbcounter}</span> : thumbnail image counter, starting from 1. Note it is &#8216;reset&#8217; whenever an element given in <code>onchange</code> differs from the previous item</li>
		<li><span class="atnm">{thumbindex}</span> : index counter (zero-based &#8212; probably not much use). It is reset like <code>{thumbcounter}</code></li>
		<li><span class="atnm">{totalimages}</span> : total number of images matched on this page</li>
		<li><span class="atnm">{maximages}</span> : absolute maximum number of images across all pages</li>
	</ul>

	<p>In addition, if either <code>paging=&quot;1&quot;</code> or <code>pageform</code> have been specified, all the <a href="#rep_paging">paging replacement tags</a> are available too. If those aren&#8217;t enough, you can <a href="#combos">create your own</a> by grouping combinations of the above, optionally with article variables such as <code>?excerpt</code>, <code>?keywords</code>, <code>?article_image</code>, etc.</p>

	<p>Other tags are added depending if you are watching for <code>onchange</code> elements, or if you have specified a <code>grouptag</code>. If you added <code>onchange=&quot;author, category&quot;</code> then every time the author or category changed compared to the previous image, one or two new replacement tags would become available; namely <code>{onchange:author}</code> and <code>{onchange:category)</code>. Using onchange with <code>smd_every</code> does <em>not</em> add a new replacement tag as it is merely used to count.</p>

	<p>If you used <code>grouptag=&quot;div&quot;</code> as well, you would be given two new replacement tags labelled <code>grouptagstart</code> and <code>grouptagend</code>. See <a href="#eg6">example 6</a> for details.</p>

	<h2 id="paging_form">Paging form</h2>

	<p>Add gallery navigation to your page. Works in a similar manner to the <a href="#gallery_form">gallery form</a>: a series of replacement tags govern which gallery navigation items are available. You could choose to only show next/prev. Or perhaps 1st page/last page. Or numbered page links.</p>

	<h3 class="atts " id="rep_paging">Replacement tags: paging</h3>

	<ul>
		<li><span class="atnm">{navfirst}</span> : first page (default label: &#8220;First&#8221; / <span class="caps">MLP</span>)</li>
		<li><span class="atnm">{navprev}</span> : previous page (default label: &#8220;&laquo;&#8221; / <span class="caps">MLP</span>)</li>
		<li><span class="atnm">{navearlier}</span> : any page numbers before the current page</li>
		<li><span class="atnm">{navthisurl}</span> : current page with a <span class="caps">URL</span> link to itself</li>
		<li><span class="atnm">{navthis}</span> : current page without a <span class="caps">URL</span> link</li>
		<li><span class="atnm">{navlater}</span> : any page numbers after the current page</li>
		<li><span class="atnm">{navnext}</span> : next page (default label: &#8220;&raquo;&#8221; / <span class="caps">MLP</span>)</li>
		<li><span class="atnm">{navlast}</span> : last page (default label: &#8220;Last&#8221; / <span class="caps">MLP</span>)</li>
		<li><span class="atnm">{navfirstpageurl}</span> : raw <span class="caps">URL</span> to first page</li>
		<li><span class="atnm">{navprevpageurl}</span> : raw <span class="caps">URL</span> to previous page</li>
		<li><span class="atnm">{navthispageurl}</span> : raw <span class="caps">URL</span> to current page</li>
		<li><span class="atnm">{navnextpageurl}</span> : raw <span class="caps">URL</span> to next page</li>
		<li><span class="atnm">{navlastpageurl}</span> : raw <span class="caps">URL</span> to last page</li>
		<li><span class="atnm">{totalimages}</span> : total number of images matched on the current page</li>
		<li><span class="atnm">{totalpages}</span> : total number of pages in this collection</li>
		<li><span class="atnm">{maximages}</span> : absolute maximum number of images across all pages</li>
	</ul>

	<p>The current page has a fixed class of &#8216;current&#8217; and each item is, by default, a <code>&lt;li&gt;</code> for easy styling. Custom labels are defined directly in the form itself; for example to label the link that takes users to the first page of the gallery as &#8220;1st&#8221;, use:</p>

	<p><code>{navfirst:1st}</code></p>

	<p>With this syntax you can label navfirst, navlast, navprev, navnext and navthis (the &#8216;:&#8217; delimiter in this case is specified by <code>paramdelim</code>). You can use this mechanism to read <span class="caps">MLP</span> snippets, e.g:</p>

	<p><code>{navfirst:##firstLabel##}</code></p>

	<p>You are not limited to text labels. Images could be used:</p>

	<p><code>{navlast: &lt;img src=&quot;images/last.png&quot; /&gt;}</code></p>

	<p>You can override the number of items displayed by navearlier and navlater by specifying a colon and a number. So to only show 2 items to the left of the current page and 3 items to the right, use <code>{navearlier:2} {navlater:3}</code> in your form. If you were on page 9 of 15, {navearlier:4} {navlater:3} would show <code>&lt;&lt; 5 6 7 8 9 10 11 12 &gt;&gt;</code></p>

	<p>Currently <code>{navearlier}</code> and <code>{navlater}</code> only display arabic numerals. Any ideas on how to offer other character sets greatly appreciated.</p>

	<h2 id="countform">Count forms</h2>

	<p>Sometimes it&#8217;s handy to be able to take action only when certain images are reached; for example:</p>

	<ul>
		<li>only display something on the first or last image</li>
		<li>start a new <span class="caps">HTML</span> &#8216;row&#8217; every 3rd image</li>
		<li>break your gallery up with an advert</li>
	</ul>

	<p>This can be done with smd_if but since it is such a common feature, the plugin has the ability built in. All replacement tags are available within your countforms so you can do some pretty neat stuff. It is best explained by example:</p>

	<ul>
		<li><code>countform=&quot;1:gal_head&quot;</code> : this would output the form <em>gal_head</em> only when the first image is displayed</li>
		<li><code>countform=&quot;{totalimages}:gal_foot&quot;</code> : this would output the form <em>gal_foot</em> only when the last image is displayed</li>
		<li><code>countform=&quot;1:gal_head, {totalimages}:gal_foot&quot;</code> : do both of the above</li>
		<li><code>countform=&quot;1:gal_head, {totalimages}:gal_foot:smd_below&quot;</code> : the same as the previous example, but put the contents below the last image (by default, all output appears above the given image)</li>
		<li><code>countform=&quot;4:9:smd_below:gal_ad&quot;</code> : output <em>gal_ad</em> after the 4th and 9th images only</li>
		<li><code>countform=&quot;4-9:smd_below:gal_ad&quot;</code> : output <em>gal_ad</em> after the 4th, 5th, 6th, 7th, 8th and 9th images only</li>
		<li><code>countform=&quot;smd_every:3:gal_row&quot;</code> : output <em>gal_row</em> before every 3rd image</li>
		<li><code>countform=&quot;smd_every:2:!8:gal_row&quot;</code> : output <em>gal_row</em> before every even image but not on the 8th image</li>
		<li><code>countform=&quot;:gal_row&quot;</code> : use an empty first value to output <em>gal_row</em> before every image. This may seem useless, but it means you can use two, three, four&#8230; forms (or any number of forms and the container) simultaneously to iterate over the same gallery. Or use the same form at different frequencies. Get creative!</li>
		<li><code>countform=&quot;:!5:gal_row:smd_below&quot;</code> : again, missing out the first value will output gal_row after every image, but this time skipping the 5th image</li>
	</ul>

	<p>The <code>,</code> and <code>:</code> can be overridden with the <code>delim</code> and <code>paramdelim</code> attributes, respectively.</p>

	<p>There are a few rules when using the countform:</p>

	<ul>
		<li>numbers must appear before the form name</li>
		<li>the form name is usually the last item in the colon-separated list, though you can put <code>smd_above</code> or <code>smd_below</code> last if you wish</li>
		<li><code>smd_every</code> only affects the value that <em>immediately</em> follows it, e.g. <code>countform=&quot;smd_every:5:7:12:my_ad&quot;</code> will output <em>my_ad</em> at every 5th image, as well as <em>only</em> on the 7th and 12th images. Thus the sequence would be 5, 7, 10, 12, 15, 20, 25, 30&#8230;</li>
		<li>if using <code>smd_every</code>, it <strong>must</strong> appear as the first item. For example <code>countform=&quot;4:the_fourth, 6:smd_every:5:my_ad&quot;</code> is invalid, but <code>countform=&quot;4:the_fourth, smd_every:5:6:my_ad&quot;</code> is OK</li>
	</ul>

	<p>See <a href="#eg10">example 10</a> for more.</p>

	<h2 id="combos">Combos</h2>

	<p>If the built-in <a href="#rep_gallery">replacement tags</a> aren&#8217;t enough for your needs or you find yourself repeating the same combination and want to save yourself some typing, you can define your own. The syntax is:</p>

	<p><code>combo=&quot;newtag1:definition, newtag2:definition, ...&quot;</code></p>

	<p>&#8216;definition&#8217; can be any fixed text, any existing replacement tag, or any &#8216;?&#8217; article variable so you can get really wild here, for example:</p>

	<p><code>combo=&quot;imgin:found in ?s [tagged with ?keywords. Photo by {author}]&quot;</code></p>

	<p>Once defined, <code>{imgin}</code> is available to your gallery <code>form</code> and might be replaced with &#8220;found in zoo [tagged with zebra, africa, stripes. Photo by Bloke]&#8221;. $pretext is also available for those geeks who know what&#8217;s in it (temporarily use <code>debug=&quot;4&quot;</code> to view all available article variables).</p>

	<p>One thing to watch out for is that the space character isn&#8217;t necessarily a delimiter for <code>?</code> variables (because custom fields can have spaces in them). So <code>combo=&quot;doesnotwork:?s in ?category1&quot;</code> will look for a variable labelled &#8220;s in&#8221; and one called &#8220;category1&#8221;. Only one of those exists! Clever use of parentheses or other punctuation can work round this. Or use <code>strictfields=&quot;0&quot;</code> to turn off the use of spaces in custom field names.</p>

	<h2 id="collate_mode">Collate mode</h2>

	<p>If you want to get <em>really</em> funky you can put the plugin into a 2nd mode called &#8220;collation mode&#8221;. This means your chosen form is <strong>not</strong> executed for every image; it is only used once at the very end of the list, after all the images have been internally &#8220;collected&#8221;. In effect, the plugin builds up a giant array of all matching images ready for you to output them all in one go. This is very handy for doing slideshows and is best explained by example:</p>

	<p><code>collate=&quot;1&quot;</code></p>

	<p>switches collation mode on. If the plugin matched 4 images and you were to use the replacement tag <code>{name}</code> in your form like this:</p>

<pre class="block"><code class="block">The matching images: {name}
</code></pre>

	<p>you might get this:</p>

<pre class="block"><code class="block">The matching images: heron.jpg,penguin.jpg,emu.jpg,puffin.jpg
</code></pre>

	<p>Sometimes it&#8217;s useful to be able to put quotes around each item so you can tell collate mode to do that instead:</p>

	<p><code>collate=&quot;quote:{name}&quot;</code></p>

	<p>You would then get:</p>

<pre class="block"><code class="block">The matching images: &quot;heron.jpg&quot;,&quot;penguin.jpg&quot;,&quot;emu.jpg&quot;,&quot;puffin.jpg&quot;
</code></pre>

	<p>The delimiter (a comma in this case) can be overridden with the <code>delim</code> attribute. You may use <code>sglquote</code> to wrap single quotes round the items, or &#8220;dblquote&#8221; as a synonym for &#8220;quote&#8221; if you prefer. You can quote more than one thing at once by specifying the items as a delimited list:</p>

	<p><code>collate=&quot;quote:{name}:{alt}:{imgin}&quot;</code></p>

	<p>Yes, you can use combos! The delimiter used between items can be overriden with the <code>collatedelim</code> attribute.</p>

	<p>The second special feature of collation mode is that you do not have to always output the entire list. You can grab individual entities from within the internal array by using the &#8216;#&#8217; notation thus:</p>

<pre class="block"><code class="block">{name} might output &quot;heron.jpg&quot;,&quot;penguin.jpg&quot;,&quot;emu.jpg&quot;,&quot;puffin.jpg&quot; (as before)
{name#1} would only output heron.jpg
{name#3} would only output emu.jpg
</code></pre>

	<p>Note that when pulling out individual entries they <strong>do not</strong> get quotes added to them, regardless of whether you used <code>quote</code> or not. This is because it is a single item so you can easily put the quotes in the form itself (viz: <code>&quot;{name#2}&quot;</code>)</p>

	<p>Messing around with pulling out individual items and lists can yield some very interesting results and allows some completely wacky galleries to be generated. Try combining smd_gallery tags with <code>&lt;txp:if_different&gt;</code> for a real mind scramble :-)</p>

	<h2 id="examples">Examples</h2>

	<p>The examples all use the classic zoo website. Let&#8217;s get some pictures out of the database&#8230;</p>

	<h3 id="eg1">Example 1: simple / lightboxed gallery</h3>

<pre class="block"><code class="block">&lt;txp:smd_gallery category=&quot;animals&quot; sublevel=&quot;all&quot; form=&quot;gallery&quot; /&gt;
</code></pre>

	<p>That pulls out all pictures from the animals category, including all sub-categories, and passes them to the form called &#8216;gallery&#8217; for processing. The form could be:</p>

<pre class="block"><code class="block">&lt;img class=&quot;animage&quot; src=&quot;{url}&quot; alt=&quot;{alt}&quot; /&gt;
&lt;div class=&quot;acaption&quot;&gt;{title}&lt;/div&gt;
</code></pre>

	<p>That means, for every matched image, substitute its <span class="caps">URL</span>, alt and title tags into the relevant places. Thus you get a series of images on the page, which you can style accordingly.</p>

	<p>For a more fancy output using, say, slimbox, you could load the relevant libraries and styles in the <code>&lt;head&gt;</code> of your page:</p>

<pre class="block"><code class="block">&lt;script type=&quot;text/javascript&quot; src=&quot;/js/mootools.js&quot;&gt;&lt;/script&gt;
&lt;script type=&quot;text/javascript&quot; src=&quot;/js/slimbox.js&quot;&gt;&lt;/script&gt;
&lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; href=&quot;/css/slimbox.css&quot; /&gt;
</code></pre>

	<p>Then your &#8216;gallery&#8217; form could be:</p>

<pre class="block"><code class="block">&lt;a rel=&quot;lightbox-{category}&quot; href=&quot;{url}&quot;
     title=&quot;A picture of {caption}&quot;&gt;
 &lt;txp:thumbnail id=&quot;{id}&quot; /&gt;
&lt;/a&gt;
</code></pre>

	<p>Voila! Using the same smd_gallery tag you have changed the way the gallery renders from a simple list to a full-featured slimbox. With virtually the same form you can switch the output to thickbox, lightbox, litebox, moonbox or whatever-you-like-box depending on which libraries you load. Follow the instructions for your favourite effect and plug it into smd_gallery.</p>

	<h3 id="eg2">Example 2: launch from one image</h3>

	<p>A common request is to be able to &#8220;launch&#8221; a slimbox gallery from a single image or text link. Using a single image:</p>

<pre class="block"><code class="block">&lt;txp:smd_gallery category=&quot;animals&quot;
     sublevel=&quot;all&quot;
     form=&quot;gallery&quot; thumblimit=&quot;1&quot; /&gt;
</code></pre>

	<p>The form will use the special <code>{object}</code> replacement tag so it only displays the thumbnail if the value of thumblimit has <strong>not</strong> been reached:</p>

<pre class="block"><code class="block">&lt;a rel=&quot;lightbox-smd&quot; href=&quot;{url}&quot;
     title=&quot;A picture of {title}&quot;&gt;
{object}
&lt;/a&gt;
</code></pre>

	<p>Change the start image by specifying <code>thumboffset</code> &#8212; note this will also start the lightbox effect from the image you choose. If you want to start on a specific image in position 1, use the <code>id</code> attribute to bring it to the top of the list, or change the sort order.</p>

	<p>If you wanted to launch the gallery from a text link, add something like <code>text=&quot;Click to start lightbox&quot;</code>.</p>

	<h3 id="eg3">Example 3: popup gallery</h3>

	<p>To achieve an effect similar to rss_thumbpop, add an image and caption placeholder outside the call to smd_gallery, then include your smd_gallery tag as usual. This time we are only interested in all the pictures from the categories up to two levels below both &#8220;animals&#8221;, plus whichever categories are listed in <code>my_custom_field</code> and the images with IDs 25, 38, 39, 40 and 42:</p>

<pre class="block"><code class="block">&lt;img id=&quot;fullsize&quot; src=&quot;/images/empty.jpg&quot; /&gt;
&lt;span id=&quot;fullcaption&quot;&gt;&lt;/span&gt;
&lt;txp:smd_gallery sublevel=&quot;2&quot;
     category=&quot;animals, ?my_custom_field&quot;
     id=&quot;25, 42, 38-40&quot; form=&quot;gallery&quot; /&gt;
</code></pre>

	<p>The gallery form looks scary but is only a thumbnail image surrounded by a simple anchor tag with two actions assigned to it: a mouseover to copy the picture and caption into the placeholder; and a mouseout to remove them:</p>

<pre class="block"><code class="block">&lt;a href=&quot;{url}&quot; title=&quot;{title}&quot;
     onmouseover=&quot;document.getElementById(&#39;fullsize&#39;).src = this.href;
     document.getElementById(&#39;fullcaption&#39;).innerHTML = this.title; return false;&quot;
     onmouseout=&quot;document.getElementById(&#39;fullsize&#39;).src = &#39;/images/17.jpg&#39;;
     document.getElementById(&#39;fullcaption&#39;).innerHTML = &#39;&#39;; return false;&quot;&gt;
  &lt;img src=&quot;{thumburl}&quot; alt=&quot;{alt}&quot; /&gt;
&lt;/a&gt;
</code></pre>

	<p>Note there are much neater ways of doing this (e.g. with jQuery) and it&#8217;s not recommended to use this form in a live site, but it gives a flavour of what is possible.</p>

	<h3 id="eg4">Example 4: slideshow</h3>

	<p>This one uses collate mode but is not much more difficult to understand. In your <code>&lt;head&gt;</code> section:</p>

<pre class="block"><code class="block">&lt;script type=&quot;text/javascript&quot; src=&quot;/js/mootools.js&quot;&gt;&lt;/script&gt;
&lt;script type=&quot;text/javascript&quot; src=&quot;/js/slideshow.js&quot;&gt;&lt;/script&gt;
</code></pre>

	<p>The tag:</p>

<pre class="block"><code class="block">&lt;txp:smd_gallery
  category=&quot;birds, fish&quot; form=&quot;gallery&quot;
  combo=&quot;imglist:{id}{ext}&quot;
  collate=&quot;quote:{imglist}:{alt}&quot; /&gt;
</code></pre>

	<p>That pulls all pictures from the birds and fish categories. Although technically unnecessary, a combo has been defined to show how it can be used. This combo is called <code>imglist</code> and is defined as the image&#8217;s ID number plus its extension. We use this in the collate attribute and tell it to put double quotes round every item in &#8216;imglist&#8217; and &#8216;alt&#8217;. Then we can put these values into the necessary javascript in the <code>gallery</code> form to generate the slideshow:</p>

<pre class="block"><code class="block">&lt;div class=&quot;slideshow&quot; id=&quot;slideshow1&quot;&gt;
 &lt;img src=&quot;&lt;txp:site_url /&gt;images/{id#1}.jpg&quot;
     alt=&quot;{alt#1}&quot; width=&quot;{width#1}&quot; height=&quot;{height#1}&quot; /&gt;
&lt;/div&gt;
</code>
<code class="block">&lt;script type=&quot;text/javascript&quot;&gt;
myShow1 = new Slideshow(&quot;slideshow1&quot;,
  { hu: &quot;&lt;txp:site_url /&gt;images/&quot;,
    images: [{imglist}],
    captions: [{alt}],
    classes: [&quot;prev&quot;,&quot;next&quot;,&quot;active&quot;],
    type: &quot;fade&quot;
  });
&lt;/script&gt;
</code></pre>

	<p>Note that the initial portion (in the div and img tags) uses the &#8216;#&#8217; notation because we only want to display one image to &#8220;start&#8221; the slideshow. In this case we&#8217;re using the first image in the list, but you can change the #1 for #42 if you wanted to show the forty-second image instead! The part in the script tag uses the full, quoted lists because that&#8217;s the format the javascript requires.</p>

	<h3 id="eg5">Example 5: pagination</h3>

	<p>To add paging to a gallery you use the <code>limit</code> attribute to show a number of thumbs per page. For a paged thumbpop gallery that shows five thumbs per page:</p>

<pre class="block"><code class="block">&lt;img id=&quot;fullsize&quot; src=&quot;/images/empty.jpg&quot; /&gt;
&lt;span id=&quot;fullcaption&quot;&gt;&lt;/span&gt;
&lt;txp:smd_gallery category=&quot;animals&quot;
  form=&quot;gallery&quot; pageform=&quot;gallery_nav&quot;
  limit=&quot;5&quot; /&gt;
</code></pre>

	<p>The &#8216;gallery&#8217; form is identical to the one in <a href="#eg4">example 4</a>, while your gallery_nav form might look like this:</p>

<pre class="block"><code class="block">&lt;div class=&quot;total&quot;&gt;# of pics: {totalimages}&lt;/div&gt;
     {navfirst} {navprev}
     {navearlier} {navthis} {navlater}
     {navnext} {navlast}
</code></pre>

	<p>That might render something similar to this below the thumbs:</p>

<pre class="block"><code class="block"># of pics: 38
     First &lt; 1 2 3 4 5 6 7 8 &gt; Last
</code></pre>

	<h3 id="eg6">Example 6: onchange</h3>

	<p>If you want to simulate multiple galleries from one smd_gallery tag you can use <code>onchange</code> to &#8220;watch&#8221; for when certain attributes of images change and insert special tags <em>only when something changes</em>. In this regard it acts like a souped-up version of <span class="caps">TXP</span>&#8217;s built-in <code>&lt;txp:if_different&gt;</code> tag.</p>

	<p>You can watch the usual things like <code>category</code>, <code>author</code>, <code>width</code>, <code>height</code>, <code>ext</code>ension and so on:</p>

<pre class="block"><code class="block">&lt;txp:smd_gallery
     category=&quot;birds, fish&quot; form=&quot;gallery&quot;
     onchange=&quot;category_title&quot;
     onchangewraptag=&quot;h3&quot; /&gt;
</code></pre>

	<p>Since the plugin normally sorts by category, this will have the effect of adding one replacement tag <code>{onchange:category_title}</code> at the very beginning of the thumb list and also when the category switches from &#8216;birds&#8217; to &#8216;fish&#8217;. Thus your gallery form could be:</p>

<pre class="block"><code class="block">{onchange:category_title}
&lt;a href=&quot;{url}&quot; rel=&quot;lightbox-{category}&quot;&gt;
{object}
&lt;/a&gt;
</code></pre>

	<p>That would make two lightboxable sets of thumbnails with a heading 3 above each group containing the category title.</p>

	<p>Note that if you add <code>thumblimit=&quot;1&quot;</code> to the smd_gallery tag you can show just one thumbnail in each group, with headings above each thumb. Visitors clicking the thumb will launch the lightbox and be able to browse the relevant category. If you want to make sure that they can only browse six images in each category set, add <code>grouplimit=&quot;6&quot;</code>.</p>

	<p>An extra pair of replacement tags are available if you wish to wrap the objects themselves to group them. Use the <code>grouptag</code> and <code>groupclass</code> attributes to set it up, then two new replacement tags called <code>grouptagstart</code> and <code>grouptagend</code> become available. They are conditional and are only populated when the attributes you are watching/sorting by change. Use it like this:</p>

<pre class="block"><code class="block">&lt;txp:smd_gallery id=&quot;?article_image&quot;
     category=&quot;birds, fish&quot; form=&quot;gallery&quot;
     onchange=&quot;category_title&quot;
     onchangewraptag=&quot;h3&quot;
     grouptag=&quot;div&quot; groupclass=&quot;box&quot; /&gt;
</code></pre>

<pre class="block"><code class="block">{onchange:category_title}
{grouptagstart}
&lt;a href=&quot;{url}&quot; rel=&quot;lightbox-{category}&quot;&gt;
{object}
&lt;/a&gt;
{grouptagend}
</code></pre>

	<p>Note that you can move the <code>grouptagstart</code> to surround the <code>onchange</code>d title if you wish.</p>

	<h3 id="eg7">Example 7: smd_every</h3>

	<p>You can also trigger an onchange event every nth image:</p>

<pre class="block"><code class="block">&lt;txp:smd_gallery category=&quot;frontpage&quot;
     limit=&quot;9&quot; sort=&quot;random&quot;
     onchange=&quot;smd_every:3&quot;
     grouptag=&quot;ul&quot; groupclass=&quot;slideshow&quot;&gt;
{grouptagstart}
   &lt;li&gt;
      &lt;a href=&quot;&lt;txp:permlink id=&quot;{alt}&quot; /&gt;&quot;&gt;
         &lt;img src=&quot;{thumburl}&quot; alt=&quot;&quot; /&gt;
         &lt;span&gt;{title}&lt;/span&gt;
      &lt;/a&gt;
   &lt;/li&gt;
{grouptagend}
&lt;/txp:smd_gallery&gt;
</code></pre>

	<h3 id="eg8">Example 8: uncategorized images</h3>

	<p>Sometimes you might wish to extract images that do not have a category assigned. You need to use the special value <code>SMD_EMPTY</code> for this:</p>

<pre class="block"><code class="block">&lt;txp:smd_gallery category=&quot;SMD_EMPTY, shoes&quot; /&gt;
</code></pre>

	<p>You can also negate the logic so you can extract all images that have some (any) category assigned to them:</p>

<pre class="block"><code class="block">&lt;txp:smd_gallery category=&quot;!SMD_EMPTY&quot; /&gt;
</code></pre>

	<h3 id="eg9">Example 9: {object} and objectform</h3>

	<p>The default <code>{object}</code> outputs a simple hyperlinked thumbnail. If you want something a bit more exotic, like launching a shadowbox effect from a single thumbnail that also has the caption beneath it, you need to customise the <code>{object}</code> via the <code>objectform</code> attribute. Put a list of image IDs in your article image field and then:</p>

<pre class="block"><code class="block">&lt;txp:smd_gallery thumblimit=&quot;1&quot;
     id=&quot;?article_image&quot; wraptag=&quot;div&quot;
     class=&quot;thumbs&quot; objectform=&quot;my_obj&quot;
     combo=&quot;artid:?thisid&quot;&gt;
  &lt;a rel=&quot;shadowbox[{artid}];
     options={counterType:&#39;skip&#39;,
     continuous:true,
     animate:false,
     animSequence:&#39;sync&#39;}&quot;
     href=&quot;{url}&quot;
     title=&quot;{alt}&quot;&gt;{object}&lt;/a&gt;
&lt;/txp:smd_gallery&gt;
</code></pre>

	<p>And in <code>my_obj</code>, you could put:</p>

<pre class="block"><code class="block">&lt;txp:thumbnail id=&quot;{id}&quot; /&gt;&lt;br /&gt;{title}
</code></pre>

	<p>Notice how the replacement tags still work in the <code>objectform</code>? This allows you to build up a complete layout for the launchable thumbnail and have it only rendered once on the page. The rest of the container in this example renders all the &#8220;hidden&#8221; images in the shadowbox gallery.</p>

	<h3 id="eg10">Example 10: <code>countform</code></h3>

<pre class="block"><code class="block">&lt;txp:smd_gallery category=&quot;animals&quot;
     countform=&quot;1:gal_a:smd_above,
       {totalimages}:gal_c,
       smd_every:3:!{totalimages}:gal_b&quot;
     countpos=&quot;below&quot;&gt;
&lt;txp:thumbnail id=&quot;{id}&quot; /&gt;
&lt;/txp:smd_gallery&gt;
</code></pre>

	<p>Note that <code>countpos</code> is set to <code>below</code> in this example so all output appears <em>after</em> the given images. If you made the following three forms, your tag would split the gallery into &#8216;rows&#8217; of 3 images:</p>

	<p>gal_a: <code>&lt;div class=&quot;newrow&quot;&gt;</code><br />
gal_b: <code>&lt;/div&gt;&lt;div class=&quot;newrow&quot;&gt;</code><br />
gal_c: <code>&lt;/div&gt;</code></p>

	<p>Breaking the <code>countform</code> attribute down into its components, you can see that:</p>

	<ul>
		<li><code>1:gal_a:smd_above</code> adds the &#8216;newrow&#8217; div above the first image</li>
		<li><code>{totalimages}:gal_c</code> adds the closing div below the last image on this page</li>
		<li><code>smd_every:3:!{totalimages}:gal_b</code> adds a closing and then an opening div after every 3rd image, <em>except</em> on the last image. If we didn&#8217;t put the exception in, and you had 12 thumbnails in your gallery (which is divisible by 3!) you would see the contents of gal2 after the last image as well</li>
	</ul>

	<h3 id="eg11">Example 11: Using an onchange form</h3>

<pre class="block"><code class="block">&lt;txp:smd_gallery
     category=&quot;birds, fish&quot;
     onchange=&quot;category_title:oc_form&quot;&gt;
{onchange:category_title}
&lt;a href=&quot;{url}&quot; rel=&quot;lightbox-{category}&quot;&gt;
{object}
&lt;/a&gt;
&lt;/txp:smd_gallery&gt;
</code></pre>

	<p>and in form <code>oc_form</code>:</p>

<pre class="block"><code class="block">&lt;div id=&quot;{category}&quot;
   class=&quot;category&quot;&gt;{category_title}&lt;/div&gt;
</code></pre>

	<h3 id="eg12">Example 12: Portfolio landing page</h3>

	<p>Here we will render a gallery for each artist on a gallery site. Arrange your image categories so they are children of a parent image category:</p>

<pre class="block"><code class="block">portfolio
  |--&gt; monet
  |--&gt; van_gogh
  |--&gt; turner
  |--&gt; dali
  |--&gt; ...
</code></pre>

	<p>Then of course, upload your images and assign them to the appropriate artist category.</p>

<pre class="block"><code class="block">&lt;txp:smd_gallery
     category=&quot;portfolio&quot; sublevel=&quot;1&quot;
     onchange=&quot;category_title&quot;
     onchangewraptag=&quot;h3&quot; thumblimit=&quot;1&quot;
     grouplimit=&quot;5&quot; sort=&quot;category asc, date desc&quot;
     objectform=&quot;full_link&quot;&gt;
{onchange:category_title}
&lt;a href=&quot;{url}&quot; rel=&quot;lightbox-{category}&quot;&gt;
{object}
&lt;/a&gt;
&lt;/txp:smd_gallery&gt;
</code></pre>

	<p>In Form <code>full_link</code>:</p>

<pre class="block"><code class="block">&lt;txp:thumbnail id=&quot;{id}&quot; /&gt;
&lt;span&gt;
   See &lt;a href=&quot;/artists/{category}&quot;&gt;all images by {category_title}&lt;/a&gt;.
&lt;/span&gt;
</code></pre>

	<p>That will grab each artist category and display a thumbnail of the most recent work submitted by each author under their own heading. When you click the thumbnail it launches the lightbox gallery and allows you to navigate through the five most recent pictures submitted. Beneath the thumbnail is a link to an individual article that could show that artists&#8217;s complete works and a bio.</p>

	<h2 id="changelog">Changelog</h2>

	<p>All available versions and changes are listed here.</p>

	<p><strong>Beta</strong></p>

	<ul>
		<li>14 Feb 08 | 0.1 | Initial release &#8211; Happy Valentines Day :-)</li>
		<li>19 Feb 08 | 0.2 | Added {galleryid} (thanks rloaderro) and some skeleton docs</li>
	</ul>

	<p><strong>Official</strong></p>

	<ul>
		<li>11 Mar 08 | 0.3 | Official public release. Fixed silly empty field bug; added {counter}, {index} and the totals (all thanks jakob)</li>
		<li>15 Mar 08 | 0.31 | Fixed a couple of undefined indexes and added {category_title} (thanks jstubbs)</li>
		<li>17 Mar 08 | 0.32 | Fixed another undefined index and removed bogus call to smd_lib (both thanks secundar)</li>
		<li>21 Mar 08 | 0.33 | Did v0.31 properly, including table prefix (thanks nardo)</li>
		<li>01 Apr 08 | 0.34 | Fixed <span class="caps">SQL</span> parenthesis bug ; added emptyclass and {maximages} (thanks the_ghost)</li>
		<li>08 Apr 08 | 0.4 | Changed thumb to allow thumb/fullsize swapping ; Added thumbchange, thumbchangewraptag, thumbchangeclass, {thumbindex}, {thumbcounter} and the {changed:*} replacement tags (thanks fuls)</li>
		<li>26 May 08 | 0.41 | Fixed Directory separator (thanks cuda) ; added raw page <span class="caps">URL</span>s to the nav replacement array and made the nav array available in the standard replacements array (thanks visualpeople)</li>
		<li>27 May 08 | 0.42 | Added pagepos and made page blocks independent of thumb block (thanks duchamp)</li>
		<li>10 Jun 08 | 0.43 | Fixed sort=&#8220;fixed&#8221; when using limit (thanks robin746) ; added per-group onchange wrapping and allowed fixed sorting of categories (thanks jstubbs) ; deprecated thumbchange* and renamed as onchange* ; fixed $idx counter problem</li>
		<li>10 Jun 08 | 0.44 | Attempt #2 at per-group onchange wrapping (thanks again jstubbs)</li>
		<li>14 Jul 08 | 0.45 | Fixed lack of output when not using categories (thanks robin746)</li>
		<li>16 Nov 08 | 0.46 | Added collatedelim (thanks curiouz) ; fixed (I hope) the category / id bug from 0.44 and 0.45 (thanks robin746/nardo)</li>
		<li>13 Feb 09 | 0.5 | Requires smd_lib ; added <span class="caps">MLP</span> support (thanks net-carver) ; added support for displaying uncategorised images (thanks xzamen) ; &#8216;?&#8217; vars expanded to link / image / file / <code>&lt;txp:variable /&gt;</code> and <span class="caps">URL</span> variable ; new attributes: <code>escape</code>, <code>html_id</code>, <code>format</code>, <code>gmt</code>, <code>lang</code> (thanks maniqui), <code>strictfields</code> ; improved <code>{object}</code> support and added <code>objectform</code> (thanks tye/rvturnage) ; <code>{title}</code> == <code>{caption}</code> at last! ; removed <code>thumbchange</code>* attributes ; improved support for table extensions (via the <code>columns</code> attribute: thanks RedFox) ; added <code>smd_every</code> syntax to <code>onchange</code> (thanks jakob) ; fixed offset bug (thanks feragnoli)</li>
		<li>01 Mar 09 | 0.51 | Added <code>countform</code> and <code>countpos</code> ; fixed <code>{hasthumb}</code> warning</li>
		<li>16 Nov 09 | 0.52 | <span class="caps">TXP</span> 4.2.0 only ; added database thumbnail height and width support ; added <code>aspect</code>, <code>dimensions</code>, <code>author</code>, <code>extension</code> and <code>imgsize</code> attributes ; fixed quote parsing in <code>escape</code> attribute and warning when using <code>fixed</code> sorting (both thanks maniqui)</li>
		<li>01 Jan 10 | 0.53 | Added onchange form capability (thanks MattD)</li>
		<li>01 Feb 10 | 0.54 | Multiple images not displayed if multiple categories exist with the same name and different title</li>
		<li>01 Mar 10 | 0.55 | Added <code>name</code> filtering</li>
		<li>10 Mar 10 | 0.6 | Simplified query to eliminate errors with uncategorised images being omitted from the results; allowed countform ranges ; added <code>grouplimit</code></li>
		<li>03 Apr 10 | 0.61 | Added <code>breakclass</code> (thanks the_ghost)</li>
		<li>06 Apr 10 | 0.62 | Fixed <code>{onchange:category_title}</code> and <code>{grouptagend}</code> (thanks jan)</li>
	</ul>

	<h2 id="credits">Credits</h2>

	<p>This plugin wouldn&#8217;t have existed without the awesome mind of Robert Wetzlmayr. His wet_for_each_image plugin is true genius; this simply stands on the shoulders of that idea and rolls in a souped up version of the thumbnail generation engine from smd_slimbox. To that end, the plugin is also indebted to anyone who has posted features or bug reports to me or the smd_slimbox thread. You&#8217;re all marvellous.</p>

</div>
<!-- *** BEGIN PLUGIN CSS *** -->
<style type="text/css">
#smd_help { line-height:1.5 ;}
#smd_help code { font-weight:bold; font: 105%/130% "Courier New", courier, monospace; background-color: #FFFFCC;}
#smd_help code.block { font-weight:normal; border:1px dotted #999; background-color: #f0e68c; display:block; margin:10px 10px 20px; padding:10px; }
#smd_help a:link, #smd_help a:visited { color: #00c; text-decoration: none; border-bottom: 1px solid blue; padding-bottom:1px;}
#smd_help a:hover, #smd_help a:active { color: blue; text-decoration: none; border-bottom: 2px solid blue; padding-bottom:1px;}
#smd_help h1 { color: #369; font: 20px Georgia, sans-serif; margin: 0; text-align: center; }
#smd_help h2 { border-bottom: 1px solid black; padding:10px 0 0; color: #369; font: 17px Georgia, sans-serif; }
#smd_help h3 { color: #079; font: bold 12px Arial, sans-serif; letter-spacing: 1px; margin: 10px 0 0;text-transform: uppercase; text-decoration:underline;}
#smd_help h4 { font: bold 11px Arial, sans-serif; letter-spacing: 1px; margin: 10px 0 0 ;text-transform: uppercase; }
#smd_help .atnm { font-weight:bold; color:#33d; }
#smd_help .mand { background:#eee; border:1px dotted #999; }
#smd_help table {width:90%; text-align:center; padding-bottom:1em;}
#smd_help td, #smd_help th {border:1px solid #999; padding:.5em 0;}
#smd_help ul { list-style-type:square; }
#smd_help .required {color:red;}
#smd_help li { margin:5px 20px 5px 30px; }
#smd_help .break { margin-top:5px; }
</style>
<!-- *** END PLUGIN CSS *** -->
