Matchbox

Matchbox is a simple, lightweight jQuery lightbox plugin. The generated lightbox uses no javascript to center the image keeping it as quick and responsive as possible on mobile devices and older machines. In it's default configuration all you need to do is add an attribute to the element you want to open the lightbox and it will do the rest or, if you want more customization, you can define a function to get the source. Other optional features include a quick link to open the image in a new window and navigation arrows to cycle through your matchboxed images without opening and closing the lightbox repeatedly. It even comes with a couple of basic skins that you can easily modify to better fit your site.

Example

You can see the script running, with both themes using both default and customized settings, from the included example directory. Additionally a version of the script can view viewed online at http://phillipgooch.com/github-examples/Matchbox/. Note: the online example may not be completely up-to-date.

Setup

• After setting up your page and including jQuery, include matchbox.jquery.js or it's minified version into the page.
• Link in the included CSS file or it's minified version either to the page or your combined CSS file, if your going to support IE8 then you also need to include the fonts. If you are not supporting IE8 you can skip the next step.
• Include the fonts. Depending on how you have things set up you may need to modify the CSS to link to the font files, these are at the bottom of the document.
• Include a call to the matchbox plugin in your script. The most basic version of this would simply be $.matchbox({});, but there are several options you can set to change it's functionality. See the information below for what they are and example/index.html for an example.

Settings

The following settings can be passed to the markdown plug-in in an object. None of them are required.

• id: An ID given to this specific matchbox, if running multiple light boxes on a single page (in order to use multiple themes or sources for instance) then each one must have it's own unique ID. Default Value: matchbox.
• selector: The jQuery selector used to find all the items you want to lightbox, this can be any jquery selector but when using a data attribute for the source it makes sense to use that as the selector. Default Value: [data-fullsize].
• selectedClass: A class that will be added to the currently selected item, this must have a value if you are going to use the navigation arrows feature. Default Value: matchbox-selected'.
• source: The location where you can find the full size image, if a string is given it will look for an attribute of that name on the element, if a function is passed it will use whatever that function returns. Default Value: data-fullsize.
• theme: The color theme of the lightbox. By default the CSS include two by default, 'light' and 'dark'. Any other string can be used here but it will be missing in the default colors. This is added to the main matchbox element. Default Value: dark.
• showOpenInNewWindow: A boolean that determines whether or not to show the open-in-new-window button at the top left corner when in the lightbox. Default Value: true.
• showNavigationArrows: A boolean that determines whether or not to show the navigation arrows on the sides of the window allowing the user to quickly go between lightboxed images. The appropriate arrow will hide when you are at the beginning or end of the selected images. Default Value: true.
• navigationLoop: A boolean that will override the normal navigation arrow function and make clicking next from the last or previous from the first go to the other end of the lightbox set. Default Value: false.
• stopPropagation: A boolean that determines whether or not the script will stop propagation of the click event. Default Value: true.
• preventDefault: A boolean that determines whether or not the script will prevent the default action of the click, useful for converting link to images into lightboxes while maintaining a backup method of viewing the image (see the example details). Default Value: true.
• debugMessages: Determines if the script should try and output debug messages regarding it's operation, is IE compatible so leaving this on won't kill older versions of IE. Default Value: false.
• loadingHTML: This string should contain whatever you want to be displayed in the lightbox while it is loading the image. Whatever content is placed here will not be automatically centered unless it is a simple an image due to the way centering is done. Default Value: A image with encoded Data URI.

Version History

• 1.1.0 - Added the navigationLoop and a minified CSS file. Fixed a bug where opening a lightbox for the same image twice in a row would cause it to not load the second time and one where the loadingHTML would not show after the first load. Moved the example into a dedicated directory, and cleaned up the unminimized script a bit making it easier to follow.
• 1.0.0 - Initial Release