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 theoutput
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 byoutputSelector
. 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'stitle
attribute, and it can also include HTML code as long as it's escaped using JavaScript'sescape()
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 bycaptionLineSeparator
and the resulting lines are assigned to their respective caption elements. -
For example, if
captionSelector
is set to#caption
, setting this parameter to4
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 bythumbnailsSelector
. 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 newsrc
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 isnull
, 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 totrue
to cache each thumbnail's separate output image on page load. The default isfalse
. 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 istrue
. fade
-
(Optional) Fade speed for image transitions (
slow
,fast
,0
for no fade, or a custom duration in milliseconds). The default is0
. 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 is0
. 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 is0
. 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 is0
. advanceNavActiveClass
-
(Optional) If either
navStopAdvanceSelector
ornavPlayAdvanceSelector
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 isactive
.
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.