Docs for Exposure 0.9.1

For documentation that applies to the most recent version of Exposure 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.5.1).

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

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 15 languages (Arabic, Brazilian Portuguese, Catalan, Czech, Dutch, English, Finnish, French, German, Greek, Italian, Russian, Simplified Chinese, Spanish and Swedish) 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.5.1.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:

  1. 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:

  1. image – image element being loaded
  2. imageData – image data container element
  3. thumb – thumbnail element for the loaded 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:

  1. 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:

  1. 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:

  1. target – The Exposure target element.
  2. 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: none.
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. 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:

<a href="javascript:void(0);" onclick="$.exposure.nextImage();">Next image</a>

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

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>
Advertisements