Purchase

JavaScript API

Getting Started

ModuloBox is a modular and responsive lightbox plugin, which allows you to create slideshow of images, videos, HTML content and iFrame in a popup.
It is compatible with common web image formats (.jpg, .jpeg, .png, .bmp, .gif, .tif, .tiff, .jfi, .jfif, .exif, .svg), HTML5 videos (.mp4, .webm, .ogv), iframe videos (Youtube, Vimeo, Dailymotion, Wistia), HTML content and iframe.

The script is written in plain JavaScript (Vanilla JS) with prototype and supports AMD loaders like RequireJS and CommonJS.
It uses the last JavaScript/HTML5 APIs and technics in order to obtain best performances.
Animations are handled by requestAnimationFrame (to obtain 60fps) and use physic principles to handle gestures and transitions (no css and no easing used).

ModuloBox is compatible with Google Chrome, Safari, FireFox, Opera, Edge, IE11 and IE10. ModuloBox is also compatible with IE9 but it's not officially supported.
The script should work with all touch devices like iOS, Android, Windows phone. It supports mouse, touch and pointer events according to W3C.

Performances

Animations

ModuloBox was built in a way to obtain the best performances on any browser and device.
Animations are handled by requestAnimationFrame in order to obtain an average of 60fps.
Gestures and animation transitions use physic principles to ensure the most natural behaviour for the user.
No easing or css transitions are used. It only uses physic principles based on attraction, friction coefficients and user gesture velocity.
This principle allows to obtain swipeable touch lightbox that feels natural, like a native mobile swipeable view.

To preserve animation performances, you should not trigger a css property or JavaScript method which layout/reflow the document.
If you are using events to modify the slider behaviour, you should use css properties hardware accelerated otherwise it will create jumps in animation due to long keyframe triggered by reflow/repaint in the document.
css3 animation should be always applied on absolute positionned elements to obtain best results.

Image sizes and weights

Performances will mainly depend of image sizes and weights used in the lightbox. The smaller images are, the smoother animations will be.
So, you should always compress your images and correctly size them for the web. A commun resolution image used in a lightbox is 1920*1080 px to handle 1080p images.
You can of course add images with bigger resolutions but it can eventually slow down a little bit animations depending of their weights.

For thumbnails, you should also correctly size them according to thumbnailSizes option of MobuloBox.
If your images are too big compared to thumbnail sizes it can significantly impact the animation performances.

Number of images in a gallery

The number of images in a lightbox will not impact the performance.
ModuloBox was fully optimized regarding loading performances. Only images in the viewport are loaded and displayed.
This principle is applied for slides and thumbnails. It means that all images which are outside the slider and/or browser viewport will not be appended and loaded.

The number of images in the main slider will never be more than 5. For thumbnails it will depend of their sizes and the screen width resolution of the device you are using.
For example, depending of MobuloBox settings, if you open a gallery of 1000 images in a lightbox, it will always generate and display 30 thumbnails at maxium to fill the entire browser width.
Otherwise, appending 1000 DOMs for the thumbnails will drastically slow down the opening time, animations, and it will certainly freeze mobile devices.

To sumup, opening 1000 images in ModuloBox will be approximately the same as opening 10 images. It will not impact performance and it will not freeze your mobile device for memory issue (on IOS for example).

Include JS & CSS files

You can find them in dist/ folder available in the main downloadable .zip package on CodeCanyon.

You should include the stylesheet (.css) of ModuloBox in the head of the document: 

<head>
<!-- ... -->
<link rel="stylesheet" href="path/to/modulobox.min.css" media="screen">
<!-- ... -->
</head>

You should include the JavaScript (.js) file of ModuloBox before the end of the body close tag. 

<body>
<!-- ... -->
<script src="path/to/modulobox.min.js"></script>
<!-- ... -->
</body>

Setup a gallery markup

ModuloBox works with any kind of markup with the help of mediaSelector option as query selector.
By default the mediaSelector is .mobx.

If you use <a> tag to wrap your images/media, the media url will be automatically fetched from the href attribute.
If you use <img> tag, the media url will be automatically fetched from the src attribute.
In all other cases, you need to declare a data-src attribute in your HTML markup.
If are using a gallery markup following schema.org, ModuloBox will automatically fetch title from figureCaption.
If an image is present as a child inside the mediaSelector, MobuloBox will use it as thumbnail.

ModuloBox can handle several galleries in a document. You can specify the gallery name in a data-rel attribute.
If no data-rel attribute is present, it will open single image with an uniquely generated gallery ID name (based on the current galleries length).
If are using a gallery markup following schema.org, ModuloBox will automatically fetch the gallery name from DOM holder ID.

ModuloBox will uses HTML5 data attributes to fetch information about the media like the type of media, title, description and thumbnails.
The script will automatically recognize image, video (HTML5 & iframe videos) formats. Other format types (HTML, iframe) must be declared inside the data-type attribute.

Attributes

  1. srcFor <img>, url of the media (image only) in original size.
  2. hrefFor <a>, url of the media (image, video, iframe only) in original size.
  3. titleTitle of the media (if data-title empty).
  4. altDescription of the media (if data-alt empty).
  5. data-relGallery Name. Allow to group media into one gallery from a name relation.
  6. data-srcurl/src or #ID (for HTML content) of the media.
  7. data-typeContent type of the media (image, video, iframe, HTML).
  8. data-titleTitle of the media.
  9. data-descDescription of the media.
  10. data-thumbThumbnail url of the media.
  11. data-posterVideo poster url of the media (only for video type).
  12. data-widthFor HTML/iframe types, max width of the content.
  13. data-heightFor HTML/iframe types, max height of the content.

A tag Example:

<div class="gallery-holder">

    <!-- image (.jpg, .jpeg, .png, .bmp, .gif, .tif, .tiff, .jfi, .jfif, .exif, .svg) -->
    <a class="mobx" href="image1.jpg" data-title="My title 1" data-desc="My description 1" data-rel="gallery1">
        <img width="80" height="80" src="thumbnail1.jpg">
    </a>

    <!-- HTML5 video (.mp4, .ogv, .webm) -->
    <a class="mobx" href="video.mp4" data-poster="poster1.jpg" data-rel="gallery1">
        <img width="80" height="80" src="thumbnail2.jpg">
    </a>

    <!-- iframe video (Youtube, Vimeo, Dailymotion, Wistia) -->
    <a class="mobx" href="https://youtu.be/M7lc1UVf-VE" data-poster="poster2.jpg" data-rel="gallery1">
        <img width="80" height="80" src="thumbnail3.jpg">
    </a>

    <!-- iframe -->
    <a class="mobx" href="https://www.google.com/maps/embed" data-type="iframe" data-width="800" data-height="600" data-rel="gallery1">
        <img width="80" height="80" src="thumbnail4.jpg">
    </a>

    <!-- HTML -->
    <a class="mobx" href="#content" data-type="HTML" data-width="500" data-height="500" data-rel="gallery1">
        <img width="80" height="80" src="thumbnail5.jpg">
    </a>
    <!-- HTML container for #content -->
    <div id="content" style="display: none">
       <div>This is an example of HTML content</div> 
    </div>

</div>

Custom markup Example:

<!-- image (.jpg, .jpeg, .png, .bmp, .gif, .tif, .tiff, .jfi, .jfif, .exif, .svg) -->
<div class="mobx" data-src="image1.jpg" data-title="My title 1" data-desc="My description 1" data-thumb="thumbnail1.jpg" data-rel="gallery1"></div>
<!-- HTML5 video (.mp4, .ogv, .webm) -->
<div class="mobx" data-src="video.mp4, video.ogv, video.webm" data-poster="poster1.jpg" data-thumb="thumbnail2.jpg" data-rel="gallery1"></div>
<!-- iframe video (Youtube, Vimeo, Dailymotion, Wistia) -->
<div class="mobx" data-src="https://youtu.be/M7lc1UVf-VE" data-poster="poster2.jpg" data-thumb="thumbnail3.jpg" data-rel="gallery1"></div>
<!-- iframe -->
<a class="mobx" data-src="https://www.google.com/maps/embed" data-type="iframe" data-thumb="thumbnail4.jpg" data-width="800" data-height="600" data-rel="gallery1"></div>
<!-- HTML -->
<a class="mobx" data-src="#content" data-type="HTML" data-thumb="thumbnail5.jpg" data-width="500" data-height="500" data-rel="gallery1"></div>

<!-- HTML container for #content -->
<div id="content" style="display: none">
    <div>This is an example of HTML content</div> 
</div>

Setup responsive images

If you are using img tag to target your media thanks to mediaSelector, ModuloBox will able to fetch the current media source (currentSrc) depending of the browser width from srcset attribute.
Images retrieved from srcset will not change on browser resize.

ModuloBox also handles responsive images in a similar way as srcset. You will be able to set different image sizes (or video poster sizes) per media depending of the browser width thanks to data-src attribute or data-poster for video posters.
Image size choosen by ModuloBox will depend of the screen device width. Because this value is fixed, whatever the browser width, MobuloBox will only load it once even if you resize your browser.
It allows to reduce the number of requests and to only load one image per item in a lightbox.

To set several image sizes, you need to specify each of your image url comma separated. You can specify the minimum browser width next to the image url with as suffix w for the width.

Responsive Example:

<!-- responsive image -->
<div class="mobx" data-src="image1-small.jpg, image1-medium.jpg 980w, image1-large.jpg 1920w"></div>
<!-- responsive video poster -->
<div class="mobx" data-src="video.mp4" data-poster="poster1-small.jpg, poster1-medium.jpg 980w, poster1-large.jpg 1920w"></div>

Initialize

You can use ModuloBox with vanilla JS, jQuery or AMD loaders. The ModuloBox() constructor accepts one argument: options object.
The initialization should happen after the included script.

Vanilla JS Example:

// create instance of ModuloBox
var mobx = new ModuloBox({
    // options
    mediaSelector : '.mobx',
    scrollToZoom  : true,
    shareButtons  : ['facebook', 'googleplus', 'twitter', 'pinterest', 'linkedin'],
});

// initialize the instance	
mobx.init();

If you initialize ModuloBox before to include the JavaScript file, or before the nodes (media) to open with mediaSelector, please make sure to listen DOMContentLoaded before to initialize the instance: 

// wait for document loaded
document.addEventListener( 'DOMContentLoaded', function() {
    
    // create instance of ModuloBox
    var mobx = new ModuloBox( /* options */ );
    // initialize the instance	
    mobx.init(); 

});

Require JS Example:

require([
    'path/to/modulobox.js'
], function( ModuloBox ) {
    
    // create instance of ModuloBox
    var mobx = new ModuloBox(options);	
    // initialize the instance	
    mobx.init();

});

jQuery Example:

// create instance of ModuloBox
var mobx = $.ModuloBox( /* options */ );
// initialize the instance	
mobx.init();

If you initialize ModuloBox before to include the JavaScript file, or before the nodes (media) to open with mediaSelector, please make sure to wait that the document is ready before to initialize the instance: 

// wait for document loaded
$( document ).ready( function() {

    // create instance of ModuloBox
    var mobx = $.ModuloBox( /* options */ );
    // initialize the instance	
    mobx.init(); 
    
});

Options

ModuloBox comes with plenty of options which allow to easily customize the lightbox without touching the core script.
Options are added in an object key-value pairs and passed as first argument to ModuloBox constructor.

Example:

var options = {
    mediaSelector  : '.mobx',
    attraction     : {
        slider : 0.055,
        slide  : 0.018,
        thumbs : 0.016
    },
    scrollToZoom   : true,
    shareButtons   : ['facebook', 'googleplus', 'twitter', 'pinterest', 'linkedin'],
    thumbnailSizes : {
        1920 : {
            width  : 110,
            height : 80,
            gutter : 10
        },
        1280 : {
            width  : 90,
            height : 65,
            gutter : 10
        },
        480 : {
            width  : 60,
            height : 44,
            gutter : 5
        }
    }
};

// create instance of ModuloBox
var mobx = new ModuloBox( options );

mediaSelector Type: (string) | Default: '.mobx'

Specify selector for media elements. mediaSelector is useful to match media in the document with a custom markup.

Example:

mediaSelector: '.mobx'

threshold Type: (number) | Default: 5

The threshold corresponds to the number of pixels a mouse or touch has to move before dragging begins.
In the core script, it allows to detect the gesture type (dragX/Y, pinch, etc...).

Example:

threshold: 5

attraction Type: (Object) | Default: { slider : 0.055, slide : 0.018, thumbs : 0.016 }

Attracts the position of the slider to the selected cell.
Higher value makes the slider move faster. Lower value makes it move slower.

Example:

attraction : {
    slider : 0.055, // From 0 to 1
    slide  : 0.018, // From 0 to 1
    thumbs : 0.016  // From 0 to 1
}

friction Type: (Object) | Default: { slider : 0.62, slide : 0.18, thumbs : 0.22 }

friction slows the movement of slider.
Higher value makes the slider feel stickier & less bouncy. Lower value makes the slider feel looser & more wobbly.

Example:

friction : {
    slider : 0.62,  // From 0 to 1
    slide  : 0.18,  // From 0 to 1
    thumbs : 0.22   // From 0 to 1
}

rightToLeft Type: (boolean) | Default: false

Enable or disable right to left layout.

Example:

rightToLeft : true

loop Type: (number) | Default: 3

Defined from how much items infinite loop is enabled.

0 : no loop,
1 : always loop (start to loop if there is at least one item in the opened gallery),
2 : loop if 2 items at least,
3 : loop if 3 items at least,
etc...

Example:

loop : 1

preload Type: (number) | Default: 1

Number of media to preload on opening. If set to 1, it will load the currently media opened and once loaded it will preload the 2 closest media. value can be 1, 3 or 5.
Lowest the value is, less it will takes time to display media opened.

Example:

preload : 3

timeToIdle Type: (number) | Default: 4000

Hide controls (top navigation bar) when an idle state exceed X milliseconds.
0 will always keep controls visible
Only works with mousemove event. On touch mobile devices, if enabled, the user can hide the top bar with one tap.

Example:

timeToIdle : 6000

history Type: (boolean) | Default: false

Enable/disable history in browser (deeplink) when opening/navigating/closing a gallery.
history options is not required to open a gallery from a deeplink url.
history options is not required to share a media.

When history is enabled, query strings are pushed in url location thanks to pushState method (HTML5 History API):
 guid : gallery unique identifier
 mid : media identifier

HTML5 History API is not available on old browsers like Internet Explorer 9.

Example:

history : true

mouseWheel Type: (boolean) | Default: true

Enable/disable mouseWheel and up, down, space keys to scroll page.

Example:

mouseWheel : false

contextMenu Type: (boolean) | Default: true

Enable/disable contextmenu on right click (on image, video poster, thumbnails).
Useful if you want to prevent an user to right click in order to download an image.

Example:

contextMenu : false

scrollBar Type: (boolean) | Default: true

Show/hide browser scrollbar on lightbox opening and closing.

Example:

scrollBar : false

controls Type: (Array) | Default: ['close']

Add corresponding control buttons in the top bar area.
Control buttons will be ordered from the array order.
Allowed values: zoom, play, fullScreen, download, share, close.

Example:

controls : ['zoom', 'play', 'fullScreen', 'download', 'share', 'close']

prevNext Type: (boolean) | Default: true

Show/hide prev and next navigation buttons.

Example:

prevNext : false

prevNextTouch Type: (boolean) | Default: false

Show/hide prev and next navigation buttons on small touch capable devices.

Example:

prevNextTouch : true

counterMessage Type: (string|null) | Default: '[index] / [total]'

Message used in the item counter.
If empty, no counter will be displayed.

Message uses shortcode system:

[index]  :  Current item number
[total]  :  Total number of items in the opened gallery

Example:

counterMessage : '[index] on [total]'

caption Type: (boolean) | Default: true

Show/hide caption under media.

Example:

caption : false

autoCaption Type: (boolean) | Default: false

Auto generate captions from title and/or alt attributes if data-title and/or data-desc attributes are missing in the markup.

Example:

autoCaption : true

captionSmallDevice Type: (boolean) | Default: true

Show/hide caption under media on small browser sizes (in width and height) like mobile devices.
Works on desktop and mobile devices.

Example:

captionSmallDevice : false

thumbnails Type: (boolean) | Default: true

Enable/disable thumbnails navigation slider at the bottom of the lightbox.

Example:

thumbnails : false

thumbnailsNav Type: (string) | Default: 'basic'

Navigation type for the thumbnails slider (basic or centered).

Example:

thumbnailsNav : 'centered'

thumbnailSizes Type: (Object) | Default: see example

Set thumbnails sizes for different browser widths.
Unlimited number of browser widths can be passed to the object
If the width or the height is set to 0, no thumbnail will be displayed for the corresponding browser width.

Example:

thumbnailSizes : {
    1920 : {          // browser width in 'px'
        width  : 110, // thumbnail width in 'px' - 0 in width will hide thumbnails
        height : 80,  // thumbnail height in 'px' - 0 in height will hide thumbnails
        gutter : 10   // gutter width in 'px' between thumbnails
    },
    1280 : {
        width  : 90,
        height : 65,
        gutter : 10
    },
    680 : {
        width  : 70,
        height : 50,
        gutter : 8
    },
    480 : {
        width  : 60,
        height : 44,
        gutter : 5
    }
}

spacing Type: (number) | Default: 0.1

Space in percent between each slide. For example, 0.1 will render as a 10% of sliding viewport width

Example:

spacing : 0.15

smartResize Type: (boolean) | Default: true

Allow images to overflow on top bar and/or caption on small devices (in width and height) only if image can entirely fill the full screen height.
Image will not overflow on thumbnails.
It's particulary usefull on mobile devices in order to fill the whole screen if possible depending of the image aspect ratio.

Example:

smartResize : false

overflow Type: (boolean) | Default: false

Allow images to overflow on top bar and/or caption.
Image will not overflow on thumbnails.
If enabled, smartResize option will be ignored.

Example:

overflow : true

loadError Type: (string) | Default: 'Sorry, an error occured while loading the content...'

Error message displayed when a media fails to load (onerror).

Example:

loadError : 'Sorry, an error occured...'

noContent Type: (string) | Default: 'Sorry, no content was found!'

Message displayed when no media/content was found.

Example:

noContent : 'Sorry, no content was found!'

prevNextKey Type: (boolean) | Default: true

Press left or right keyboard keys to navigate.

Example:

prevNextKey : false

scrollToNav Type: (boolean) | Default: false

Scroll with a mouseWheel to navigate next/prev.
Disabled if scrollToZoom set to true

Example:

scrollToNav : true

scrollSensitivity Type: (number) | Default: 15

threshold in px from when a method is called (to zoom, to navigate for example).
Useful to fine tune touchPad and free mouseWheel sensitivity.
The sensitivity will also depend of the velocity involved by the user when touching a touchPad or when wheeling a free mouseWheel.

Example:

scrollSensitivity : 60

zoomTo Type: (number|string) | Default: 'auto'

Zoom factor applied on zoom button click or on double click/tap.
auto value will scale to the natural image size, accept number value (e.g.: 2, 3, 4, etc...).

Example:

zoomTo : 4

minZoom Type: (number) | Default: 1.2

Min zoom factor required to enable Zoom feature.
The user will be able to zoom only if the image size displayed on screen can be scaled up by the minZoom factor in order to reach, at minimum, its original size.

Example:

minZoom : 1.5

maxZoom Type: (number) | Default: 4

Max zoom factor allowed when pinched/scrolled.

Example:

maxZoom : 3.5

doubleTapToZoom Type: (boolean) | Default: true

Double Tap/click to zoom on image.

Example:

doubleTapToZoom : false

pinchToZoom Type: (boolean) | Default: true

Pinch out with 2 fingers to zoom on image.

Example:

pinchToZoom : false

scrollToZoom Type: (boolean) | Default: false

Scroll with a mouseWheel to Zoom in/out.

Example:

scrollToZoom : true

escapeToClose Type: (boolean) | Default: true

Press escape keyboard key to close the lightbox.

Example:

escapeToClose : false

scrollToClose Type: (boolean) | Default: false

Scroll with a mouseWheel to close the lightbox.
Disabled if scrollToNav and/or scrollToZoom set to true.

Example:

scrollToClose : true

pinchToClose Type: (boolean) | Default: true

Pinch out with 2 fingers to close the lightbox.

Example:

pinchToClose : false

dragToClose Type: (boolean) | Default: true

Drag vertically to close the lightbox.

Example:

dragToClose : false

tapToClose Type: (boolean) | Default: true

Tap/click outside the image/media to close the lightbox.

Example:

tapToClose : false

shareButtons Type: (Array) | Default: ['facebook', 'googleplus', 'twitter', 'pinterest', 'linkedin', 'reddit']

Add social sharing button(s) in the share tooltip holder
Social sharing buttons will be ordered from the array order.

Allowed values: facebook, googleplus, twitter, pinterest, linkedin, reddit, stumbleupon, tumblr, blogger, buffer, digg, evernote.

Example:

shareButtons : ['facebook', 'googleplus', 'twitter']

shareText Type: (string|null) | Default: 'Share on'

Text displayed above social sharing buttons inside the tooltip.
Empty value will completely remove text DOM holder from the tooltip.

Example:

shareText : 'Share on'

sharedUrl Type: (string) | Default: 'deeplink'

url used to share the media.
Allowed values: deeplink, page, media

Example:

sharedUrl : 'media'

slideShowInterval Type: (number) | Default: 4000

Time interval, in milliseconds, between slide changes in slideshow mode.
Require play control in the controls options.

Example:

slideShowInterval : 6300

slideShowAutoPlay Type: (boolean) | Default: false

Automatically start slideShow mode on opening.
If videoAutoPlay is enabled, the slideshow will not start if the slide contains a video.

Example:

slideShowAutoPlay : true

slideShowAutoStop Type: (boolean) | Default: false

Stop slideShow mode when the last item is reached (only if slider loop).

Example:

slideShowAutoStop : true

countTimer Type: (boolean) | Default: true

Show a circular countdown timer next to the counter message when slideShow (slideshow).

Example:

countTimer : false

countTimerBg Type: (string) | Default: 'rgba(255,255,255,0.25)'

Background color of the circular count timer stroke.

Example:

countTimerBg : '#f5f6fa'

countTimerColor Type: (string) | Default: 'rgba(255,255,255,0.75)'

Color of the circular count timer stroke.

Example:

countTimerColor : '#ffffff'

mediaelement Type: (boolean) | Default: false

Play HTML5 videos with mediaelement.js.
jQuery library & mediaelement.js script required.
You will find in the main package of MobuloBox a stylesheet and .svg icons files for mediaelement.js controls (used in the live demo).

Example:

mediaelement : true

videoRatio Type: (number) | Default: 16/9

Video aspect ratio used in the lightbox for HTML5 and iframe videos (Youtube, Vimeo, Dailymotion, Wistia).

Example:

videoRatio : 4/3

videoMaxWidth Type: (number) | Default: 1180

Maximum video width authorized for video in a slide.
Videos are responsive and will be resized according to this value and the aspect ratio set for videoRatio.

The max width can be overrided by the HTML5 data atrribute data-width set in the markup.

Example:

videoMaxWidth : 1180

videoAutoPlay Type: (boolean) | Default: false

Autoplay video on opening.

Example:

videoAutoPlay : true

videoThumbnail Type: (boolean) | Default: false

Automatically fetches poster/thumbnails of iframe video if missing.

Example:

videoThumbnail : true

Methods

Methods are actions done by ModuloBox instance.
JavaScript methods look like mobx.methodName( /* arguments */ ).
Methods cannot be chained together. 

// create instance of ModuloBox
var mobx = new ModuloBox();

mobx.init();
mobx.open( 'gallery1', 0 );

.init()

Initialize ModuloBox instance.
If the current url contains query strings guid and mid from ModuloBox, the lightbox will be automatically opened once initialized.

Events can be declared before this method.

Arguments

  1. none

Example

// initialize Mobulobox instance
mobx.init();

.destroy()

Destroy ModuloBox instance.

Arguments

  1. none

Example

// destroy lightbox
mobx.destroy();

.open( gallery, index )

Open the lightbox from a gallery name and media index.
If no gallery name was given, the default gallery name is 1.

Arguments

  1. gallery (string)Name of the gallery to open
  2. Index (number)Index of the media to show on opening (zero-based numbering)

Example

// open the lightbox from 'gallery-1' on media 10
mobx.open( 'gallery-1', 10 );

.close()

Close the lightbox.

Arguments

  1. none

Example

// close the lightbox
mobx.close();

.next()

Go to the next slide.

Arguments

  1. none

Example

// go to the next slide
mobx.next();

.prev()

Go to the previous slide.

Arguments

  1. none

Example

// go to the previous slide
mobx.prev();

.slideTo( index )

Go to slide by index.

Arguments

  1. index (number)Index of the media (zero-based numbering)

Example

// slide to slide index 3
mobx.slideTo( 3 );

.zoomTo( clientX, clientY, scale )

Zoom current slide to a scale factor on X and Y coordinates in px.

Arguments

  1. clientX (number)X coordinate in px relative of the window viewport
  2. clientY (number)Y coordinate in px relative of the window viewport
  3. scale (number)Scale fator applied on zoom

Example

// zoom with 3.5 factor on coordinate x: 800px, y: 600px
mobx.zoomTo(  800, 600, 3.5 );

.play()

Starts auto-play slideshow.

Arguments

  1. none

Example

// auto-play slideshow
mobx.play();

.stopPlay()

Stops auto-play slideshow.

Arguments

  1. none

Example

// stop slideshow
mobx.stopPlay();

.download()

Download current media displayed in the lightbox.
Only works with images and HTML5 videos.

Arguments

  1. none

Example

// download current media
mobx.download();

.getMedia()

Get current media data.
Return an object.

Arguments

  1. none

Example

// get current media data
var media = mobx.getMedia();
console.dir(media);

/* media object example
media = {
    caption : 'Image caption',
    desc    : 'Image description',
    dom     : {oject},
    index   : 0,
    poster  : null,
    src     : 'path/to/image.jpg',
    thumb   : 'path/to/thumbnail.jpg',
    title   : 'Image title'
    type    : 'image'
}
*/

.addMedia( gallery, media )

Allows to push dynamically media in a gallery (new or existing one).
This method must be used before to init() the instance of ModuloBox.
This method should be used inside the event updateGalleries in order to push the media collection on init() and when all galleries are fetched in the document.

Arguments

  1. gallery (string)Name of the gallery where media will be pushed
  2. media (Object)Media collection

Example

// create instance of ModuloBox
var mobx = new ModuloBox( /* options */ );

// set media array
var media = [
    // image
    {
        src    : 'path/to/image1.jpg',
        thumb  : 'path/to/thumbnail-1.jpg',
        title  : 'Image title',
        desc   : 'Image Description'
    },
    // HTML5 video
    {
        src    : 'path/to/video.mp4, path/to/video.ogv, path/to/video.webm',
        thumb  : 'path/to/thumbnail-2.jpg',
        poster : 'path/to/poster-1.jpg',
        title  : 'HTML5 video title',
        desc   : 'HTML5 video Description'
    },
    // iframe video
    {
        src    : 'https://youtu.be/M7lc1UVf-VE',
        thumb  : 'path/to/thumbnail-3.jpg',
        poster : 'path/to/poster-2.jpg',
        title  : 'Youtube video title',
        desc   : 'Youtube video Description'
    },
    // HTML
    {
        src    : '#content',
        thumb  : 'path/to/thumbnail-4.jpg',
        type   : 'HTML', // type key required for HTML content
        title  : 'HTML title',
        desc   : 'HTML Description'
    },
    // iframe
    {
        src    : 'https://www.google.com/maps/embed',
        thumb  : 'path/to/thumbnail1-5.jpg',
        type   : 'iframe', // type key required for iframe
        title  : 'iframe title',
        desc   : 'iframe Description'
    }
];

// bind updateGalleries event
mobx.on( 'updateGalleries.modulobox', function( galleries ) {

    // add media to a gallery
    mobx.addMedia( 'my gallery', media );

});

// initialize the instance
mobx.init();

.resizeMedia()

Resize current media and closest media in the slider viewport.

Arguments

  1. none

Example

// resize all media in the slider viewport
mobx.resizeMedia();

.getGalleries()

Allows to fetch all media galleries in the document.
It will update all media data present in the document and will dispatch the event updateGalleries.
It's particularly useful when you append new media in your document and want to take them into account for the ligthbox.
If the lightbox was open when getting galleries, you will need to re-open it again in order to see new added media.

Arguments

  1. none

Example

// get/update all media available in the document
mobx.getGalleries();

Events

ModuloBox will dispatch several events after initialization.
These events can be listened with JavaScript. Event names are namespaced with .modulobox.
To correctly listen all events, particular ones dispatched on init(), it is better to declare them before to initialize MobuloBox instance.

Example

function listener( /* parameters */ ) {
    console.log( 'eventName happened' );
}

// create instance of ModuloBox
var mobx = new ModuloBox( /* options */ );

// bind event listener
mobx.on( 'eventName.modulobox', listener );

// initialize the instance
mobx.init();

beforeOpen

Event dispatched before the lightbox is opened.
This event can be useful to modify an options of the instance.
Options related to DOM/Interface like buttons/controls cannot be changed on beforeOpen because they are only used when generating the DOM before init() method.

Parameters

  1. gallery (string)Gallery Name
  2. index (number)Media index (zero-based numbering)

Example

mobx.on( 'beforeOpen.modulobox', function( gallery, index ) {

     console.log( 'BeforeOpen:' + '\n' + 
                  '\t- gallery name => ' + gallery + '\n' + 
                  '\t- media index  => ' + index );

});

afterOpen

Event dispatched after the lightbox is opened on transition ends.

Parameters

  1. gallery (string)Gallery Name
  2. index (number)Media index (zero-based numbering)

Example

mobx.on( 'afterOpen.modulobox', function( gallery, index ) {

     console.log( 'afterOpen:' + '\n' + 
                  '\t- gallery name => ' + gallery + '\n' + 
                  '\t- media index  => ' + index );

});

beforeClose

Event dispatched before the lightbox start to be closed.

Parameters

  1. gallery (string)Gallery Name
  2. index (number)Media index (zero-based numbering)

Example

mobx.on( 'beforeClose.modulobox', function( gallery, index ) {

     console.log( 'beforeClose:' + '\n' + 
                  '\t- gallery name => ' + gallery + '\n' + 
                  '\t- media index  => ' + index );

});

afterClose

Event dispatched when the lightbox is closed on transition ends.

Parameters

  1. gallery (string)Gallery Name
  2. index (number)Media index (zero-based numbering)

Example

mobx.on( 'afterClose.modulobox', function( gallery, index ) {

     console.log( 'afterClose:' + '\n' + 
                  '\t- gallery name => ' + gallery + '\n' + 
                  '\t- media index  => ' + index );

});

updateGalleries

Event dispatched when media (from gallery(ies)) are retrieved in the document and are parsed.
This event is dispatched on init() and can be used to dynamically push media in gallery with addMedia() method.

Parameter

  1. galleries (Object)return the galleries media collection

Example

// bind updateGalleries event
mobx.on( 'updateGalleries.modulobox', function( galleries ) {

     console.log( 'Galleries (media) updated' );
     console.log( galleries );

});

updateMedia

Event dispatched when the media on screen is updated when navigating or on resize.
It can be used to customize UI depending of a media (see example 2)

Parameters

  1. gallery (string)Gallery Name
  2. index (number)Media index (zero-based numbering)

Example 1

mobx.on( 'updateMedia.modulobox', function( gallery, index ) {

     console.log( 'updateMedia:' + '\n' + 
                  '\t- gallery name => ' + gallery + '\n' + 
                  '\t- media index  => ' + index );

});

Example 2

mobx.on( 'updateMedia.modulobox', function( gallery, index ) {

    var color = '#';

    // generate random color
    for ( var i = 0; i < 6; i++ ) {
        color += '0123456789ABCDEF'[Math.floor( Math.random() * 16 )];
    }

    // set a random background color to the lightbox overlay
    // you can access to all lightbox DOMs with this.DOM
    this.DOM.overlay.style.backgroundColor = color;

});

loadComplete

Event dispatched when an image is fully loaded.

Parameters

  1. gallery (string)Gallery Name
  2. index (number)Media index (zero-based numbering)

Example

mobx.on( 'loadComplete.modulobox', function( gallery, index ) {

     console.log( 'loadComplete:' + '\n' + 
                  '\t- gallery name => ' + gallery + '\n' + 
                  '\t- media index  => ' + index );

});

loadError

Event dispatched when an image fails to load (onerror).

Parameters

  1. gallery (string)Gallery Name
  2. index (number)Media index (zero-based numbering)

Example

mobx.on( 'loadError.modulobox', function( gallery, index ) {

     console.log( 'loadError:' + '\n' + 
                  '\t- gallery name => ' + gallery + '\n' + 
                  '\t- media index  => ' + index );

});

noContent

Event dispatched when no media was found to load.

Parameters

  1. gallery (string)Gallery Name
  2. index (number)Media index (zero-based numbering)

Example

mobx.on( 'noContent.modulobox', function( gallery, index ) {

     console.log( 'noContent:' + '\n' + 
                  '\t- gallery name => ' + gallery + '\n' + 
                  '\t- media index  => ' + index );

});

resize

Event dispatched when the lightbox (window) was resized.

Parameter

  1. Event (Object)Original event object

Example

mobx.on( 'resize.modulobox', function( event ) {

     console.log( 'resized' );
     console.log( event );

});

dragSliderStart

Triggered when the user's pointer initiates an horizontal movement (more than the threshold) on the slider.

Parameters

  1. event (Object)Original event object
  2. gesture (Object)return pointer coordinates and delta displacements in X & Y axis

Example

mobx.on( 'dragSliderStart.modulobox', function( event, gesture ) {

     console.log( 'Drag Slider Start' );
     console.log( gesture );

     /* gesture output example :
     gesture = {
        x  : 450,
        y  : 200,
        dx : 20,
        dy : 5
     }
     */

});

dragSliderMove

Triggered when the user's pointer moves (dispatched after dragSliderStart).

Parameters

  1. event (Object)Original event object
  2. gesture (Object)return pointer coordinates and delta displacements in X & Y axis

Example

mobx.on( 'dragSliderMove.modulobox', function( event, gesture ) {

     console.log( 'Drag Slider Move' );
     console.log( gesture );

     /* gesture output example :
     gesture = {
        x  : 450,
        y  : 200,
        dx : 20,
        dy : 5
     }
     */

});

dragSliderEnd

Triggered when the user's pointer is released (dispatched after dragSliderMove).

Parameters

  1. event (Object)Original event object
  2. gesture (Object)return pointer coordinates and delta displacements in X & Y axis

Example

mobx.on( 'dragSliderEnd.modulobox', function( event, gesture ) {

     console.log( 'Drag Slider End' );
     console.log( gesture );

     /* gesture output example :
     gesture = {
        x  : 450,
        y  : 200,
        dx : 20,
        dy : 5
     }
     */

});

sliderProgress

Triggered when the slider moves (with or without pointer interaction).
This event can be used to add css transformations when the slider moves (see example 2).

Parameter

  1. progress (number)How far slider has moved, from 0 at the first slide to 1 at the end

Example 1

mobx.on( 'sliderProgress.modulobox', function( progress ) {

    console.log( 'Slider Progress' );
    console.log( progress );

});

Example 2 (IOS parallax effect)

mobx.on( 'sliderProgress.modulobox', function( progress ) {

    var cells    = this.cells, // cells are present in slides
        slides   = this.slides, // slides are present in slider
        position = this.slider.position.x; // current slider position

    // add transform for each cell regarding current slider position
    for ( var cell in cells ) {

        var x = ( parseInt( slides[cell].style.left ) + position ) * -1/3;
        cells[cell].element.style.transform = 'translateX( ' + x + 'px )';

    }

});

sliderSettled

Triggered when the slider is settled at its end position.

Parameter

  1. position (Object)Current slider position in X & Y axis (in px)

Example

mobx.on( 'sliderSettled.modulobox', function( position ) {

    console.log( 'Slider Settled' );
    console.log( position );

    /* position output example :
    position = {
        x : 450,
        y : 0
    }
    */

});

dragThumbsStart

Triggered when the user's pointer initiates an horizontal movement (more than the threshold) on the thumbnails slider.

Parameters

  1. event (Object)Original event object
  2. gesture (Object)return pointer coordinates and delta displacements in X & Y axis

Example

mobx.on( 'dragThumbsStart.modulobox', function( event, gesture ) {

    console.log('Drag Thumbs Start');
    console.log( gesture );

    /* gesture output example :
    gesture = {
        x  : 450,
        y  : 200,
        dx : 20,
        dy : 5
    }
    */

});

dragThumbsMove

Triggered when the user's pointer moves (dispatched after dragThumbsStart).

Parameters

  1. event (Object)Original event object
  2. gesture (Object)return pointer coordinates and delta displacements in X & Y axis

Example

mobx.on( 'dragThumbsMove.modulobox', function( event, gesture ) {

    console.log('Drag Thumbs Move');
    console.log( gesture );

    /* gesture output example :
    gesture = {
        x  : 450,
        y  : 200,
        dx : 20,
        dy : 5
    }
    */

});

dragThumbsEnd

Triggered when the user's pointer is released (dispatched after dragThumbsMove).

Parameters

  1. event (Object)Original event object
  2. gesture (Object)return pointer coordinates and delta displacements in X & Y axis

Example

mobx.on( 'dragThumbsEnd.modulobox', function( event, gesture ) {

    console.log('Drag Thumbs End');
    console.log( gesture );

    /* gesture output example :
    gesture = {
        x  : 450,
        y  : 200,
        dx : 20,
        dy : 5
    }
    */

});

thumbsProgress

Triggered when the thumbnails slider moves (with or without pointer interaction).

Parameter

  1. progress (number)How far thumbnails slider has moved, from 0 at the first thumb to 1 at the end

Example

mobx.on( 'thumbsProgress.modulobox', function( progress ) {

    console.log( 'Thumbs Slider Progress' );
    console.log( progress );

});

thumbsSettled

Triggered when the thumbnails slider is settled at its end position.

Parameter

  1. position (Object)Current thumbnails slider position in X (in px)

Example

mobx.on( 'thumbsSettled.modulobox', function( position ) {

    console.log( 'Thumbs Slider Settled' );
    console.log( position );

    /* position output example :
    position = {
        x : -200
    }
    */

});

panYStart

Triggered when the user's pointer initiates a vertical movement (more than the threshold) on the slider to close the lightbox.
PanY can only occurs if dragToClose options is enabled and that the slider is near settled.

Parameters

  1. event (Object)Original event object
  2. gesture (Object)return pointer coordinates and delta displacements in X & Y axis

Example

mobx.on( 'panYStart.modulobox', function( event, gesture ) {

    console.log( 'PanY Start' );
    console.log( gesture );

    /* gesture output example :
    gesture = {
        x  : 450,
        y  : 200,
        dx : 20,
        dy : 5
    }
    */

});

panYMove

Triggered when the user's pointer moves (dispatched after panYStart).

Parameters

  1. event (Object)Original event object
  2. gesture (Object)return pointer coordinates and delta displacements in X & Y axis

Example

mobx.on( 'panYMove.modulobox', function( event, gesture ) {

    console.log( 'PanY Move' );
    console.log( gesture );

    /* gesture output example :
    gesture = {
        x  : 450,
        y  : 200,
        dx : 20,
        dy : 5
    }
    */

});

panYEnd

Triggered when the user's pointer is released (dispatched after panYMove).

Parameters

  1. event (Object)Original event object
  2. gesture (Object)return pointer coordinates and delta displacements in X & Y axis

Example

mobx.on( 'panYEnd.modulobox', function( event, gesture ) {

    console.log( 'PanY End' );
    console.log( gesture );

    /* gesture output example :
    gesture = {
        x  : 450,
        y  : 200,
        dx : 20,
        dy : 5
    }
    */

});

panYProgress

Triggered when the slide moves in Y (with or without pointer interaction).

Parameter

  1. progress (number)How far slide has moved, from 0 at the center of the slide to 1 at the end

Example

mobx.on( 'panYProgress.modulobox', function( progress ) {

    console.log( 'PanY Progress' );
    console.log( progress );

});

panYSettled

Triggered when the slide is settled at its end position (center of the slider viewport).

Parameter

  1. position (Object)Current slide position in X, Y, scale

Example

mobx.on( 'panYSettled.modulobox', function( position ) {

    console.log( 'PanY Settled' );
    console.log( position );

    /* position output example :
    position = {
        x : 450,
        y : 200,
        s : 1   // s for scale
    }
    */

});

panZoomStart

Triggered when the user's pointer(s) initiates a pan in X, and/or X, and/or a pinch gesture(s) on a slide to panZoom.

Parameters

  1. event (Object)Original event object
  2. gesture (Object)return pointer coordinates and delta displacements in X & Y axis

Example

mobx.on( 'panZoomStart.modulobox', function( event, gesture ) {

    console.log( 'PanZoom Start' );
    console.log( gesture );

    /* gesture output example :
    gesture = {
        x     : 450,
        y     : 200,
        scale : 1.2,
        dx    : 20,
        dy    : 5
    }
    */

});

panZoomMove

Triggered when the user's pointer(s) moves to pan and/or zoom an image (dispatched after panZoomStart).

Parameters

  1. event (Object)Original event object
  2. gesture (Object)return pointer coordinates and delta displacements in X & Y axis

Example

mobx.on( 'panZoomMove.modulobox', function( event, gesture ) {

    console.log( 'PanZoom Move' );
    console.log( gesture );

    /* gesture output example :
    gesture = {
        x     : 450,
        y     : 200,
        scale : 1.2,
        dx    : 20,
        dy    : 5
    }
    */

});

panZoomEnd

Triggered when the slide is settled after a panZoom gesture (dispatched after panZoomMove).

Parameters

  1. event (Object)Original event object
  2. gesture (Object)return pointer coordinates and delta displacements in X & Y axis

Example

mobx.on( 'panZoomEnd.modulobox', function( progress ) {

    console.log( 'PanZoom End' );
    console.log( progress );

    /* gesture output example :
    gesture = {
        x     : 450,
        y     : 200,
        scale : 1.2,
        dx    : 20,
        dy    : 5
    }
    */

});

panZoomProgress

Triggered when the slide is scrolled or scaled (with or without pointer interaction).

Parameter

  1. progress (number)How much slide has been scaled, from 0 to maxZoom

Example

mobx.on( 'panZoomProgress.modulobox', function( progress ) {

    console.log( 'PanZoom Progress' );
    console.log( progress );

});

panZoomSettled

Triggered when the slide is settled after a pan in X and/or Y, and/or zoom gesture(s).

Parameter

  1. position (Object)Current slide position in X/Y/Scale

Example

mobx.on( 'panZoomSettled.modulobox', function( position ) {

    console.log( 'PanZoom Settled' );
    console.log( position );

    /* position output example :
    position = {
        x : 450,
        y : 200,
        s : 1   // s for scale
    }
    */

});