Three things must be done to make lightbox work: include JavaScript and CSS files, mark which links should open in lightbox, and initialize the script.
Save the skLib.lightbox package – skLib.lightbox.js and .css files, as well as images – somewhere among the website's files, for example in /lightbox folder. It doesn't matter where; you'll specify path for the .js and .css files in the script and link tags, and the path to image folder can be changed in initialization call, though /lightbox/images is the default location.
skLib.lightbox.js
.css
/lightbox
.js
script
link
/lightbox/images
jQuery is required, as is imagesLoaded.js file, the lightbox won't work without them. We recommend you also add jquery.event.move.js and jquery.mousewheel.js plugins, but the lightbox will work without them, only the relevant functionalities will be missing if you don't use them.
imagesLoaded.js
jquery.event.move.js
jquery.mousewheel.js
Example (or you can just copy this code):
Though it can be changed in case some other approach fits your site better, by default the lightbox will use all links with CSS class "skLib-lightboxLink".
"skLib-lightboxLink"
So a link should look something like this:
A simple call of skLib.lightbox.init(); should be enough to finish setting up lightbox. But you might want to make sure all external files have finished loading so there isn't a JavaScript error.
skLib.lightbox.init();
This should do:
Above snippets will get you the basic functionality. There won't be any descriptions or galleries to browse through quickly though.
href
light-gallery
light-title
light-desc
light-type
Type of a slide. In almost all cases the lightbox will be able to determine the type correctly, so you can safely ignore it. But in some situations it might be necessary to manually set how the slide should be presented; for example if you want to open a page in iframe, but its URL just happens to end with .jpg.
.jpg
Possible values: image, video, iframe.
image
video
iframe
light-width
light-height
10000
variation
light-variations
List of size variations of the image (pairs of URL and width). Separate individual images with semicolon (;), and url and width with at sign (@). For example, definition "image1.jpg@100;image2.jpg@500" lists two images, image1.jpg width width of 100 pixels, image2.jpg width width of 500 pixels. Only width is supported, not height, and aspect ratio is presumed to be the same for every variation.
;
@
"image1.jpg@100;image2.jpg@500"
Example:
Most YouTube, Vimeo and Dailymotion links will be automatically detected and values for video code, player and embedded URL filled accordingly, so they don't have to be explicitly set. But please check after entering any new URLs, because not all video hosting services and all of their URLs are supported for automatic detection.
light-url
URL to use for the frame if different from linked URL.
In some cases you might want to use one URL for link and different one for the frame shown in lightbox. For example, if in lightbox the page should be without navigation and branding, but if a user chooses to open link in a new tab or window, or JavaScript is either not yet loaded or blocked, what the user sees should be the full version of the page. Because of this we recommend that the URL in href attribute is set to what the user should see as if lightbox was not used at all.
light-video_code
light-player
"youtube"
"vimeo"
"dailymotion"
light-ratio
Aspect ratio of the frame (e.g. "16:9" or "1.7777").
"16:9"
"1.7777"
Video: Default value is "16:9".
Frame: Ratio is not fixed by default. You can either specify a specific ratio or set both width and height and set ratio to 1, yes or true.
1
yes
true
Maximum dimensions of video or frame.
Video: Default value of width is 10000. Default height is calculated by ratio.
Frame: If a specific aspect ratio is set and neither dimension is set, default width is 10000 and height is calculated by ratio.
If both dimensions and a specific aspect ratio is set (video: always; frame: if not left undefined), value of light-ratio is overriden by aspect ratio of specified width and height.
Function skLib.lightbox.init(config) accepts a configuration object to better adapt lightbox to the page where it's used. Once set, configuration will be preserved even if you call init again, for example when you dynamically add, remove or change links.
skLib.lightbox.init(config)
init
rootSelector
jQuery selector for a root container within html node that encompasses all content on the page, but is unstyled. In ASP.NET projects "form" can be used. Used for locking page scroll while lightbox is open.
html
"form"
What happens is this: the root container is placed absolutely (100% width and height of the browser window) and content is scrolled within it so it appears as if nothing had changed. This preserves current position on the page, while completely disabling page scrolling, even on mobile devices of which some would otherwise ignore overflow styles.
overflow
When lightbox is closed, previous styles are restored. Page is scrolled back to the point it was when lightbox was opened, so even without a root container the behaviour should be the same. However, if lightbox's background is transparent, scrolling will be noticeable.
linkSelector
".skLib-lightboxLink"
iconsDir
"lightbox/images"
linkData
imageWidth
imageHeight
containerWidth
containerHeight
fitWidth
fitHeight
isRtl
body
direction: rtl;
youtubeParams
"autohide=1&autoplay=1&modestbranding=1&showinfo=0&theme=dark&rel=0&color=white"
vimeoParams
"title=0&byline=0&portrait=0&fullscreen=1&autoplay=1"
dailymotionParams
"autoPlay=1&related=0&logo=0"
commands
An array of additional toolbar commands, for example save to disk or share. These commands are rendered as links: icon, name and target are defined globally, while specific URL is specified for each lightbox link separately. If no URL is given, the command icon is not displayed.
Each command has the following values: icon is URL of the icon image; text is name of the command used in alt text and title attributes; attr is the name of the attribute of a lightbox link which contains the URL of the command; target is, well, target of the command link.
icon
text
attr
target
There are two ways to use image variations. First is by specifying all images and their widths in link attributes. The other option is to use a JavaScript function to generate the image URL based on the linked URL and browser size. JavaScript function is the better choice if your web site can automatically resize images. But if you're resizing images manually and don't want to use image variations on every lightbox link, listing the image variations in each link's attribute will suite you better. In case you're using both, the attribute will take priority wherever it's set.
Here is an example of how to set it through an attribute. Here image1.jpg is 1000px wide and image2.jpg is 500px wide; height is calculated according to the aspect ratio of the full image (2000×1500px or 4:3), 750px and 375px respectively.
image1.jpg
image2.jpg
If you'd rather use a JavaScript function to generate URLs for all images' variations, this is how it can be done. Lightbox will call the function configured in the first initialization with a number of parameters and expect it to return a URL of the image.
The call looks something like this:
The parameters are:
.link
<a>
.file
.type
"image"
"video"
"iframe"
.gallery
.descTitle
.desc
.image.width
.image.height
.video.player
.video.code
.video.ratio
.video.width
video.height
.iframe.width
iframe.height
This example uses a fixed list of variations. Each variation represents a limit of the longer side of the image; for example variation "500" may generate 500×300 or 300×500px images (among others), not 500×750px. Variation is here appended to the end of file name, e.g. "image-500.jpg".
You can add additional command links to lightbox. They will appear as icon links in the lightbox's toolbar and can link either to another URL or call a JavaScript method. A couple of sample images are included in the lightbox package, but you can add your own.
In the JavaScript initialization of the lightbox set the list of icons to add to its toolbar. For example:
Above example sets two commands, one to save to disk and one to share. URL can't be set here, because it's unique to each image.
The attr value of each command in itinialization is the name of the image link attribute from which the lightbox will pull the URL of the command. If an URL is not specified for an image, the icon will be hidden on its slide.
In this example save icon links to a .zip file, while share icon calls a local JavaScript method.
Demo
Initializes lightbox. Function parses all elements matching linkSelector condition. By default that is ".skLib-lightboxLink", meaning it'll find all elements with CSS class "skLib-lightboxLink". If the element does not have an ID, lightbox assigns it one and sets onclick event.
onclick
Initialization can be called multiple times, for example after content-altering AJAX calls. Configuration will be preserved, and you don't need to include it in any later calls.
skLib.lightbox.open(link)
skLib.lightbox.open(document.getElementById("link1"));
skLib.lightbox.close()
This is a representation of the HTML. You can use this template to prepare an alternate stylesheet.