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):

<script src="jquery-1.6.4.min.js" type="text/javascript"></script>
<script src="jquery.exposure.js" type="text/javascript"></script>

The next step is to include some images that Exposure can display. This is done by adding an HTML list element that contains list items that holds links to the images that you wish to display:

<ul id="images">
	<li><a href="myfirstimage.jpg"></a></li>
	<li><a href="mysecondimage.jpg"></a></li>
</ul>

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:

<script type="text/javascript">
$(function(){
	$('#images').exposure();
});
</script>

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.

<ul id="images">
	<li><a href="myfirstimage.jpg"></a></li>
	<li><a href="mysecondimage.jpg" class="selected"></a></li>
</ul>

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.

<ul id="images">
	<li>
		<a href="myfirstimage.jpg"  title="My first image"><img src="thumbs/myfirstimage.jpg" /></a>
	</li>
	<li>
		<a href="mysecondimage.jpg" title="My second image"><img src="thumbs/mysecondimage.jpg" /></a>
	</li>
</ul>

An alternative way of achieving the same thing is to add a rel attribute that points to where the thumbnail can be found to the image links.

<ul id="images">
	<li>
		<a href="myfirstimage.jpg"  title="My first image" rel="thumbs/myfirstimage.jpg"></a>
	</li>
	<li>
		<a href="mysecondimage.jpg" title="My second image" rel="thumbs/mysecondimage.jpg"></a>
	</li>
</ul>

Adding captions

To add a captions to your images. Just add a title attribute containing the caption to each link in the images list:

<ul id="images">
	<li><a href="myfirstimage.jpg" title="My first image"></a></li>
	<li><a href="mysecondimage.jpg" title="My second image"></a></li>
</ul>

When using thumbnails, an alternative solution is to add the title attribute to thumbnail img tag instead of to the image link.

<ul id="images">
	<li>
		<a href="myfirstimage.jpg"><img src="thumbs/myfirstimage.jpg" title="My first image" /></a>
	</li>
	<li>
		<a href="mysecondimage.jpg"><img src="thumbs/mysecondimage.jpg" title="My second image" /></a>
	</li>
</ul>

The captions only allows the use of some very basic HTML (like <br /> tags etc.). For more complex HTML needs see the “Adding additonal content” section below.

Adding additional content (links, display metadata etc.)

You can add any extra information you want to each image. This is done by filling the li elements that contains the image links with any HTML content:

<ul id="images">
	<li>
		<a href="myfirstimage.jpg" rel="thumbs/myfirstimage.jpg" title="My first image"></a>
		<strong>Metadata</strong><br />Aperture: 5.6<br />Shutter speed: 1/200
	</li>
	<li>
		<a href="mysecondimage.jpg" rel="thumbs/mysecondimage.jpg" title="My second image"></a>
		<a href="http://facebook.com">Link to Facebook</a>
	</li>
</ul>

Keyboard navigation

The built in keyboard navigation in Exposure is powered by the jQuery Hotkeys Plugin by John Resig.

Here’s the full list of the currently supported actions in Exposure:

Left arrow – Previous photo
Right arrow – Next photo
Up arrow – Last photo (*)
Down arrow – First photo (*)
Ctrl+Left arrow – Next page (*)
Ctrl+Right arrow – Previous page (*)
Ctrl+Up arrow – Last page (*)
Ctrl+Down arrow – Last page (*)
Space – Play/pause slideshow

(*) Not supported in carousel mode.

For instructions on how to add your own custom actions see the jQuery Hotkeys plugin website.

Using localization

Exposure can speak any language in the world. The download package currently comes with 18 languages (Arabic, Brazilian Portuguese, Catalan, Czech, Dutch, English, Finnish, French, German, Greek, Italian, Polish, Russian, Simplified Chinese, Spanish, Swedish, Turkish, and Urdu) but you can easily add your own language. Just read on!

To use one of the languages included in the download bundle is dead simple. Just include the JavaScript file from the localization folder for the language that you want to use.

<script src="jquery-1.6.4.min.js" type="text/javascript"></script>
<script src="jquery.exposure.js" type="text/javascript"></script>
<script src="localization/texts_de.js" type="text/javascript"></script>

This example is will result in a gallery that’s translated to German.

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.

Here’s what the plain English translation would look like:

/**
* Exposure plugin texts translated to English.
*/
jQuery.extend(jQuery.exposure.texts, {
	first : "First",
	previous : "Prev",
	next : "Next",
	last : "Last",
	play : "Play slideshow",
	pause : "Pause slideshow"
});

…and here’s a Swedish translation of the same texts:

/**
 * Exposure plugin texts translated to Swedish.
 */
jQuery.extend(jQuery.exposure.texts, {
	first : "F&ouml;rsta",
	previous : "F&ouml;rra",
	next : "N&auml;sta",
	last : "Sista",
	play : "Starta bildspel",
	pause : "Stoppa bildspel"
});

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:

<script type="text/javascript">
$(function(){
	$('#images').exposure({showCaptions : false, showControls : false});
});
</script>

Here’s the complete list of available options:

Option	Type	Description
target	jQuery selector string	Use this option to customize where on the page the main image should be displayed. Defaults to ‘#exposure’. If no target is found, one will be created.
showThumbs	boolean	Use this option to hide or show thumbnails. Defaults to true.
showControls	boolean	Use this option to hide or show paging controls. Display paging controls or not. Defaults to true, but will be set to false if missing controlsTarget or if carouselControl is set to true.
imageControls	boolean	Use this option to tie the paging controls to images instead of pages (for example “Next” will mean “next image” instead of “next page”. Defaults to false.
controls	object	Use this option to choose which of the paging controls to display. All controls default to true. Usage example (that hides First/Last but displays the rest): controls : { prevNext : true, pageNumbers : true, firstLast : false }
carouselControls	boolean	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:

HTML (put anywhere on your page):

<a href="javascript:void(0);" class="next">Next image</a>

JavaScript:

$(function() {
    var gallery = $('#images');
    gallery.exposure();
    $('.next').click(function() {
        gallery.nextImage();
    });
});

Here’s the complete list of available public functions:

Function	Description	Prameters
pageNumberForImage	Get the page number of a specific image.	index (number): Index of the image to get page number for.
numberOfPages	Get the total number of pages in the viewer.	none
atFirstPage	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:

// Hide the thumbnail of the currently selected image.
var thumbs = gallery.find('li.' + $.exposure.currentThumbClass);
thumbs.hide();

The available classes are:

Reference variable name	Class name	Description
wrapperClass	exposureWrapper	Wrapper element for the main image
targetClass	exposureTarget	Target element for the main image
currentImageClass	exposureCurrentImage	Marker class for the currently selected main image (used for cross-fading)
lastImageClass	exposureLastImage	Marker class for the last selected main image (used for cross-fading)
captionClass	caption	Caption container element
imageDataClass	extra	Additional data container element
dataContainerClass	exposureData	Data wrapper element (contains both caption and additional data)
controlsClass	exposureControls	Navigation controls element (contains prev, next etc. and paging controls)
slideshowControlsClass	exposureSlideshowControls	Slideshow controls element (contains play/pause slideshow controls)
firstPageClass	exposureFirstPage	“First” button
prevPageClass	exposurePrevPage	“Prev” button
nextPageClass	exposureNextPage	“Next” button
lastPageClass	exposureLastImage	“Last” button
pagingClass	exposurePaging	Paging container element
pagingClass	exposurePaging	Paging container element
playSlideshowClass	exposurePlaySlideshow	“Play slideshow” button
pauseSlideshowClass	exposurePauseSlideshow	“Pause slideshow” button
maskClass	exposureMask	Mask element (used in modal mode)
thumbsClass	exposureThumbs	Thumbnail container element
imageClass	exposureImage	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:

{
	"data" : [
		// First image
		{
			// Required property
			"source" : "URL to first image",
			// Optional properties
			"thumb_source" : "URL to thumbnail for first image",
			"caption" : "Caption for first image",
			"extra_data" : "Additional content for first image"
		},
		// Second image
		{
			"source" : "URL to second image",
			"thumb_source" : "URL to thumbnail for second image",
			"caption" : "Caption for second image",
			"extra_data" : "Additional content for second image"
		}
		// etc.
	]
}

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:

"extra_data" : "<a href=\\\"http://exposure.blogocracy.org\\\">Exposure website</a>"

JSON data string

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) .

<script type="text/javascript">
$(function(){
	$('#images').exposure({
		jsonSource : '{' +
			'"data" : [' +
				'{' +
					'"source" : "http://exposure.blogocracy.org/testing/json/slides/Base balls.jpg",' +
					'"thumb_source" : "http://exposure.blogocracy.org/testing/json/thumbs/Base balls.jpg",' +
					'"caption" : "Plenty of base balls"' +
				'},' +
				'{' +
					'"source" : "http://exposure.blogocracy.org/testing/json/slides/Football.jpg",' +
					'"thumb_source" : "http://exposure.blogocracy.org/testing/json/thumbs/Football.jpg",' +
					'"caption" : "Footballer ready for action",' +
					'"extra_data" : "<a href=\\\"nfl.com\\\">Go to NFL.com</a>"' +
				'}' +
			']' +
		'}'
	});
});
</script>

The JSON data string will be parsed into a JSON object using jQuery’s parseJson function.

JSON data object

This example is very similar to the one above, but here the data isn’t embedded in a string, it’s a JSON data object. If you already have a parsed JSON object you can send that into Exposure directly.

<script type="text/javascript">
$(function(){
	$('#images').exposure({
		jsonSource : {
			"data" : [
				{
					"source" : "http://exposure.blogocracy.org/testing/json/slides/Base balls.jpg",
					"thumb_source" : "http://exposure.blogocracy.org/testing/json/thumbs/Base balls.jpg",
					"caption" : "Plenty of base balls"
				},
				{
					"source" : "http://exposure.blogocracy.org/testing/json/slides/Football.jpg",
					"thumb_source" : "http://exposure.blogocracy.org/testing/json/thumbs/Football.jpg",
					"caption" : "Footballer ready for action",
					"extra_data" : "<a href=\\\"nfl.com\\\">Go to NFL.com</a>"
				}
			]
		}
	});
});
</script>

The JSON object can also be passed in as a variable. In the example the variable is called “images”.

<script type="text/javascript">
$(function(){
	var images = {
		"data" : [
			{
				"source" : "http://exposure.blogocracy.org/testing/json/slides/Base balls.jpg",
				"thumb_source" : "http://exposure.blogocracy.org/testing/json/thumbs/Base balls.jpg",
				"caption" : "Plenty of base balls"
			},
			{
				"source" : "http://exposure.blogocracy.org/testing/json/slides/Football.jpg",
				"thumb_source" : "http://exposure.blogocracy.org/testing/json/thumbs/Football.jpg",
				"caption" : "Footballer ready for action",
				"extra_data" : "<a href=\\\"nfl.com\\\">Go to NFL.com</a>"
			}
		]
	};
	$('#images').exposure({jsonSource : images});
});
</script>

URL to JSON data

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.

See http://exposure.blogocracy.org/testing/json/photos.js for an example of a proper JSON response. Please note that the AJAX call made by Exposure is a GET type call.

$(function(){
	$('#images').exposure({jsonSource : 'http://exposure.blogocracy.org/testing/json/photos.js'});
});
</script>

Exposure jQuery plugin

What is Exposure?

Support the project

Recent posts

Links

Search

Docs

Getting started

Start with a specific image selected

Adding thumbnails

Adding captions

Adding additional content (links, display metadata etc.)

Keyboard navigation

Using localization

More options

Public functions

Selector classes

Public elements

Alternate input sources

What is Exposure?

Support the project

Recent posts

Links

Search

Docs

Getting started

Start with a specific image selected

Adding thumbnails

Adding captions

Adding additional content (links, display metadata etc.)

Keyboard navigation

Using localization

More options

Public functions

Selector classes

Public elements

Alternate input sources

Share this: