What is Gallerax?

Gallerax is a small jQuery plugin by nodethirtythree design that helps you put together slick, dynamic image galleries with minimal time and effort. It also includes a few extra features should you want to make your gallery a bit fancier.

Basic Usage

To make Gallerax as flexible as possible it's designed to simply take existing elements on a page (picked out using the jQuery selectors you provide it) and build a gallery around them. Here's a basic example:

<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="jquery.gallerax-0.2.js"></script>

<div id="gallery">
  <img class="output" src="images/1.jpg" alt="" />
  <p class="caption">Monument Valley</p>
  <ul class="thumbnails">
	<li><img class="active" src="images/1.jpg" title="Monument Valley" alt="" width="100" height="75" /></li>
	<li><img src="images/2.jpg" title="Honey Bee" alt="" width="100" height="75" /></li>
	<li><img src="images/3.jpg" title="Cup of Coffee" alt="" width="100" height="75" /></li>
	<li><img src="images/4.jpg" title="Grand Tetons" alt="" width="100" height="75" /></li>
	<li><img src="images/5.jpg" title="LA Skyline" alt="" width="100" height="75" /></li>
	<li><img src="images/6.jpg" title="Leaf" alt="" width="100" height="75" /></li>
	<li><img src="images/7.jpg" title="Chinese Bell" alt="" width="100" height="75" /></li>
	<li><img src="images/8.jpg" title="Ladybird" alt="" width="100" height="75" /></li>
  </ul>
  <br class="clear" />
</div>

<script type="text/javascript">
  $('#gallery').gallerax({
	outputSelector: '.output',
	thumbnailsSelector: '.thumbnails li img',
	captionSelector: '.caption'
  });
</script>
				

In this example, we first select the DIV #gallery as the parent element for the gallery and then call the gallerax jQuery function with the following set of parameters:

outputSelector: '.output'
This tells Gallerax where to find the main output image (ie. the big, full size image) within #gallery. In this case it's the image element with the output class.
thumbnailsSelector: '.thumbnails li img'
This tells Gallerax where to find each thumbnail image we want in the gallery (again, within #gallery). In this case we're selecting every image inside each item of the unordered list with the .thumbnails class.
captionSelector: '.caption'
This (optionally) tells Gallerax where to find the element within #gallery where we want each image's caption to show up when it's selected. In this case it's the paragraph element with the .caption class.

The result? See it in action in example1.html.

Advanced Usage

While the basic example above works pretty well, Gallerax has several extra features that can make it not only look better but also more functional. Check out example2.html for a more enhanced version of the example above, and example3.html for a version that incorporates every feature Gallerax currently has to offer.

Parameter Reference

outputSelector
Selector for the main output image. This is usually an image element.
outputImgSelector
(Optional) Selector for the main output image in the event outputSelector is not an image element. If this selector is provided, Gallerax will look for it within the scope of the element pointed to by outputSelector. This must point to an image element.
captionSelector
(Optional) Selector for the caption element. This is usually a span or paragraph element, but anything that can hold text will work as well. The caption string (which can actually contain more than a single caption line using the captionLineSeparator parameter below) is pulled from each thumbnail image element's title attribute, and it can also include HTML code as long as it's escaped using JavaScript's escape() function.
captionLineSeparator
(Optional) Separator character used to separate each line of a multi-line caption string. The default is ; (a semicolon). A multi-line caption string might look like this: This is the first line of my caption ; This is the second line of my caption.
captionLines
(Optional) Total number of caption lines. If this is more than 1, each thumbnail image's caption string is treated as a multi-line caption and additional caption elements beyond the first will be selected within the parent element using the format "captionSelector + n", where n is an integer from 2 to the number defined by this parameter. Each caption string is then split by the character defined by captionLineSeparator and the resulting lines are assigned to their respective caption elements.
For example, if captionSelector is set to #caption, setting this parameter to 4 will make Gallerax look for the following four caption elements: #caption, #caption2, #caption3, and #caption4.
thumbnailsSelector
Selector for every thumbnail image. This is usually one or more image elements, but can be something else in the event you wish to have the optional thumbnailsActiveClass class (see below) applied to the element containing each thumbnail image rather than the thumbnail image itself.
thumbnailsImgSelector
(Optional) Selector for every thumbnail image in the event thumbnailsSelector does not point to image elements. If this selector is provided, Gallerax will look for it within the scope of each element pointed to by thumbnailsSelector. This must point to image elements.
thumbnailsActiveClass
(Optional) Class assigned to the thumbnail element of the image currently being viewed. The default is active.
thumbnailsFunction
(Optional) Callback function used to transform a thumbnail image's src attribute to a new src attribute that will be used for its output image (instead of just reusing the same image as the thumbnail). This is useful if you want to use a separate image for each thumbnail's output image. The default is null, which tells Gallerax to just use the same thumbnail image as the output image.
For a good example of this in use, see example3.html.
thumbnailsPreloadOutput
(Optional) If thumbnailsFunction is defined, this can be set to true to cache each thumbnail's separate output image on page load. The default is false.
navNextSelector
(Optional) Selector for the "next" navigational element. This can be pretty much anything, though it's usually either an anchor element or an image element.
navPreviousSelector
(Optional) Selector for the "previous" navigational element. This can be pretty much anything, though it's usually either an anchor element or an image element.
navFirstSelector
(Optional) Selector for the "first" navigational element. This can be pretty much anything, though it's usually either an anchor element or an image element.
navLastSelector
(Optional) Selector for the "last" navigational element. This can be pretty much anything, though it's usually either an anchor element or an image element.
navStopAdvanceSelector
(Optional) Selector for the "stop advancement" navigational element. This can be pretty much anything, though it's usually either an anchor element or an image element.
navPlayAdvanceSelector
(Optional) Selector for the "play advancement" navigational element. This can be pretty much anything, though it's usually either an anchor element or an image element.
navWrap
(Optional) If true, navigation will jump to the opposite end of the thumbnails list if the user navigates beyond the first or last thumbnail. The default is true.
fade
(Optional) Fade speed for image transitions ( slow, fast, 0 for no fade, or a custom duration in milliseconds). The default is 0.
advanceDelay
(Optional) Delay (in milliseconds) between automatic image advances. If this is not 0, Gallerax will automatically advance to the next thumbnail image after this many milliseconds, wrapping back to the first image when it reaches the end. The default is 0.
advanceResume
(Optional) Time (in milliseconds) before automatic image advancement resumes after the user manually changes the image (by either clicking on a thumbnail or using a navigational element). If set to 0, automatic image advancement will not resume after an interruption. The default is 0.
advanceFade
(Optional) Fade speed for image transitions performed by automatic image advancement ( slow, fast, 0 for no fade, or a custom duration in milliseconds). The default is 0.
advanceNavActiveClass
(Optional) If either navStopAdvanceSelector or navPlayAdvanceSelector are defined, this class gets assigned to whichever navigation element is active. ie. if automatic image advancement is stopped, the "stop advancement" element will be given this class, and the same class will be removed from the "start advancement" element. The default is active.

License

This plugin, like jQuery itself, is dual licensed under the MIT or GPL license, so pick the one that best suits the project you're working on and rock out. Whichever one you use, make sure the license in its entirety (along with my copyright) remains with the plugin wherever it goes.

MIT license

Copyright (c) 2010 nodethirtythree design, http://nodethirtythree.com/

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
			
GPL license

Copyright (c) 2010 nodethirtythree design, http://nodethirtythree.com/

This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free 
Software Foundation, either version 3 of the License, or (at your option) 
any later version.

This program is distributed in the hope that it will be useful, but 
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 
for more details.

You should have received a copy of the GNU General Public License along 
with this program. If not, see <http://www.gnu.org/licenses/>. 
				

Credits

Thanks to the jQuery Team for developing jQuery, and PD Photo for the excellent public domain photos used in this plugin's examples.

If you need help, find a bug or problem, or just want to let me know you're using this plugin, feel free to contact me via my site.