Search

Advertisements

Docs

This documentation applies to version 1.0 or higher. For documentation that covers version 0.9.1, go here.

Getting started

Using the Exposure plugin is dead simple, but before you can start using it you need to download it. You also need a copy of jQuery, which you can download form the jQuery website. Exposure is tested to work with jQuery 1.4 or later (and is bundled with jQuery 1.6.4).

When you have downloaded the two libraries you need to include them both (preferably in the head section of your HTML document):

All we need to do now is to apply the magic of Exposure, to do this the plugin needs to know where to find the images. In the example above we gave the list element the id “images“, so we simply tell Exposure to use that list using a simple JavaScript call:

This all you need to do to get Exposure to work. What the gallery should look like and how it should act in different situations is all up to you. For some examples of what you can do with Exposure download the full demo package. To learn more about all of the customization options that Exposure has to offer just keep on reading.

Start with a specific image selected

Exposure always defaults to showing the first image in the gallery, but in some cases you may want to start with a different image. To do this simply add the CSS class “selected” to the image link that you wish to start with instead.

Adding thumbnails

Exposure will by default use scaled down versions of your images to create a clickable list of thumbnails in the gallery. To save bandwith it is a good idea to generate smaller versions of your images yourself instead, and then tell Exposure where to find the thumbnail for each image. This is done by including an img tag inside the image links. This way you can also use thumbnails that uses different format than the larger versions of the images.

Adding your own translation is also quite easy. Simply copy one of existing the localization JavaScript files (it’s recommended to use the English version as a template), open up the copy, and change the text strings to something suitable in your own language. Save your copy, and include it in the same way that we did in the example above.

If you want to contribute to the Exposure project by submitting a translation for your own language send an e-mail to kris@blogocracy.org.

More options

Exposure has a long list of customization options that you can use to configure your gallery to work just the way you want it to. Let’s say that you want to turn off the display of captions and paging controls, using the above example the modified code would look like this:

Use this option to enable “Carousel mode” (thumbnail image carousel type controls instead of the classic paging controls). Defaults to false, will also be set to false if showThumbs is set to false.

controlsTarget

jQuery selector string

Use this option to customize where on the page the paging controls should be displayed.

enableSlideshow

boolean

Use this option to enable or disable the slideshow. Defaults to true.

slideshowControlsTarget

jQuery selector string

Use this option to customize where on the page the slideshow controls should be displayed.

autostartSlideshow

boolean

Use this option to automatically start the slideshow when the gallery is loaded. Defaults to false.

slideshowDelay

number

Use this option to set the amount of time (in milliseconds) each image in the slideshow should be displayed. Defaults to 3000.

onSlideshowPlayed

function

Callback function that is called when the slideshow is played. Use this option to update custom slideshow controls.
Parameters: none.

onSlideshowPaused

function

Callback function that is called when the slideshow is paused. Use this option to update custom slideshow controls.
Parameters: none.

showCaptions

boolean

Use this option to hide or show captions. Defaults to true.

showExtraData

boolean

Use this option to hide or show additional image data. Defaults to true.

dataTarget

jQuery selector string

Use this option to customize where on the page the image data (captions and extra data) should be displayed. Defaults to null, in which case the data container will be appended to the main Exposure target.

onThumb

function

Callback function that is called when a thumbnail is displayed. Use this option to add effects when a thumbnail image is loaded.
Parameters:

thumb – thumbnail element that was loaded

onImage

function

Callback function that is called when an image is displayed. Use this option to add effects when switching between images. Defaults to simply removing the previous image.
Parameters:

image – image element being loaded

imageData – image data container element

thumb – thumbnail element for the loaded image

onImageHoverOver

function

Callback function that is called when the mouse enters the displayed image.

onImageHoverOut

function

Callback function that is called when the mouse leaves the displayed image.

onCarousel

function

Callback function that is called when browsing image carousel. Can be used to add transition effects in “Carousel mode”.

onNext

function

Callback function that is called when browsing to the next image. Can be used to integrate with thumbnail scrollers.
Parameters: none.

onPrev

function

Callback function that is called when browsing to the previous image. Can be used to integrate with thumbnail scrollers.
Parameters: none.

onPageChanged

function

Callback function that is called when browsing to a different page (is not called in “Carousel mode”). Can be used to add customized effects when using your own paging controls. Defaults to simply showing all the thumbnails on the current page.
Parameters: none.

onPagingLink

function

Callback function that is called when a paging link is created. Can be used to create your own custom links. Must return the created link. Parameters:

link – The newly created link.

separatePageBrowsing

boolean

Use this option to enable separate browsing of pages (browse through pages without changing the image being displayed). Defaults to false.

loop

boolean

Use this option to start over when last image is reached. Defaults to true.

onEndOfLoop

function

Callback function that is called when the last image is reached and loop option is set to false. Can be used to add a custom message when the last image in the gallery is reached. Parameters: none.

viewFirstImage

boolean

Use this option to turn off automatic viewing of the first image in the gallery. Defaults to true.

pageSize

number

Use this option to control the number of of images (thumbnails) to display per page. Defaults to 5.

visiblePages

number

Use this option to control the number of pages displayed in the paging control. Defaults to 5.

preloadBuffer

number

Use this option to increase or decrease the maximum number of images that is preloaded at any given time. Defaults to 3.

keyboardNavigation

boolean

Use this option to disable or enable keyboard navigation. Defaults to true.

clickingNavigation

boolean

Use this option to disable or enable browsing by clicking on the image being shown. Defaults to true.

fixedContainerSize

boolean value

Use this option to prevent Exposure from automatically resizing the target element to the size of the current photo. Defaults to false.

maxWidth

number

Use this option to set a maximum width for the images in the gallery (larger images will be downscaled). Defaults to null.

maxHeight

number

Use this option to set a maximum height for the images in the gallery (larger images will be downscaled). Defaults to null.

stretchToMaxSize

boolean

Use this option to stretch all images in the gallery to the defined maxWidth and maxHeight. Defaults to false.

fullScreen

boolean

Use this option to set the maximum width and height to the window size. If combined with stretchToMaxSize images will be stretched to max window size. Defaults to false.

onEnterFullScreen

function

Callback function that is called when full screen mode is entered. Can be used to add maks fading or other similar effects. Defaults to showing the mask. Parameters:

mask – Mask element that is used to mask the content “behind” the viewed image.

onExitFullScreen

function

Callback function that is called when full screen mode is entered. Can be used to update thumbnails or to add other effects. Defaults to hiding the target and mask elements. Parameters:

target – The Exposure target element.

mask – Mask element that is used to mask the content “behind” the viewed image.

showThumbToolTip

boolean value

Use this option to prevent Exposure from automatically adding image captions as tool tip texts for thumbnails. Defaults to true.

onEmpty

function

Callback function that is called if the gallery is empty after the initial loading of the plugin. Defaults to removing controls and targets and to hiding the list element that the plugin is called on. Can be used to dynamically load images from other sources.
Parameters:

gallery – reference object for the actual gallery

onInit

function

Callback function that is called after that gallery has been initially loaded. Can be used to add custom loading effects.
Parameters: none.

allowDuplicates

boolean value

Use this option to prevent Exposure from images with the same image source. Defaults to true.

jsonSource

JSON data string/URL to JSON data/JSON object

Load additional images from an external source using JSON. Read more about this option under “Alternate input sources” below. Defaults to null.

If you want to customize your gallery even further, read on and learn how to create your own Exposure controls using the public functions.

Public functions

Exposure also has a set of public functions that you can use to build your own custom controls. When you invoke Exposure on a list element the plugin will append these public functions to the functions available for that element. So in order to invoke these functions you need to keep a reference to your list element:

var gallery = $('#images');
gallery.exposure();

Now let’s say that you want to create your own “Next image” button. All you have to is to create a normal hyperlink and then add a call to the nextImage() function from the link’s onclick event. The code for such a link would look like this:

Check if the page currently being viewed is the first page of the viewer.

none

atLastPage

Check if the page currently being viewed is the last page of the viewer.

none

firstImageOnPage

Check if a specific image is the first image of its page.

index (number): Index of the image to check. Will default to index of current image if left undefined.

lastImageOnPage

Check if a specific image is the last image of its page.

index (number): Index of the image to check. Will default to index of current image if left undefined.

currentPageNumber

Get the number of the page currently being viewed.

none

numberOfImages

Get the total number of images in the viewer.

none

atFirstPage

Check if the image currently being viewed is the first image of the viewer.

none

atLastPage

Check if the image currently being viewed is the last image of the viewer.

none

getImage

Get the image object for a specific image. The image object has the following properties:

src (string) – full source URL for the image

thumb (string) – full source for the image thumbnail

caption (html) – image caption

data (html) – additional image data

loaded (boolean) – check if the image has been loaded or not

Usage: var firstImageUrl = $.exposure.getImage(0).src;

index (number): Index of the image to get.

indexOfImage

Get the index of a specific image by URL. If allowDuplicates is set to true and there are more than one image with the same URL the first index of the first image will be returned.

src (string): Full image URL for the image to get index for.

currentImage

Get the index of the image currently being viewed.

none

addImage

Dynamically add an image to the gallery (the new image will be put last).

src (string) – full source URL for the image

thumb (string) – full source for the image thumbnail

caption (html) – image caption

data (html) – additional image data

removeImage

Dynamically remove a certain image from the gallery.

index (number): Index of the image to remove.

removeAllImages

Dynamically remove all the images from the gallery.

none

getThumb

Get the <img> tag for the thumbnail for a specific image.

index (number): Index of the image to get the thumbnail element for.

getNextImage

Get the index of the next image.

none

getPrevImage

Get the index of the previous image.

none

goToPage

Tell Exposure to view a specific page.

page (number): Number of the page to show.

imageToView (number): Set if you desire to view a specific image on the image. Otherwise leave undefined.

firstPage

View the first page.

none

lastPage

View the last page.

none

prevPage

View the previous page.

none

nextPage

View the next page.

none

viewImage

View a specific image.

index (number): Index of the image to view.

nextImage

View the next image.

none

prevImage

View the previous image.

none

imageHasData

Check if the current image has any displayed caption or additional image data.

none

playSlideshow

Start the slideshow.

none

pauseSlideshow

Stop the slideshow.

none

toggleSlideshow

Toggle the slideshow (if started, stop it – if stopped, start it).

none

first

View the first page/image (depending on imageControls) setting.

none

prev

View the previous page/image (depending on imageControls) setting.

none

next

View the next page/image (depending on imageControls) setting.

none

last

View the last page/image (depending on imageControls) setting.

none

exitFullScreen

Leave full screen mode.

none

fitToWindow

Fit slideshow images to current window size (used in full screen mode).

none

Selector classes

Exposure uses a bunch of special CSS classes to keep track of its elements. You can think of them as constants. When implementing your own callback functions or using the public functions to create custom controls it is recommended that you use these constants to reference the different elements. You reach them through the static exposure object, like this:

Main images (use currentImageClass to find the currently displayed main image)

imageHoverClass

exposureHover

Marker class for when the user hovers the mouse over the current main image (used for sliding captions effect etc.)

selectedImageClass

selected

Marker class for the thumbnail of the currently selected image

activeThumbClass

active

Marker class for the container of the thumbnail of the currently selected image

currentThumbClass

current

Marker class for thumbnail containers of images that are on the currently displayed page

firstThumbClass

first

Marker class for the thumbnail container of the first image on the currently displayed page

lastThumbClass

last

Marker class for the thumbnail container of the last image on the currently displayed page

loadedClass

loaded

Marker class for the target element when the currently displayed image has been loaded (use to hide loading indicators)

activeLinkClass

active

Marker class for the currently selected page inside the paging element

disabledLinkClass

disabled

Marker class for disabled paging control links

Public elements

To make it even easier to reference some of the above mentioned element you can also reach them as public properties of your gallery element (see Public functions section). An example:

// Hide the target element.
gallery.targetElement.hide();

Element name

Description

targetElement

Target element for the main image

wrapper

Wrapper element for the main image

dataElement

Data wrapper element (contains both caption and additional data)

mask

Mask element (used in modal mode)

Alternate input sources

You can also add images from other sources than the actual markup. This is done by passing JSON data to Exposure using the jsonSource option. The jsonSource option can accept three different types of input; a data string, a URL or a JSON object.

The JSON data passed to Exposure must be strictly formatted according to the following structure:

Any occurrences of the double quote character inside the property values (for instance when building HTML tags with attributes in “extra_data” property) must be escaped using three backslashes, like this:

In this example the JSON data is embedded in a long string (notice the single quotes in the beginning of each line). Using this example we will add two additional images to the gallery. Both images have a caption, and the second image also has additional content (in the form of a link, with escaped double quotes). Since “extra_data” is an optional property it doesn’t need to be listed with the properties of the first image (only the “source” property is actually required) .

This is perhaps the most useful type to pass to the jsonSource, since it really lets you use images from an external source. Just supply Exposure with a URL that returns a JSON response, and Exposure will fetch that response using AJAX and parse it.