patiek / gallerie

Gallerie is a simple JQuery plugin that offers a lightbox-like gallery viewer of a collection of images.
Other
15 stars 14 forks source link

Gallerie - A JQuery Gallery Plugin

Gallerie is a plugin that offers a basic lightbox-like gallery viewer of a collection of images. It features a simple overlay with a scrollable thumbnail list, image loading hint, as well as an image caption and index. The overlay thumbnails automatically scroll with the user's mouse and can be activated by click or custom event. Several methods exist to allow for extending the plugin with richer functionality through javascript.

Usage

You can use gallerie by simply calling it on your existing collection of thumbnail links. For example, you could place the folling inside of <head> tags:

<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script src="https://github.com/patiek/gallerie/raw/master/jquery.gallerie.js"></script>
<link rel="stylesheet" type="text/css" href="https://github.com/patiek/gallerie/blob/master/gallerie.css"/>
<link rel="stylesheet" type="text/css" href="https://github.com/patiek/gallerie/blob/master/gallerie-effects.css"/>

<script type="text/javascript">
$(document).ready(function(){
    $('#gallery').gallerie();
});
</script>

Where you have your thumbnail images linked to originals in your <body>:

<div id="gallery">
    <a href="https://github.com/patiek/gallerie/blob/master/images/myimage.png"><img src="https://github.com/patiek/gallerie/raw/master/thumbs/myimage-thumb.png"/></a>
    <a href="https://github.com/patiek/gallerie/blob/master/images/second.png"><img src="https://github.com/patiek/gallerie/raw/master/thumbs/second_thumb.png"/></a>
    <a href="https://github.com/patiek/gallerie/blob/master/other/facephoto.jpg"><img src="https://github.com/patiek/gallerie/raw/master/other/thumb-facephoto.jpg"/></a>
    <a href="https://github.com/patiek/gallerie/blob/master/images/cat.jpg"><img src="https://github.com/patiek/gallerie/raw/master/images/cat.jpg"/></a>
</div>

You can see example.html for a basic example.

CSS3

Gallerie supports CSS3 use of translate and transition for scrolling if is supported by the browser.

There is also a separate gallerie-effects.css stylesheet that can be included in addition to the standard stylesheet that will use some nice transition and opacity effects when changing images in the gallerie overlay. You can customize these further for greater effect.

Chaining support

Gallerie supports jQuery-style chaining.

Demo

You can find a demo of these on my website.

Options

Gallerie features several options that can be set at initialization or using the .gallerie('option') method.

You can find a full description of the options below. Here is an example of setting all of the options at initialization:

var $gallery = $('#gallery').gallerie({
    thumbboxTriggerWidth: 0.10,
    thumbboxSpeed: 0.5,
    imageEvent: 'click',
    elem: 'a',
    wrapAround: true
});

elem

.gallerie('option', 'elem': selector)

Default: 'a'

Sets the selector that gallerie will use to find anchor elements for images. Gallerie will look use the href attribute of items it finds with this selector as the original image to display in gallerie. It assumes there is an img element inside of the anchor that contains the thumbnail (see example.html).

NOTE: setting elem using the option method may not have desired effect until you call .gallerie('load') method


// typically we set this at initialization, not using option
// only attach to links that have gallery-image class
var $gallery = $('#gallery').gallerie({
    elem: 'a.gallerie-image'
});

wrapAround

value: boolean

Default: true

If set to true, the thumbbox will automatically warp around to the front or end of the list when calling next or previous methods, or when the user advances using keyboard input LEFT and RIGHT keys.

var $gallery = $('#gallery');

// disable wrapAround
$gallery.gallerie('option', 'wrapAround', false);

thumbboxTriggerWidth

value: number

Default: 0.10

Sets the width of the edges of the thumbnail box in the overlay that will cause the thumbnail box to begin to scroll. A value greater than or equal to 1 is assumed to be in pixels. A value of less than 1 is assumed to be a percentage of the total width of the page. Thus, the value 125 will set a 125px width on both sides of the thumbox that will cause the thumbbox to scroll in that direction when the user hovers over the 125px area. A value of 0.10 will set the width to be 10% of the total window width.

var $gallery = $('#gallery');

// change trigger width to be 100 pixels
$gallery.gallerie('option', 'thumbboxTriggerWidth', 100);

thumbboxSpeed

value: number

Default: 0.5

Sets the speed of the thumbbox scroll. This value starts at 0 (no movement) with higher values causing faster movement. You can try increasing/decreasing this value by 0.25 at a time until you are satisfied.

var $gallery = $('#gallery');

// change thumbbox scroll speed to be fast
$gallery.gallerie('option', 'thumbboxSpeed', 2.0);

imageEvent

value: string

Default: 'click'

Sets the event on gallery elements that will cause gallerie to open. Accepts standard jquery event types such as 'click', 'hover', and 'dblclick'.

var $gallery = $('#gallery');

// open gallerie on hover event (because we like to annoy users)
$gallery.gallerie('option', 'imageEvent', 'hover');

Methods

Gallerie features several useful methods that you can call from your own javascript to extend its abilities:

close

The close method will close the gallery overlay.

.gallerie('close')

var $gallery = $('#gallery');

// close the gallery
$gallery.gallerie('close');

isOpen

Returns true or false indicating whether gallerie is open or closed, respectively.

.gallerie('isOpen')

var $gallery = $('#gallery');

// only advance image if gallerie is open
if ($gallery.gallerie('isOpen')) {
    $gallery.gallerie('next');
}

load

The load method can be used to re-load images in the gallery and is useful if you have programatically changed your images after initializing gallerie. Note that images are automatically loaded upon initialization and this method only needs to be called if your images have been modified since first calling .gallerie().

.gallerie('load')

.gallerie('load', element)

The element is the link anchor element that you want to search for and consider as the base of your original image, such as 'a'. If you do not specify an element, gallerie will use the elem specified during its initialization.

var $gallery = $('#gallery');

// perhaps we load another image into our gallery
$image = $('<a href="https://github.com/patiek/gallerie/blob/master/extra-image.jpg"><img src="https://github.com/patiek/gallerie/raw/master/extra-image-thumb.jpg" /></a>');
$gallery.append($image);

// reload the gallery data
$gallery.gallerie('load');

next

Sets the selected image to the next image in the gallery. If wrapAround option is enabled, the next method will wrap around to the beginning of the list after reaching the last image.

.gallerie('next')

var $gallery = $('#gallery');

Go to the next image
$gallery.gallerie('next');

open

The open method will display the gallery overlay.

.gallerie('open')

var $gallery = $('#gallery');

// open the gallery
$gallery.gallerie('open');

.gallerie('open', url|elem|index)

The open tag accepts an optional argument similar to setImage method.

var $gallery = $('#gallery');

// open the gallery to the 4th image
$gallery.gallerie('open', 4);

option

The option method allows you to get or set one or more options. It works similar to JQuery UI's option methods.

See options for the various options available.

.gallerie('option', key)

Gets the value of the option key.

var $gallery = $('#gallery');

// What is our thumbbox trigger width?
var triggerWidth = $gallery.gallerie('option', 'wrapAround');
alert('thumbboxTriggerWidth is ' + triggerWidth);

.gallerie('option', key, value)

Sets the value of the option key to value.

var $gallery = $('#gallery');

// disable wrap-around
$gallery.gallerie('option', 'wrapAround', false);

.gallerie('option', options)

Sets the values of the option keys found in options object to values in options object.

var $gallery = $('#gallery');

// disable wrap-around and make scrolling fast
$gallery.gallerie('option', {'wrapAround', false, 'thumbboxSpeed': 2.0});

previous

Sets the selected image to the previous image in the gallery. If wrapAround option is enabled, the previous method will wrap around to the end of the list after reaching the first image.

.gallerie('previous')

var $gallery = $('#gallery');

Go to the previous image
$gallery.gallerie('previous');

setImage

The set image method will set the image displayed in the gallerie. If the gallerie is open, the thumbnail box will automatically scroll to this image. If the gallerie is closed, it will open to this image when you open it.

The setImage method can accept different argument types including a url, an html element, or the index position of a gallery image.

.gallerie('setImage', url)

var $gallery = $('#gallery');

// load the image from gallery that matches the url
$gallery.gallerie('setImage', 'http://example.com/images/my-image.png');

.gallerie('setImage', elem)

var $gallery = $('#gallery');

// load the first image from gallery with class="facephotos"
var target = $gallery.find('a.facephotos:first')[0];
$gallery.gallerie('setImage', target);

.gallerie('setImage', index)

var $gallery = $('#gallery');

// load the 4th image from gallery
$gallery.gallerie('setImage', 4);

License

Gallerie is open sourced Copyright (c) 2013 Patrick Brown under the MIT License.