ips.ui.lightbox

Description

The Lightbox widget implements a commonly-seen interface convention whereby images can be clicked to view them at a larger size inside a popup that appears on the page. In addition, related images are grouped so that they can be scrolled through inside the popup. IPS4's lightbox also supports built-in commenting.

Example

@todo

Usage

A lightbox can be initialized on a single image as simply as:

<img src='http://url/to/image' data-ipsLightbox>

However, it's likely additional functionality would be desired. A common practice is to link to a large image but display a small thumb image on the page. In this situation, the lightbox is initialized on the link:

<a href='http://url/to/image' data-ipsLightbox><img src='http://url/to/thumb'></a>

In both of the above example, a single image will be displayed in the lightbox. It's also possible to group images together - such as in a photo album, or a group of images for a single content item. In this case, you should initialize a lightbox on all of the items, and include the group option which should be consistent between them:

<a href='http://url/to/image1' data-ipsLightbox data-ipsLightbox-group='example'><img src='http://url/to/thumb1'></a>
<a href='http://url/to/image2' data-ipsLightbox data-ipsLightbox-group='example'><img src='http://url/to/thumb2'></a>
<a href='http://url/to/image3' data-ipsLightbox data-ipsLightbox-group='example'><img src='http://url/to/thumb3'></a>

Options

group
(String; optional)

If provided, the widget will display other images from the same group in the lightbox.

fullURL
(String; optional)

By default, the full size image will be loaded from the href attribute on the a tag. If this option is provided, the full size image will instead be loaded from this URL.

className
(String; optional; default ipsLightbox)

Allows you to provide a classname prefix which will be used when the lightbox UI is built, enabling a custom UI to be shown.

preload
(Boolean; optional; default true)

Determines whether images in the lightbox should be preloaded when the lightbox is opened, designed to reduce wait time for the user as they scroll through images.

Events emitted by ips.ui.lightbox

lightboxImageShown

Triggered when the lightbox shows a new image.

Event data:

• image
  • elem
    Reference to this image's widget element (may different from <em>imageElem</em> if a link launches the lightbox)
  • imageElem
    Reference to the actual image element
  • largeImage
    URL to the fullsize image
  • originalImage
    URL to the image that already existed on the page (e.g. a thumbnail)
  • meta
    The meta information for the image, if any
• triggerElem
  Reference to the widget element that originally opened the lightbox, which may or may not be the image being viewed.