Gallery slideshow

Navigation

Skip navigation.

Site search

Site navigation

Details and download

Contents

The script

This script takes an accessible HTML-based image gallery, and turns it into a slideshow, allowing users to quickly step to the previous/next images. It works by taking the thumbnail and associated text captions from a series of links, for use in the slideshow. It then either overlays the slideshow on top of the normal document contents (effectively replacing the page), or embeds it within a chosen element.

In its simplest form, it can be used with very little configuration on your part. However, it is highly configurable and stylable, and can be used in a large variety of arrangements, with an API that allows you to control and monitor it from your scripts. If you need a less flexible script that does not use thumbnails, then you should use the simple gallery script instead.

This is a DOM-based script that will work in almost all DOM capable browsers. Some older browsers work with some cosmetic issues, such as IE 5.5-6 having odd overlaps with some configurations. Some older browsers (Opera 8-, IE 5.5-6, iCab 3, NetFront) may not be able to scroll the thumbnails independently, and may have reduced functionality, such as shrink-to-fit not working, but the basic parts of the script remain functional.

Demos

Page-replacing (original format) demo

Start a slideshow using the following gallery:

Note: if the images are ugly, it's just because I made ugly images. The script does not attempt to change or resize images in any way, unless you enable shrink-to-fit.

Embedded demo

This demo is styled and configured to replicate a certain popular gallery. You may wish to view the source code of the page to see the very small amount of JavaScript that is used to configure it, and the relatively small amount of CSS that is used to style it.

Automatic slideshow Hide captions

The image counter and the buttons on the bottom-right are not provided by the script itself, but use the API exposed by the script to provide extra functionality. The counter uses the onchange callback to update the count, the captions button simply uses getShowCaption and showCaption to toggle captions if there is no transition happening, and the automatic slideshow button simply calls the showNext method using an interval timer.

Instructions

To download the script(s), see the script license, and check details like browser compatibility, use the links on the navigation panel at the top of this page.

Download the script, then inbetween the <head> tags, put:

<script src="PATH TO SCRIPT/galleryslideshow.js" type="text/javascript"></script>

Make sure that each thumbnail is a regular HTML IMG element, inside a regular link (A element), which points directly to the full sized image. Make sure that any descriptive text that you want it to use as an associated text caption is also written inside the link. This is the normal approach for many thumbnail-based galleries. As an example, the following markup will work with the script:

<ul id="mygallery">
  <li><a href="bigfoo.jpg"><img src="smallfoo.jpg" alt=""> A foo</a></li>
  <li><a href="bigbar.jpg"><img src="smallbar.jpg" alt=""> A bar</a></li>
</ul>

The script will assume that the first image it finds inside a link is the thumbnail. It will also assume that any link it locates (within the contents of the element or collection used when calling the prepareImagesFrom* methods), that contains an image, is a link to the full sized image. Any contained markup is ignored when locating associated text.

Although the script can be initialised at any time, searching for thumbnails can only be done once the parser has created all the required elements. As a result, it's best to run the script either from an onload event handler, or an equivalent that ensures they will have been created.

The script has one main class used to initialise the slideshow. The class creates a GallerySlideshow Object which has the methods needed to display and control the slideshow. In its simplest form, running the script looks like this:

window.onload = function () {
  var mySlideshow = new GallerySlideshow();
  mySlideshow.prepareImagesFromElement(document);
  mySlideshow.showSlideshow();
};

However, if you make the script replace the page instead of embedding within it, it is best to call it only when the user requests it, so that when they close it, it returns to the basic gallery format. This can be done through a normal function call. That same function could also select an initial image to display. This defaults to 0 (the first image), but if the user closes and re-opens the slideshow, it will remember the last image they looked at:

var mySlideshow;
window.onload = function () {
  mySlideshow = new GallerySlideshow();
  //protect old browsers
  if( mySlideshow.canWork() ) {
    mySlideshow.prepareImagesFromElement(document.getElementById('mygallery'));
  }
};
function openslideshow() {
  if( !mySlideshow ) { return; }
  mySlideshow.setCurrent(3); //4th image
  mySlideshow.showSlideshow();
}

A simple change to the above code could be used to open the slideshow to display the selected image when the user clicks a thumbnail:

var mySlideshow;
window.onload = function () {
  mySlideshow = new GallerySlideshow();
  //protect old browsers
  if( mySlideshow.canWork() ) {
    mySlideshow.prepareImagesFromElement(document.getElementById('mygallery'));
  }
};
function openslideshow(startImg) {
  if( !mySlideshow || !mySlideshow.canWork() ) { return true; }
  mySlideshow.setCurrent(startImg);
  mySlideshow.showSlideshow();
  return false;
}
...
<ul id="mygallery">
  <li><a href="bigfoo.jpg" onclick="return openslideshow(0);"><img src="smallfoo.jpg" alt=""> A foo</a></li>
  <li><a href="bigbar.jpg" onclick="return openslideshow(1);"><img src="smallbar.jpg" alt=""> A bar</a></li>
</ul>

Or to enable keyboard support:

var mySlideshow;
window.onload = function () {
  mySlideshow = new GallerySlideshow();
  //protect old browsers
  if( mySlideshow.canWork() ) {
    mySlideshow.prepareImagesFromElement(document.getElementById('mygallery'));
  }
};
function openslideshow() {
  if( !mySlideshow ) { return; }
  mySlideshow.setKeyPrev(true);
  mySlideshow.setKeyNext(true);
  //this example uses Shift+Esc to close
  mySlideshow.setKeyClose(27,true,false,false,false);
  mySlideshow.showSlideshow();
}

A slideshow can be opened and closed as many times as needed, and can have its list of images repopulated multiple times (if a slideshow is already showing, repopulating it will also cause it to close). However, populating the list of images is quite expensive in terms of performance, so it's best to populate it just once, and show it whenever it is needed. Multiple slideshows can be created on the same page, but the script will only allow one of them to be displayed at any time if they are replacing the page instead of being embedded within it. Each slideshow can only be shown once at a time - although the same images can be used in multiple slideshows, the same GallerySlideshowObject cannot be displayed in more than one place on the page at any given time.

For best results, do not set the border, margin, or padding styles on the HTML or BODY elements using the STYLE attribute, if any slideshow will replace the page. If those styles are needed in your normal page style, they should be set using a normal stylesheet instead.

To embed the slideshow in the page instead of replacing it, simply provide the a reference to the element that you want to embed it in, as the first parameter to showSlideshow. The following example embeds a slideshow in the page, with thumbnails at the bottom instead of the top, with a shrink-to-fit checkbox (initially set to shrink images to fit), with a loop message displayed when the user reaches the end of the gallery:

window.onload = function () {
  var mySlideshow = new GallerySlideshow();
  //protect old browsers
  if( mySlideshow.canWork() ) {
    mySlideshow.prepareImagesFromElement(document.getElementById('mygallery'));
    mySlideshow.setThumbPosition(false);
    mySlideshow.shrinkToFit(true);
    mySlideshow.showShrinkToggle(true);
    mySlideshow.setLooping(true,true);
    if( mySlideshow.showSlideshow(document.getElementById('slidearea')) ) {
      document.getElementById('mygallery').style.display = 'none';
    }
  }
};
...
<div id="slidearea"></div>

Transitions

The script supports two basic transitions when changing images, which can be selected and combined using the setTransitions method. The duration of the transition animations can be adjusted using the setTransitionDuration method. It is important to keep this quite low, since the thumbnails, next/previous links and keyboard shortcuts will remain unresponsive while a transition is playing. Although upto 120000 ms (2 minutes) of transition time is allowed, users will probably find that far too long, and will become frustrated with the slow response. The default is 500 ms (0.5 seconds), and you are advised not to use anything higher than that. Note that transitions can be quite CPU intensive, and will become quite choppy on less powerful hardware or on browsers with a slower response to clipping or opacity. For the vast majority of users, however, they will play smoothly enough.

When using transitions, the script overlays the previous slide on top of the new slide, and slowly removes it. It will work best with images that are similar in size, and do not require scrolling to see them completely (though it will work with images of any size). If the images may be of different sizes, or have associated text captions, you should ensure that the slideimage container DIV has a background colour set, to prevent the underlying image showing around the edges. If you are embedding the slideshow, and your images may be of different sizes, you should also ensure that the slideimage container has a fixed height, or the transition will overlay surrounding content. The clip transition effect works best when used on images that are approximately the same size as the slideimage container, and is best suited to slideshows that are embedded within the current page, as a result.

The script does not attempt to cache the new image before starting a transition, as that would cause the slideshow to become unresponsive while waiting for images to load. However, this can produce an undesirable effect as the image loads while the transition is playing. To produce the best effect, you should use setCacheNext and setCachePrev when using transitions.

Some of the methods exposed by the API will not function normally while a transition is playing; specifically the setCurrent, showPrevious, showNext, shrinkToFit and showCaption methods. In all cases, a normal call to these methods will not perform any function while a transition is playing. However, all of these methods accept an optional parameter that will cause them to cancel any transition that is currently playing, and apply their changes without triggering a new transition.

DHTML scrolling buttons

By default, the script uses a standard scrollbar provided by the browser to scroll through the available thumbnails. If this does not suit your design, you can use the setThumbScrollbar method to make the script use a DHTML layer to contain the thumbnails, with buttons to scroll through them. This is a fairly minimal approach to scrolling, but that is intentional because if you want the functionality of a scrollbar, then you should be using a real scrollbar, not a DHTML version. Real scrollbars have the benefit of being completely familiar for the user, and providing interactions for multiple input devices in a way that is consistent with their chosen platform. The DHTML layer approach also uses a little more processing power. You are encouraged to use normal scrollbars instead of the DHTML layer approach.

Choosing keys to use for shortcuts

By default, the script does not add any keyboard shortcuts. The user can still use Tab, spatial navigation, or keyboard shortcuts (depending on what the browser provides) to focus the various links, and then activate them to display their chosen images. However, you can use the keyboard support to provide more convenient keys, using the methods setKeyNext, setKeyPrev, setKeyClose, setKeyShrink and setKeyCaption. By default, they use Space, Shift+Space, Esc, Shift+S and Shift+C. You are strongly urged to use only these defaults.

Be warned that if you have multiple slideshows showing on one page, and they are all set up to use the same keys, they will all respond simultaneously when the user presses those keys. Enabling keyboard shortcuts for embedded slideshows could cause conflicts with normal keyboard interaction on that page, such as making it impossible to type in inputs. The script attempts to minimise these conflicts, but cannot cope with all possible situations. You are advised to enable keyboard support only for slideshows that replace the page, or are the main content of a page. You are advised not to enable any keyboard shortcut for closing an embedded slideshow, or it will disappear when the user presses that key, without necessarily providing any way for them to get it back.

There are several keys that you should avoid using. These include arrow keys (which are used for scrolling large images, or combined with Shift or Ctrl for spatial navigation), Page up/down (also used for scrolling large images), Enter/Return, other non-printing character keys (Tab, Insert, F5, Backspace, etc.), non-ascii character keys, etc. Even regular character keys and numbers are often already in use by several browsers as keyboard shortcuts, and it is best not to cause conflicts with those. The default keyboard shortcuts are already established as normal keyboard shortcuts used for native gallery displays in some browsers, and are therefore the most appropriate keys to use.

To work out the key codes for your chosen key, put your cursor in the following input, and press your chosen keys (keyboard users can use Esc to get back out of the input): (JavaScript needs to be enabled to use this tool.) Remember to test in multiple browsers to ensure that they have all chosen the same code. Also check the same shortcut in that browser without the input focused, to see if it conflicts with a default shortcut.

Note that no visual indicators are provided to let the user know what keyboard shortcuts are available. You may want to provide appropriate text for the links, to show what the available shortcuts are, using the parameters of the showSlideshow method:

mySlideshow.showSlideshow( '<< Previous (Shift+Space)', 'Next (Space) >>', 'Close slideshow (Esc)' );

API documentation

Create a GallerySlideshowObject using:

mySlideshow = new GallerySlideshow()
GallerySlideshowObject.prepareImagesFromCollection( Collection )
Searches for all links containing thumbnails within the collection, and uses the results to create the slideshow. Note that calling this method will close the slideshow if it is currently being displayed, and will also reset the current index to 0. Returns the number of images found for use in the slideshow, or false if the browser is not capable of running the script. This method must not be called until all relevant elements have been created by the parser.
Collection
Array or DOM NodeList: either an array where each cell contains an A element, or a DOM NodeList (the sort of thing returned by the getElementsByTagName method) of A elements.
GallerySlideshowObject.prepareImagesFromElement( Element )
Searches for all links containing thumbnails within the given element, and uses the results to create the slideshow. Note that calling this method will close the slideshow if it is currently being displayed, and will also reset the current index to 0. Returns the number of images found for use in the slideshow, or false if the browser is not capable of running the script. This method must not be called until all relevant elements have been created by the parser.
Element
Object: either a DOM element node or the document object.
GallerySlideshowObject.setCurrent( Index[, BlockTransitions] )
Shows the image at the specified index in the slideshow. If the slideshow is not currently showing, this affects which image will be shown when the slideshow is started. Has no effect if a transition is playing, unless the optional BlockTransitions parameter is set to true. If this method is not called before showing a slideshow, the first image in the slideshow will be displayed by default. If the slideshow is then reshown later, it will remember the last image that was shown. Returns the current index number, which may not be the same as the desired value, if the desired value is less than 0 or higher than the maximum available index, or if a transition was playing.
Index
Integer: the index of the desired image to show. Index is 0 based, so to show the first image, the index value should be 0.
BlockTransitions
Optional Boolean: true to cancel any transitions that are playing and apply the change without triggering a new transition, false has no effect.
GallerySlideshowObject.showPrevious( [BlockTransitions] )
GallerySlideshowObject.showNext( [BlockTransitions] )
Shows the previous or next image in the slideshow. If the slideshow is not currently showing, this affects which image will be shown when the slideshow is started. By default, this wraps around at the start to show the last image, and at the end to show the first image. Has no effect if a transition is playing, unless the optional parameter is set to true. Returns the current index number. The index will be the same as the number of images in the slideshow if the loop message is being displayed (one more than the maximum index that can be used with setCurrent).
BlockTransitions
Optional Boolean: true to cancel any transitions that are playing and apply the change without triggering a new transition, false has no effect.
GallerySlideshowObject.setLooping( Allowed[, WithMessage] )
Sets whether looping will be allowed between the first and last images in the gallery when the user attempts to show the previous/next images. Optionally, it can enable looping but cause a message to be displayed to the user, telling them that they have reached the end of the gallery. When looping is disabled, the previous/next links will be given the additional CSS class notenabled to facilitate styling, when the relevant end of the gallery has been reached. For best results, it should only be called before calling showSlideshow (although it can be called afterwards, the previous/next links may not be styled correctly until the user selects another image to display). By default, looping is allowed, and no message will be shown to the user.
Allowed
Boolean: true to allow the user to loop between the first and last images, false to prevent looping.
WithMessage
Optional Boolean: true to display a message to the user when they reach the end of the gallery, false to loop without any message. This parameter has no effect if the Allowed parameter is false. Defaults to false.
GallerySlideshowObject.setThumbPosition( Position )
Sets whether the thumbnail strip should be positioned above the currently displaying slide, or below it. Setting thumbnails to display below the slide can make it more difficult to use with a keyboard, since the viewport scrollbars are no longer used, and instead, CSS scrollbars are used on the slide when needed. The order of the slidelist and slideimage containers will be reversed in the source. Returns true if the setting was accepted, or false if it was rejected because the method was called while the slideshow was already being shown. By default, thumbnails are placed above the slide.
Position
Boolean: true to position the thumbnails above the slide, false to position them below it.
GallerySlideshowObject.setThumbScrollbar( Enabled )
Sets whether the thumbnail strip should use a native scrollbar when it does not have enough space to fit all of the thumbnails. If the scrollbar is disabled, it will use DHTML layers and buttons instead. This adds extra markup, including the slideleft and slideright links, which serve as the buttons. They will be given the additional CSS class notenabled to facilitate styling, when the relevant end of the thumbnail strip has been reached. Returns true if the setting was accepted, or false if it was rejected because the method was called while the slideshow was already being shown. By default, the thumbnail strip uses a scrollbar.
Enabled
Boolean: true to use a scrollbar, false to DHTML layers and buttons.
GallerySlideshowObject.shrinkToFit( Enable[, BlockTransitions] )
Sets whether the image should shrink to fit inside the current display area, or if it should be displayed in its natural size, and provide scrollbars for the user to see the rest of it. When shrink-to-fit is enabled, associated text captions are positioned at the bottom of the display area (unless you have already positioned them with CSS position absolute/fixed), and may become scrollable if they become too tall. Can be called at any time, whether the slideshow is showing or not. If the slideshow is being embedded within the page, and your CSS does not impose some fixed height on the slideimage container DIV, shrink-to-fit will only affect the width of the image, not the height. (Note that Opera may not always update the height correctly when resizing - this is a bug in Opera, and has been reported to them. Other browsers, particularly Firefox and Safari, may impose a minimum viewport width.) Shrink-to-fit can only work in browsers that support CSS max-width and min-width. Has no effect if a transition is playing, unless the optional BlockTransitions parameter is set to true. By default, shrink-to-fit is not enabled.
Enable
Boolean: true to enable shrink-to-fit, false to disable it.
BlockTransitions
Optional Boolean: true to cancel any transitions that are playing and apply the change, false has no effect.
GallerySlideshowObject.getShrinkToFit()
Returns true if shrink-to-fit is currently enabled.
GallerySlideshowObject.showShrinkToggle( Enable )
Sets whether a checkbox should be provided to allow the user to enable/disable shrink-to-fit. Returns true if the setting was accepted, or false if it was rejected because the method was called while the slideshow was already being shown. By default, no checkbox is shown.
Enable
Boolean: true to provide the checkbox, false to not provide it.
GallerySlideshowObject.showCaption( Enable[, BlockTransitions] )
Sets whether the associated text captions should be displayed. Can be called at any time, whether the slideshow is showing or not. Has no effect if a transition is playing, unless the optional BlockTransitions parameter is set to true. Does not affect the loop message, which is controlled using the setLooping method (otherwise the user would end up looking at an empty frame). By default, they are displayed.
Enable
Boolean: true to show associated text captions, false to disable them.
BlockTransitions
Optional Boolean: true to cancel any transitions that are playing, false has no effect.
GallerySlideshowObject.getShowCaption()
Returns true if associated text captions are currently enabled.
GallerySlideshowObject.showCaptionToggle( Enable )
Sets whether a checkbox should be provided to allow the user to enable/disable associated text captions. Returns true if the setting was accepted, or false if it was rejected because the method was called while the slideshow was already being shown. By default, no checkbox is shown.
Enable
Boolean: true to provide the checkbox, false to not provide it.
GallerySlideshowObject.showSlideshow( [PrevText[, NextText[, CloseText[, LoopText[, ShrinkText[, CaptionText[, LeftText[, RightText]]]]]]]] )
GallerySlideshowObject.showSlideshow( ParentElement[, PrevText[, NextText[, CloseText[, LoopText[, ShrinkText[, CaptionText[, LeftText[, RightText]]]]]]]] )
Shows the slideshow. If it is being overlayed on top of the document instead of being embedded, other document contents are hidden, and if any other non-embedded slideshows are already showing, they will be closed. Returns false if the browser is not capable of running the script, or if there are currently no images in the slideshow, or if the slideshow is already showing. The only strings used by the script can be changed using the parameters, to allow translation. Use null as the value of a string (or do not provide that parameter at all) to revert to the default value.
ParentElement
Object: a DOM element node or DocumentFragment. By default, the slideshow will overlay the entire page, effectively replacing it. Providing an element or document fragment as a parent will cause the slideshow to integrate into the document instead, embedded within the given ParentElement. See above for more details.
PrevText
Optional String: the text used for the link to show the previous image in the slideshow. Defaults to '<< Previous'.
NextText
Optional String: the text used for the link to show the next image in the slideshow. Defaults to 'Next >>'.
CloseText
Optional String: the text used for the link to close the slideshow. Defaults to 'Close slideshow'.
LoopText
Optional String: the text displayed when the last image in the slideshow has been reached, and the user attempts to display the next/previous image, if looping with a message is enabled. Defaults to 'You have reached the end of this gallery.'.
ShrinkText
Optional String: the text used beside the checkbox used to enable shrink-to-fit. Defaults to 'Shrink image to fit'.
CaptionText
Optional String: the text used beside the checkbox used to enable associated text captions. Defaults to 'Show captions'.
LeftText
Optional String: the text used on the slideleft link, used to scroll the thumbnails when using the DHTML layer. Defaults to '<'.
RightText
Optional String: the text used on the slideright link, used to scroll the thumbnails when using the DHTML layer. Defaults to '>'.
GallerySlideshowObject.appendMarkup( Markup, InButtonArea )
Adds the new markup into the end of either the galleryslideshow or the prvnxt container DIV. Should only be called after calling showSlideshow. Returns true if the markup was appended, or false if it failed to append it (typically if it is called before the slideshow has been shown).
Markup
Object: a DOM element node, text node, CDATA node or DocumentFragment.
String: HTML markup as a string.
InButtonArea
Boolean: true to append it to the prvnxt container DIV, false to append it to the galleryslideshow container DIV.
GallerySlideshowObject.closeSlideshow()
Closes the slideshow, and restores the previous state of the document if the slideshow was replacing the page. Returns false if the slideshow was not showing. Returns true if the slideshow was showing, and was successfully closed. Closing an embedded slideshow will simply remove it from the element it was embedded in.
GallerySlideshowObject.setTransitions(UseOpacity,UseClip)
Sets which transitions is should use when changing slides. If both transitions types are disabled, then transitions are disabled. Can be set at any time, but may make a mess if a transition is currently playing. By default, transitions are disabled.
UseOpacity
Boolean: true to enable a fade-out effect in browsers that support opacity, false to disable it.
UseClip
Boolean: true to enable a clipping effect, false to disable it.
GallerySlideshowObject.setTransitionDuration(Time)
Sets the amount of time that the transition animation should take to change from one slide image to the next. Can be called at any time. By default, transitions will take 500 ms.
Time
Integer: the number of milliseconds that the transition should take, between 50 and 120000 inclusive.
GallerySlideshowObject.cancelTransition()
Cancels the current transition, if any, that is playing. If a transition was currently playing, the slide it was changing to will then be shown instantly. Can be called at any time.
GallerySlideshowObject.isTransitioning()
Returns true if an transition is currently playing.
GallerySlideshowObject.setCachePrev( ShouldCache )
GallerySlideshowObject.setCacheNext( ShouldCache )
Sets whether it should pre-cache the 'previous' or 'next' image whenever an image is displayed, to speed up displaying the previous/next image when the user selects it. Use with caution, since the user is free to select any image they want, and this could just waste bandwidth and slow down loading of other images if they do not want to view the previous/next image. For best results, it should only be called before calling showSlideshow. By default, 'previous' and 'next' images are not pre-cached.
ShouldCache
Boolean: true to enable caching, false to disable it.
GallerySlideshowObject.setKeyPrev( keyCode[, shiftKey, altKey, ctrlKey, metaKey] )
GallerySlideshowObject.setKeyNext( keyCode[, shiftKey, altKey, ctrlKey, metaKey] )
GallerySlideshowObject.setKeyClose( keyCode[, shiftKey, altKey, ctrlKey, metaKey] )
GallerySlideshowObject.setKeyShrink( keyCode[, shiftKey, altKey, ctrlKey, metaKey] )
GallerySlideshowObject.setKeyCaption( keyCode[, shiftKey, altKey, ctrlKey, metaKey] )
Enables or disables keyboard support for displaying the 'previous' and 'next' images in the slideshow, for closing the slideshow, for toggling shrink-to-fit, and for toggling display of captions. By default, there are no dedicated keyboard shortcuts for any of the actions. Each method can be called as follows:
  1. With a single boolean true parameter to enable keyboard support for the given action, using the default keyboard shortcuts. It will display the next image when the user presses Space, the previous image when the user presses Shift+Space, will close the slideshow when the user presses Esc, toggle shrink-to-fit when the user presses Shift+S, and toggle display of captions when the user presses Shift+C.
  2. With a single boolean false parameter to disable keyboard support for the given action.
  3. With all parameters (where the first parameter must be a positive integer), to enable keyboard support for the given action, which will performed when the user presses the specified keys. Only one key combination can be enabled at a time for each action - calling it multiple times causes it to replace the previous combination.
keyCode
Boolean: true to enable keyboard support using default keyboard shortcuts, false to disable keyboard support. Further parameters will be ignored.
Integer: the key code for the chosen key. Positive integers only. 0 is not a valid code (browsers typically use 0 for all keys they do not explicitly provide codes for). More details are given below.
shiftKey
Optional Boolean: true to require Shift to be pressed at the same time, false to require it not to be pressed.
altKey
Optional Boolean: true to require Alt to be pressed at the same time, false to require it not to be pressed. Can easily conflict with browser UI shortcuts. Recommend always using false.
ctrlKey
Optional Boolean: true to require Ctrl to be pressed at the same time, false to require it not to be pressed. Has problems in some browsers on Mac. Recommend always using false.
metaKey
Optional Boolean: true to require the Windows key or Command key to be pressed at the same time, false to require it not to be pressed. Has problems in some browsers on Windows and Mac, and can conflict with system shortcuts. Recommend always using false.
GallerySlideshowObject.getCurrent()
Returns the index number of the currently selected image in the slideshow. The index will be the same as the number of images in the slideshow if the loop message is being displayed (one more than the maximum index that can be used with setCurrent).
GallerySlideshowObject.getTotal()
Returns the number of images that are currently in the slideshow.
GallerySlideshowObject.canWork()
Returns true if the browser is capable of running the script. Note that this must only be called after the BODY element has been created by the parser, or it will return the wrong result.
GallerySlideshowObject.isCurrentSlideshow()
Returns true if the slideshow is currently replacing the page.
GallerySlideshowObject.isShowingSlideshow()
Returns true if the slideshow is currently being displayed (either embedded within the page, or replacing it).
GallerySlideshowObject.onchange
Allows you to attach a callback function to the slideshow, that will be called whenever the slide view changes or is redrawn. This could mean that the slideshow has just opened, that the user has chosen to display a new image, or redisplay the same image, that they have enabled shrink-to-fit, hidden the associated text captions, or closed the slideshow. Simply assign your chosen function to the slideshow's onchange property. Note that this will also be called if you have used the API to trigger any of these changes while the slideshow is being shown. It is not a real event, despite its name. It simply calls your callback function, passing it a single parameter:
ChangeInformation
An object containing information about what just changed. It will have the following properties:
type
String: the name of the method that caused the redraw. This will be one of 'showSlideshow', 'closeSlideshow', 'setCurrent', 'showPrevious', 'showNext', 'shrinkToFit', 'showCaption'.
from
Mixed: the previous value of the setting. This will be null for 'showSlideshow' and 'closeSlideshow', the slide index number for 'setCurrent', 'showPrevious' and 'showNext', and a boolean for 'shrinkToFit' and 'showCaption'.
to
Mixed: the new value of the setting. This will be null for 'showSlideshow' and 'closeSlideshow', the slide index number for 'setCurrent', 'showPrevious' and 'showNext', and a boolean for 'shrinkToFit' and 'showCaption'.
Note that there are many cases where the from and to values can be the same, meaning that no actual change in that setting took place, but the slide view was still redrawn. Examples include where the user attempts to show the previous/next slide when there is only one available image, when the user clicks on the thumbnail for an image that is already showing, or where your script sets captions or shrink-to-fit to their existing values using the API. Your callback function will be called as a method of the GallerySlideshowObject, so the this keyword will be a reference to that object. You can then use the methods provided by the API to determine or manipulate the current state of the slideshow. Suggested uses are to use the API to determine the current image count, and display that somewhere. Note that if your onchange handler triggers another change, it could result in an infinite script loop, as that subsequent change will cause it to be called again.

Note; there are other methods and properties, but they are for use only by the script itself, and should not be called directly.

Styling the slideshow

By default, the slideshow is almost unstyled, and its styling should be tailored to suit your own style. Only a few style properties are created by the script, and these should not be removed or overridden. The slide wrapper in particular is not designed for you to use for styling - it is used by the script for various other functionality. When the slideshow is replacing the page instead of being embedded within it, it sets a class attribute on the HTML element to facilitate styling, and forces a few styles on the HTML and BODY elements. The resulting DOM it creates is as follows:

<!-- the HTML and BODY styles and classes are only manipulated when the slideshow replaces the page instead of being embedded within it -->
<html class="[showingslides]" style="
  [not-embedded] display: block; border-width: 0; margin: 0; padding: 0;
  [not-embedded and [thumbs-on-bottom or shrink-to-fit]] overflow-x: hidden; overflow-y: hidden;
  [not-embedded and thumbs-on-top and not-shrink-to-fit] overflow-x: auto; overflow-y: scroll;
">
  ... HEAD ...
  <body style="
    [not-embedded] border-width: 0; margin: 0; padding: 0; position: static; width: auto; max-width: none;
  ">
    ... other BODY contents ...
    <!-- when embedding within the page, there could be any other parent elements here -->
    <div class="galleryslideshow[ mouseover]" style="
        [embedded] position: relative;
      ">
      <div class="slidelist" style="
        [always] width: 100%; margin-left: 0; margin-right: 0; padding-left: 0; padding-right: 0; border-left: none; border-right: none;
        [embedded] position: relative;
        [not-embedded] z-index: 2; left: 0; width: 100%;
        [not-embedded and thumbs-on-top] position: fixed; top: 0;
        [not-embedded and thumbs-on-bottom] position: absolute; bottom: 0;
      ">
        <div class="prvnxt" style="text-align: center;">
          <!-- the next link is only present when the slideshow replaces the page instead of being embedded within it -->
          <a style="float: right" class="closebutton">Close slideshow</a>
          <a class="prevbutton[ notenabled]">&lt;&lt; Previous</a>
          <!-- the nextbutton will also contain multiple hidden spans in Opera -->
          <a class="nextbutton[ notenabled]">Next &gt;&gt;</a>
          <!-- the next label is only present when showShrinkToggle is enabled -->
          <label class="shrinklabel"><input type="checkbox"> Shrink image to fit</label>
          <!-- the next label is only present when showCaptionToggle is enabled -->
          <label class="captionlabel"><input type="checkbox"> Show captions</label>
          <!-- appendMarkup can add markup here -->
        </div>
        <div class="slidescroll" style="
          [always] white-space: nowrap; width: auto; margin-left: 0; margin-right: 0; padding-left: 0; padding-right: 0; padding-bottom: 0; border-left: none; border-right: none;
          [scrollbar] overflow: auto; overflow-y: hidden;
          [DHTML-scrolling] overflow: hidden; position: relative
        ">
          <!-- the following elements are only present when using a scrollbar -->
          <a style="vertical-align: middle" class="current"><img style="vertical-align: middle;"></a>
          <a style="vertical-align: middle"><img style="vertical-align: middle;"></a>
          ...
          <!-- the following elements are only present when using DHTML scrolling -->
          <span class="thumblayer" style="position: relative; display: inline-block; vertical-align: middle; top: 0; left: 0; width: auto; margin: 0; padding: 0; border-width: 0;">
            <a style="vertical-align: middle" class="current"><img style="vertical-align: middle;"></a>
            <a style="vertical-align: middle"><img style="vertical-align: middle;"></a>
            ...
          </span>
          <a class="slideleft[ notenabled]" style="position: absolute; top: 0; bottom: 0; left: 0; margin: 0;">&lt;</a>
          <a class="slideright[ notenabled]" style="position: absolute; top: 0; bottom: 0; right: 0; margin: 0;">&gt;</a>
        </div>
      </div>
      <!-- slidelist and slideimage will be in the opposite order if thumbnails are on the bottom -->
      <div class="slideimage" style="
        [embedded] position: relative;
        [not-embedded] position: absolute; top: 0; width: 100%; bottom: 0; left: 0; z-index: 1;
        [not-embedded and thumbs-on-top] margin-top: 123px;
        [not-embedded and thumbs-on-bottom] margin-bottom: 123px;
        [[embedded or thumbs-on-bottom] and shrink-to-fit] overflow: visible;
        [[embedded or thumbs-on-bottom] and not-shrink-to-fit] overflow: auto;
      ">
        <!-- the next div is the slide wrapper - it is not intended to be styled by your CSS -->
        <div style="
          [always] position: static; float: none; border-width: 0; padding: 0; margin: 0;
          [not-shrink-to-fit and [not-loop-message or not-positioned-caption]] display: table; border-spacing: 0; width: 100%; height: 100%;
          [all-other-cases] display: block;
        ">
          <!-- the next image is only present when not displaying a loop message -->
          <img style="
            [always] display: block;
            [shrink-to-fit] float: none; max-width: 123px; max-height: 123px;
            [not-shrink-to-fit and caption and not-positioned-caption] float: left;
          ">
          <!-- the next span is only present if there is a non-shrink-to-fit image and some non-positioned caption to display -->
          <span style="float: right; min-width: 10em; height: 1px;"></span>
          <!-- the next div is only present if there is some caption or loop message to display -->
          <div class="slidecaption" style="
            [shrink-to-fit-height and specified-slideimage-height and caption and not-positioned-caption] position: absolute; bottom: 0; left: 0; right: 0; overflow: auto; max-height: 30%;
            [not-loop-message and not-shrink-to-fit] clear: right;
            [not-positioned-caption and not-shrink-to-fit] max-width: 789px;
          ">
            Text
          </div>
          <!-- the next span is only present if there is a non-shrink-to-fit image and some non-positioned caption to display in an embedded slideshow, and the height of slideimage does not seem to be enforced in some other way -->
          <span style="display: block; height: 1px; clear: both;"></span>
        </div>
      </div>
      <!-- appendMarkup can add markup here -->
      <!-- slideimage will be duplicated here when playing transitions, with absolute position, fixed height/width/top/left, and either opacity and/or clip -->
    </div>
  </body>
</html>

You will need to use some CSS to style this structure. The following CSS should get you started, but be aware that it may need to be tailored to suit your document, and that part is up to you. If your slideshow is going to be embedded within the page, and you plan on allowing or enabling shrink-to-fit, then you should consider applying some kind of fixed height to the slideimage container DIV, to allow it to restrict the height of the image as well as the width. Various elements may not be included depending on what content is going to be included in the slide. As a result, it is important to rely as much as possible on the classes attached to the elements, and not to use CSS 2/3 descendant and sibling selectors. Also note that for maximum compatibility, you should ensure that your DOCTYPE triggers standards mode rendering.

html.showingslides, html.showingslides body, div.slidelist, div.slideimage {
  background: #abc;
}
div.prvnxt {
  padding: 4px 0;
}
div.prvnxt a {
  margin: 0 5px;
  padding: 0 5px;
  text-decoration: none;
  background: #eee;
  color: #22c;
  border: 2px outset silver;
}
div.prvnxt label {
	margin: 0 5px;
}
div.prvnxt * {
  white-space: nowrap;
}
div.prvnxt a:active {
  border-style: inset;
}
div.prvnxt a.closebutton {
  margin-top: -2px;
}
div.slidescroll {
  border-bottom: 1px solid #777;
}
div.slidescroll img {
  margin: 5px 10px;
  border: 1px solid black;
}
div.slidescroll a.current img {
  margin: 2px 7px;
  border: 4px solid #22c;
}
div.slideimage {
  padding-top: 10px; /* prevent a margin collapse with the inner div */
  /* padding-bottom will not affect slidecaption if shrink-to-fit is enabled */
}
div.slideimage img {
  border: 1px solid black;
  margin: 0 10px 10px;
}
div.slidecaption { /* note that this was 'div.slideimage div' in version 1.x */
  margin: 0 10px 10px;
}

If you are embedding the slideshow in the page instead of replacing it, and your images may be of different sizes, you may want to ensure that the slideimage container has a fixed height, or the slideshow will change size when changing images. If you choose to do this, you may also want to include the following CSS to prevent Opera showing a pointless disabled vertical scrollbar, if you know that the slide contents will never overflow:

div.slideimage {
  overflow-y: hidden !important
}

If you are using the DHTML layer for the thumbnail strip instead of a native scrollbar, then you will also want to add some styles for that. Note that although the thumblayer element has a class attribute, that exists only to make it easier for you to target its contents. The element itself is not intended for you to use it for styling, as it serves a vital purpose as the scrolling layer. Make sure that the enabled/disabled styles for the buttons are the same widths as each other. The following CSS should be enough to get you started:

a.slideleft, a.slideright {
  padding: 1.5em 5px;
  text-decoration: none;
  background: #eee;
  color: #22c;
  border: 2px outset silver;
}
a.notenabled {
  color: silver;
  border-style: solid;
}

Note that the script makes various measurements when a slideshow is opened, and in order to maintain performance, will assume that these styles will not change later. You should ensure that the styles that affect its layout are set in the stylesheets before showing a slideshow, and you should also not show a slideshow inside an element that is set not to display at the moment that the slideshow is shown. (Changes that are made later can be picked up by closing and reopening the slideshow.) Note also that the measurements will not take into account any markup that you append to the galleryslideshow container, so if you will enable or allow shrink-to-fit, you should ensure that appended markup will not affect the layout.

Overlaying the associated text captions

The slideimage container is a positioned element container. By default, the script puts the caption to the right of the image, or wraps underneath it if the image is wide enough, or is shrinking to fit the available space. To position the captions overlaying the bottom of it (a popular position for captions, even though it partially obscures the image), simply set the slidecaption class to use absolute position, with the left, bottom and right styles set to appropriate values.

Showing the previous/next buttons only when the image is hovered

Note that this reduces accessibility for keyboard users, who may prefer to use the keyboard to focus and activate links (though you could still enable shortcuts for the gallery). Initially, you can set the nextbutton and prevbutton classes to not display, perhaps while also positioning them somewhere convenient. You can then use CSS :hover detection and selectors to show them like this:

a.prevbutton {
  display: none;
  position: absolute;
  top: 200px;
  left: 50px;
}
a.nextbutton {
  display: none;
  position: absolute;
  top: 200px;
  right: 50px;
}
div.galleryslideshow:hover a.prevbutton, div.galleryslideshow:hover a.nextbutton {
  display: block;
}

However, this has the limitation that not all browsers detect :hover over non-links, and may not behave correctly when reflowing. It will also not work if the previous/next buttons are positioned outside the image area. To make it easier, the script adds an extra mouseover class to the galleryslideshow container DIV whenever the user hovers the slideimage container DIV or previous/next links, and for a short time afterwards. This provides a more reliable option, that is more tolerant of the user failing to control their mouse well. It could be used as follows:

a.prevbutton {
  display: none;
  position: absolute;
  top: 200px;
  left: 50px;
}
a.nextbutton {
  display: none;
  position: absolute;
  top: 200px;
  right: 50px;
}
div.mouseover a.prevbutton, div.mouseover a.nextbutton {
  display: block;
}

Adding extra scroll notices

By default, some browsers do not provide scrollbars in fullscreen mode, or users may have scrollbars disabled. When using a basic slideshow where the thumbnails are at the top, and the slideshow replaces the page, the user may not realise that a large image extends beyond the edge of the screen. It is possible to add extra markup that can be styled to provide a hint to the user that this is the case, and that they need to scroll to see the rest of it. As an example, you could use the following, where the rightfade and bottomfade images are semi-transparent PNG images, faded so that the edge of the image seems to sink behind the background (this is a common effect seen at the top of some long pages, when the header remains static as the rest of the page scrolls):

mySlideshow.appendMarkup('<div class="rightshadow"><\/div><div class="bottomshadow"><\/div>');
...
div.rightshadow {
  position: fixed;
  z-index: 1;
  top: 0;
  bottom: 0;
  right: 0;
  width: 10px;
  background: url(rightfade.png) repeat-y top right;
}
div.bottomshadow {
  position: fixed;
  z-index: 1;
  left: 0;
  bottom: 0;
  right: 0;
  height: 10px;
  background: url(bottomfade.png) repeat-x bottom left;
}

Changelogs

Changes in version 2.0.1

Changes in version 2.0

Changes in version 1.2

Changes in version 1.1

Features of version 1.0

This site was created by Mark "Tarquin" Wilton-Jones.
Don't click this link unless you want to be banned from our site.