Options

The ScalableLightbox plugin features a singleton pattern, meaning there is just one instance per web page. This allows to improve performance (fewer DOM elements and lesser events). Multiple lightboxes (called decks) are nevertheless possible.

Initialization

The plugin is initialized on the first call, by passing an options object. The method takes a nonrecurring callback as a second argument, which is executed, once the plugin has been initialized.

$(function() {

  // initial plugin call
  $.ScalableLightbox(options, function() {

    // nonrecurring callback once the plugin has been initialized

  });

});

Do not use the initialization callback for module display

The initialization callback presented above is called immediately after the plugin has been initialized. Especially when the data structure is loaded via the api setting, the additional network request may take some more time, therefore data may not be ready to be presented in the index or lightbox module. Therefore you should use the loaded callback, which is executed, once the data has been loaded.

options

Type: Object

Default: as shown below

The options object has the following structure:

$.ScalableLightbox({
  // data settings
  data:        [],
  api:         null,

  // general settings
  debug:       false,
  resize:      "smartresize",
  hash:        true,
  baseImgPath: "",

  // index module settings
  index: {
    // ...
  },

  // lightbox module settings
  lightbox: {
    // ...
  },

  // callback settings
  callbacks: {
    // ...
  },

  // class name settings
  classNames: {
    // ...
  },

  // transition settings
  transitions: {
    // ...
  }
});

Do not overwrite with empty objects

All of these settings, except for data and general settings are Javascript objects with additional attributes. Please do not the copy the code from above, as it would remove the nested structure! The attributes of these settings are explained in detail below.

Data settings

A few options are necessary in order to run the ScalableLightbox. You need to provide a data source, so that the plugin can load the images and additional information (such as captions). This can be done in two ways, namely via one of the following attributes:


API has higher priority

If both attributes are filled out, the api attribute has the higher priority and overwrites the direct data array. Actually, the information from the api attribute is loaded into the data attribute array.

Data structure

A ScalableLightbox consists of at least one deck object. A deck (aka one slideshow) consists of several item objects in an items array. The order of the item objects is how they are presented in the index and lightbox module. Furthermore, a deck needs to have a unique id, so that it can be called later on (e.g. via the open method).

[
  { // deck with id 1
    id: 1, items: [
      // the order of the item objects is important
      // the first item is displayed first in the
      // index as well as lightbox module
      {
        img:      "p1/1.jpg",
        width:    1000,
        height:   700,
        caption:  "Overview"
      },
      {
        img:      "p1/2.jpg",
        width:    1300,
        height:   666,
        caption:  "Detail"
      }
      // additional item objects ...
    ]
  },
  { // deck with id 2
    id: 2, items: [
      {
        img:           "p2/1.jpg",
        thumb:         "p2/thumb-1.jpg",
        width:         1000,
        height:        700,
        caption:       "Project 2 Caption 1",
        thumbcaption:  "Thumb 1"
      },
      {
        img:          "p2/2.jpg",
        thumb:        "p2/thumb-2.jpg",
        width:        1300,
        height:       666,
        caption:       "Project 2 Caption 2",
        thumbcaption: "Thumb 2"
      }
    ]
  }
  // additional decks ...
]

An item object has the following attributes:

  • img — the path to the image (required)
  • width and height — of the image to maintain aspect ratio on resizes (required)
  • caption — an image description (optional)
  • thumb — an image for the index module, otherwise img is used (optional)
  • thumbcaption — a description for the index module (optional)

Which caption is used in the index module or lightbox module is determined by the caption settings of the module specific options.

Thumbnails need to have same aspect ratio

If you provide a thumb source, it needs to have the same aspect ratio as the image. The plugin uses the width and height that is provided. The thumb is loaded, when the index module is called.

data

Type: Array

Default: []

Provides the data structure directly within the script.

$.ScalableLightbox({
  data: [
    // for data structure, see above
  ]
});

api

Type: String

Default: null

Provides the data structure via a JSON endpoint. The provided URL gets requested automatically:

$.ScalableLightbox({
  api: "api/data.json" // same data structure, see above
});

Use API variant for large collections

The inline version creates a lot of markup that is directly transferred, once the page is requested (or with the script that includes that code), which is not very wise, especially when you have large collections of lightboxes. If that is the case, we strongly encourage you to use the api variant, which makes an additional network request and does not delay the page loading (blocking). You may also benefit from server side abilities such as automatically calculating image width's and heights, as well as pull the ordering of the images from a CMS or database.

A not so sophisticated version (since it uses no database for ordering and does not calculate image width's and heights) of a PHP server side script for generating the JSON API is:

<?php

class Item {
  public $thumb;
  public $img;
  public $width;
  public $height;
  public $caption;

  public function __construct($thumb, $img, $width, $height, $caption) {
    $this->thumb = $thumb;
    $this->img = $img;
    $this->width = $width;
    $this->height = $height;
    $this->caption = $caption;
  }
}

class Deck {
  public $id;
  public $items = array();

  public function __construct($id, $items) {
    $this->id = $id;
    $this->items = $items;
  }
}

$data = array();
$data[] = new Deck(1, [
    new Item(null, "canyon-house/01.jpg", 1500, 2173, "Canyon House 01.jpg by Labics"),
    new Item(null, "canyon-house/02.jpg", 1500, 2173, "Canyon House 02.jpg by Labics"),
    new Item(null, "canyon-house/03.jpg", 1500, 2173, "Canyon House 03.jpg by Labics"),
    new Item(null, "canyon-house/04.jpg", 1500, 1033, "Canyon House 04.jpg by Labics"),
    // more item objects..
  ]
);

echo json_encode($data);

?>

General settings

debug

Type: Boolean

Default: false

Whether debug information should be displayed in the browser's web developer console.

resize

Type: Boolean or String

Default: "smartresize"

How the plugin resizes itself. The resize attribute may take one of the following values:

  • "smartresize" — debounced resizing for better performance
  • true — resize the plugin on every window resize event
  • false — to deactivate auto-resize

For example you might want to trigger the resizing of the plugin within your own code. See the resize method for additional information.

$.ScalableLightbox({
  resize: false
});

$(window).bind("resize", function() {

  // do my resize stuff
  // ...

  $.ScalableLightbox("resize");

  // ...

});

hash

Type: Boolean

Default: true

The hash of the URL is changed, when navigating through the lightbox module or when opening the index module. Furthermore, when the page loads and a valid hash is present, the plugin displays the contents accordingly.

baseImgPath

Type: String

Default: ""

The base path for image URL's. If the variable is set, its value will be placed in front of all img and thumb paths of every deck object. For example, in case you have all your lightbox images under a specific folder structure (lets say "img/lightboxes/"), you can reduce the amount of transferred data, by providing the base path with a trailing slash:

$.ScalableLightbox({
  baseImgPath:  "img/lightboxes/",
  data:         [
    {
      id: 10, items: [
        // then instead of providing "img/lightbox/project-1/image1.png",
        // you put "project-1/image1.png"
        { img: "project-1/image1.png", width: 1000, height: 600 },
        { img: "project-2/image2.png", width: 1200, height: 800 },
        { img: "project-2/image3.png", width: 1000, height: 600, thumb: "project-2/image3-thumb.png" }
      ]
    }
  ]
});

Index module settings

Type: Object

Default: as shown below

The index object defines index module specific parameters. Below you find a list with all those parameters, which are afterwards explained in detail.

index: {

  enabled:                        true,
  overlay:                        true,
  layout:                         "float",

  thumb: {
    overlay:                      true,
    width:                        280,
    caption:                      "number",
    captionNumberFmt:             "%n% / %total%",
    captionPosition:              "below",
    captionVerticalMargin:        5
  },

  controls: {
    close:                        true
  }

}

enabled

Type: Boolean

Default: true

Whether the index module is activated or not.

overlay

Type: Boolean

Default: true

If the index module is displayed on top of an overlay div.

layout

Type: String

Default: "float"

The layout of the thumbs, valid values are:

  • "float" — elements are floated with standard CSS
  • "masonry" — elements are aligned in a masonry (masonry plugin required)

How to enable masonry layout mode

First you need to download the masonry plugin. Then integrate it before calling the plugin like so:

<!-- ... -->

<script type="text/javascript" src="js/masonry.pkgd.min.js"></script>
<script type="text/javascript" src="js/jquery.scalable-lightbox.js"></script>

<!-- ... -->

You are then ready to use the masonry layout for the index module:

$.ScalableLightbox({
  data:  [
    // ...
  ],
  index: {
    layout: "masonry"
  }
  // ...
});

thumb

Type: Object

Default: as shown previously

Thumbnail specific options, such as the thumb width, the contents and positioning of the caption.

overlay

Type: Boolean

Default: true

Whether the thumbnails of index module have themselves have an overlay.

width

Type: Integer

Default: 280

The width of a thumbnail. The height is calculated automatically out of the width and height of the corresponding deck item.

caption

Type: String

Default: "number"

What should be displayed as a caption of the thumb. Valid attributes are:

  • "none" — no caption is displayed
  • "caption" — the caption value of the data item is displayed
  • "thumbcaption" — the thumbcaption value of the data item is displayed
  • "number" — the number of the item is displayed (e.g. 2 / 10) according to captionNumberFmt

captionNumberFmt

Type: String

Default: "%n% / %total%"

In case caption is set to "number", how the number should be displayed. Use %n% to display the thumbs position and %total% to show the total items in the current deck. For example, "%n% of %total%", will display 1 of 10, 2 of 10, etc.

captionPosition

Type: String

Default: "below"

The position of the caption for the thumbnails of the index module. Valid attributes are:

  • "above" — above the thumb (use captionVerticalMargin for vertical spacing)
  • "top" — at the top border of the thumb
  • "center" — at the center of the thumb
  • "bottom" — at the bottom of the thumb
  • "below" — below the thumb (use captionVerticalMargin for vertical spacing)

captionVerticalMargin

Type: Integer

Default: 5

The margin to the thumbnail (in pixel), in case a caption is positioned "above" or "below".

controls

Type: Object

Default: as shown previously

Control parameters for the index module.

close

Type: Boolean

Default: true

Whether a click or touch outside an index element (for example on the index overlay) as well as ESC key closes the index module. This invokes the close method.

Type: Object

Default: as shown below

The lightbox attribute defines lightbox module specific parameters. Below you find a list with all those parameters, which are afterwards explained in detail.

lightbox: {

  enabled:                        true,
  overlay:                        true,

  padding: {
    horizontal:                   100,
    vertical:                     100,

    horizontalMobile:             50,
    verticalMobile:               50,
  },

  img: {
    captionLeft:                  "index",
    captionCenter:                "caption",
    captionRight:                 "number",
    captionNumberFmt:             "%n% / %total%",
    captionIndexTxt:              "Index",

    captionPosition:              "below",

    captionVerticalMargin:        5
  },

  controls: {
    close:                        true,
    clicks:                       true,
    keys:                         true
  }

}

Type: Boolean

Default: true

Whether the lightbox module is activated or not.

Type: Boolean

Default: true

Whether the lightbox module is displayed on top of an overlay div.

Type: Object

Default: as shown previously

The padding for the lightbox images to the browser window. The values are divided by 2, to have an equal padding on each side.

Type: Integer

Default: 100

The horizontal padding of the lightbox images to the browser window. The values are divided by 2, to have an equal padding on each side.

Type: Integer

Default: 100

The vertical padding of the lightbox images to the browser window. The values are divided by 2, to have an equal padding on each side.

Type: Integer

Default: 50

The horizontal padding of the lightbox images to the browser window for window width's below 450 pixel, or window height's below 400 pixel. The values are divided by 2, to have an equal padding on each side.

Type: Integer

Default: 50

The vertical padding of the lightbox images to the browser window for window width's below 450 pixel, or window height's below 400 pixel. The values are divided by 2, to have an equal padding on each side.

Type: Object

Default: as shown previously

Lightbox image specific options, such as the contents and positioning of the caption. The lightbox features three caption positions, namely captionLeft, captionCenter and captionRight. Valid attributes for those three captions are:

  • "none" — no caption is displayed
  • "caption" — the caption value of the data item is displayed
  • "thumbcaption" — the thumbcaption value of the data item is displayed
  • "number" — the number of the item is displayed (e.g. 2 / 10) according to captionNumberFmt
  • "index" — a link to the index module (only visible if it is enabled) is displayed, change the link text, by changing captionIndexTxt accordingly

Type: String

Default: "index"

What should be displayed as the left caption of the lightbox module. Valid attributes are described above.

Type: String

Default: "caption"

What should be displayed as the center caption of the lightbox module. Valid attributes are described above.

Type: String

Default: "number"

What should be displayed as the right caption of the lightbox module. Valid attributes are described above.

Type: String

Default: "%n% / %total%"

In case one of three lightbox captions above is set to "number", how the number should be displayed. Use %n% to display the thumbs position and %total% to show the total items in the current deck. For example, "%n% of %total%", will display 1 of 10, 2 of 10, etc.

Type: String

Default: "Index"

In case one of three lightbox captions above is set to "index", what should be displayed as the link's text.

Type: String

Default: "below"

The position of the three captions of the lightbox module. Valid attributes are:

  • "above" — above the thumb (use captionVerticalMargin for vertical spacing)
  • "top" — at the top border of the thumb
  • "center" — at the center of the thumb
  • "bottom" — at the bottom of the thumb
  • "below" — below the thumb (use captionVerticalMargin for vertical spacing)

Type: Integer

Default: 5

The margin to the lightbox image (in pixel), in case a caption is positioned "above" or "below".

Type: Object

Default: as shown previously

Control parameters for the lightbox module.

Type: Boolean

Default: true

Whether a click or touch outside the lightbox (for example on the lightbox overlay) as well as ESC key closes the lightbox module. This invokes the close method.

Type: Boolean

Default: true

Whether click events on lightbox image (left and right side of the lightbox container) for navigating to the previous or next image are enabled. This invokes the prev or next method. For styling the cursors, have a look at the lightbox cursor styles.

Type: Boolean

Default: true

Whether left and right keyboard arrows are used for navigation from a lightbox image to the previous or next one. This invokes the prev or next method.

Callback settings

Type: Object

Default: as shown below

The general callback functions open and close are executed every time after the corresponding function call has been finished. In order to use nonrecurring callbacks, you may send them along with the call the corresponding public function (see open or close method).

callbacks: {
  loaded:                         null,
  open:                           null,
  close:                          null,
  resize:                         null
}

loaded

Type: Function

Default: null

This callback is triggered, once (and only once) the plugin has been initialized and the data has been loaded. However, the image and thumb sources are not loaded yet, they are loaded, when they are displayed to the user.

This callback is especially useful, in case you want to display a module, once the page has been loaded. The following example displays a project page in a lightbox, once the project images data (determined by the window.projectID) has been loaded.

// previously set by server
window.projectID = 10;

$.ScalableLightbox({

  // the JSON endpoint just feeds one
  // single deck with the id = window.projectID
  api:                              "api/project/" + window.projectID,
  lightbox: {
    // display on white background (no
    // overlay is needed)
    overlay:                        false,
    // the lightbox cannot be closed, otherwise
    // users would see a white page
    controls: {
      close:                        false
    }
  },
  callbacks: {
    // once a plugin module has been loaded,
    // display the current project in the lightbox
    loaded: function() {

      var regex = /#lightbox\/(\d*)\/(\d*)/,
          match = regex.exec(window.location.hash);

      // hash detect (if true, the plugin
      // will open the contents for you)
      if (!match) {
        $.ScalableLightbox("open", { module: "lightbox", deck: window.projectID });
      }
    }
  }

});

open

Type: Function

Default: null

General callback function, which is executed every time the open method is called. If a nonrecurring callback is provided along with the open method, this general open callback is not executed.

For example, in case you have a heavy, responsive web app, you may disable it's resizing, while the plugin is displayed, so the browser window does not start to get chunky.

$.ScalableLightbox({

  api:                  "api/work",

  lightbox: {
    img: {
      captionNumberFmt: "%n%/%total%",
    }
  },

  callbacks: {
    // once a plugin module has been opened,
    // we disable the heavy resizing of our app,
    // because that UI is not visible to
    // the user
    open: function() {
      window.myApp.core.unbind("resize");
    }
  }

});

close

Type: Function

Default: null

General callback function, which is executed every time the close method is called. If a nonrecurring callback is provided along with the close method, this general close callback is not executed.

Using the example from above, once the plugin module has been closed, we want to rebind the resizing of your heavy, responsive app.

$.ScalableLightbox({

  api:                  "api/work",

  lightbox: {
    img: {
      captionNumberFmt: "%n%/%total%",
    }
  },

  callbacks: {
    // once a plugin module has been closed,
    // we rebind the heavy resizing of our app,
    // because that UI becomes visible to the
    // user again
    close: function() {
      window.myApp.core.bind("resize");

      // depending on your implementation, you may
      // also trigger the global resize (this will
      // not invoke the plugin resize, which is
      // unbound on every close call)
      $(window).trigger("resize");
    }
  }

});

resize

Type: Function

Default: null

General callback function, which is executed every time the resize method is called. If a nonrecurring callback is provided along with the resize method, this general close callback is not executed.

You might want to resize a part of your app that is displayed above the Plugin (e.g. top navigation):

$.ScalableLightbox({

  api:                  "api/projects",

  // increase the vertical padding
  // for our top navigation
  lightbox: {
    padding: {
      vertical: 200
    }
  },

  callbacks: {
    // once the plugin has been resized, we also
    // want to resize the top navigation
    resize: function() {
      window.myApp.core.Topnavi.resize();
    }
  }

});

Class name settings

Type: Object

Default: as shown below

The CSS class names that are used for the HTML structure of the plugin are all changeable. The attribute names should be self explaining, otherwise we recommend that you study the corresponding CSS style definitions in the design section of this website. Furthermore you can directly investigate the HTML structure and class names in your browser's web developer tool.

classNames: {
  clearfix:                       "clearfix",
  pluginActive:                   "sl-active",
  container:                      "sl-container",

  indexOverlay:                   "sl-index-overlay",
  indexWrapper:                   "sl-index-wrapper",
  indexDecksContainer:            "sl-index-decks-container",
  indexDeck:                      "sl-index-deck",
  indexItem:                      "sl-index-item",
  indexItemImg:                   "sl-index-item-img",
  indexItemIndicator:             "sl-index-item-indicator",
  indexItemOverlay:               "sl-index-item-overlay",
  indexItemCaption:               "sl-index-item-caption",
  indexItemCaptionInner:          "sl-index-item-caption-inner",

  lightboxOverlay:                "sl-lightbox-overlay",
  lightboxWrapper:                "sl-lightbox-wrapper",
  lightboxDecksContainer:         "sl-lightbox-decks-container",
  lightboxDeck:                   "sl-lightbox-deck",
  lightboxItem:                   "sl-lightbox-item",
  lightboxItemIndicator:          "sl-lightbox-item-indicator",
  lightboxItemCaptionContainer:   "sl-lightbox-caption-container",
  lightboxIndexLink:              "sl-lightbox-index-link",
  lightboxCursor:                 "sl-lightbox-cursor"
}

Change CSS style definitions accordingly

Of course, when you change a class name here, you also need to rename all the corresponding style definitions in jquery.scalable-lightbox.css. See design for more information.

Transition settings

Type: Object

Default: as shown below

These parameters allow you to tailor the durations of the animations.
All durations are in milliseconds.

transitions: {
  fadeInIndexOverlay:             500,
  fadeOutIndexOverlay:            500,

  fadeInIndex:                    500,
  fadeOutIndex:                   500,

  fadeInIndexItemLoaded:          250,

  fadeInLightboxOverlay:          500,
  fadeOutLightboxOverlay:         500,

  fadeInLightbox:                 500,
  fadeOutLightbox:                500,

  fadeInLightboxItemLoaded:       250,

  fadeLightboxItem:               250
}

fadeInIndexOverlay

Type: Integer

Default: 500

Duration to fade in the index overlay. For this to work, the overlay attribute of the index module must be enabled.

fadeOutIndexOverlay

Type: Integer

Default: 500

Duration to fade out the index overlay. For this to work, the overlay attribute of the index module must be enabled.

fadeInIndex

Type: Integer

Default: 500

Duration to fade in the index module in by calling the open method.

In case the overlay attribute of the index module is enabled, total transition time is (fadeInIndexOverlay + fadeInIndex), because first the overlay is faded in, then the index module.

fadeOutIndex

Type: Integer

Default: 500

Duration to fade out the index module by calling the close method.

In case the overlay attribute of the index module is enabled, total transition time is (fadeOutIndexOverlay + fadeOutIndex), because first the index module is faded out, then the overlay.

fadeInIndexItemLoaded

Type: Integer

Default: 250

Duration to fade in a index item once the img or thumb source has been loaded.

In case the source has been loaded previously (for example only the img attribute is provided and the user has first visited the lightbox module), it will be displayed directly (no fade in).

Hardware accelerated CSS3 animations

In case you have CSS3 hardware accelerated animations enabled, you will also need to change the durations for the opacity transitions of the style definition .csstransitions .sl-index-item-img img in jquery.scalable-lightbox.css, or overwrite that definition in your own style sheet.

.csstransitions .sl-index-item-img img {
  -webkit-transition: opacity 250ms ease;
     -moz-transition: opacity 250ms ease;
      -ms-transition: opacity 250ms ease;
       -o-transition: opacity 250ms ease;
          transition: opacity 250ms ease;
}

fadeInLightboxOverlay

Type: Integer

Default: 500

Duration to fade in the lightbox overlay. For this to work, the overlay attribute of the lightbox module must be enabled.

fadeOutLightboxOverlay

Type: Integer

Default: 500

Duration to fade out the lightbox overlay. For this to work, the overlay attribute of the lightbox module must be enabled.

fadeInLightbox

Type: Integer

Default: 500

Duration to fade in the lightbox module by calling the open method.

In case the overlay attribute of the lightbox module is enabled, total transition time is (fadeInLightboxOverlay + fadeInLightbox), because first the overlay is faded in, then the lightbox module.

fadeOutLightbox

Type: Integer

Default: 500

Duration to fade out the lightbox module out by calling the close method.

In case the overlay attribute of the lightbox module is enabled, total transition time is (fadeOutLightboxOverlay + fadeOutLightbox), because first the lightbox module is faded out, then the overlay.

fadeInLightboxItemLoaded

Type: Integer

Default: 250

Duration to fade in a lightbox item once the image (img of data item) has been loaded.

In case the source has been loaded previously (for example only the img attribute is provided and the user has first visited the index module), it will be displayed directly (no fade in).

Hardware accelerated CSS3 animations

In case you have CSS3 hardware accelerated animations enabled, you will also need to change the durations for the opacity transitions of the style definition .csstransitions .sl-lightbox-item img in jquery.scalable-lightbox.css, or overwrite that definition in your own style sheet.

.csstransitions .sl-lightbox-item img {
  -webkit-transition: opacity 250ms ease;
     -moz-transition: opacity 250ms ease;
      -ms-transition: opacity 250ms ease;
       -o-transition: opacity 250ms ease;
          transition: opacity 250ms ease;
}

fadeLightboxItem

Type: Integer

Default: 250

Duration for the transition from previous image to the next in the lightbox by using a navigation method (such as prev, next or goto).

Hardware accelerated CSS3 animations

In case you have CSS3 hardware accelerated animations enabled, you will also need to change the durations for the transitions of the style definition .csstransitions .sl-lightbox-decks-container in jquery.scalable-lightbox.css, or overwrite that definition in your own style sheet.

.csstransitions .sl-lightbox-decks-container {
  -webkit-transition: all 250ms ease;
     -moz-transition: all 250ms ease;
      -ms-transition: all 250ms ease;
       -o-transition: all 250ms ease;
          transition: all 250ms ease;
}