Share on Facebook Tweet this

Lightcase.js

Documentation

Getting Started

First of all - download the source files, extract the archive and then upload the entire folder to your preferred location on your web server.
Then, just include the JavaScript/CSS files and follow the steps described in the section be from low. You also can have a look at the examples on demo page and how they are initialized. This can be figured out by checking the lightcase.init.js file. (Note: lightcase.init.js is not part of the lightcase plugin itself!)

Basic setup

Step 1: Lightcase is based on the jQuery framework, so first you have to load this library.

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>

Step 2: Now, include the CSS and JavaScript files for Lightcase.

<link rel="stylesheet" type="text/css" href="path/to/lightcase.css">
<script type="text/javascript" src="path/to/lightcase.js"></script>

Step 3: After including those files you have to define which links you want to open in Lightcase. Here we are using a wildcard selector for selecting all links which have an attribute "data-rel" beginning with "lightcase".

<script type="text/javascript">
	jQuery(document).ready(function($) {
		$('a[data-rel^=lightcase]').lightcase();
	});
</script>

Step 4: To open your media with Lightcase, create a link and add the attribute data-rel="lightcase".

<a href="path/to/media.jpg" data-rel="lightcase">Your link description or thumb</a>

Display title

In case you want to add a title, simply extend your link tag with the attribute title="Your title".

<a href="path/to/media.jpg" data-rel="lightcase" title="Your title">Your link description or thumb</a>

Videos

There are a couple of ways how to display videos on your website using lightcase. The most likely approach is to place it as HTML5 video which will be referred as type 'video' by lightcase. Of course, it is also possible to present external videos from Youtube, Vimeo or other video platforms, or as Adobe Flash video.

<a href="path/to/media.mp4" data-rel="lightcase">HTML5 video</a>
<a href="//www.youtube.com/embed/6v2L2UGZJAM?version=3" data-rel="lightcase">Youtube video</a>
<a href="path/to/media.swf" data-rel="lightcase">Flash video</a>

Different video file formats can be provided using the attribute 'data-lc-href' and have best browser support. Lightcase will do the rest and pick the one with the most presumable support of the actual browser. Note: Sources are delimited using comma. (since v2.4.0)

<a href="" data-lc-href="path/to/media.mp4, path/to/media.webm, path/to/media.ogg" data-rel="lightcase">HTML5 video using different file formats</a>

Source sets

For different sources to be loaded related to the current browser viewport width or device density, you can use the following notation below. There is no limitation for sources as well as a combination with viewport and density (Device Pixel Ratio) is possible. Note: Sources are delimited using comma. (since v2.3.0)

<a href="" data-lc-href="path/to/media1_small.jpg, path/to/media1_large.jpg 2x" data-rel="lightcase">Your link description or thumb</a>
<a href="" data-lc-href="path/to/media2_default.jpg, path/to/media2_small.jpg 320w, path/to/media2_small_2x.jpg 320w 2x" data-rel="lightcase">Link</a>

Collections

Couple of links with same attribute will open all of them as a collection.

<a href="path/to/media1.jpg" data-rel="lightcase:myCollection">Your link description or thumb</a>
<a href="path/to/media2.jpg" data-rel="lightcase:myCollection">Your second collection item</a>
<a href="path/to/media3.jpg" data-rel="lightcase:myCollection">Your third item, and so on...</a>

Within collections it is also possible to use various categories which can make your collections much more powerful. Lightcase looks for matching categories within a certain collection and will show them separated depending on the link was clicked to invoke Lightcase. Note: Categories are delimited using spaces. (since v2.2.0)

<a href="path/to/media1.jpg" data-rel="lightcase:myCollection" data-lc-categories="myCategory1 myCategory2">Your link description or thumb</a>
<a href="path/to/media2.jpg" data-rel="lightcase:myCollection" data-lc-categories="myCategory1">Your second collection item</a>
<a href="path/to/media3.jpg" data-rel="lightcase:myCollection" data-lc-categories="myCategory2 myCategory3 myCategory4">Your third item, and so on...</a>

Slideshow

Collections with trailing ":slideshow" in the attribute 'data-rel' will open them as a slideshow.

<a href="path/to/media.jpg" data-rel="lightcase:myCollection:slideshow" title="Your title">Your link description or thumb</a>

Advanced

Options

Lightcase provides various options to customize and override defaults. All possible options are described in section API.

$('a[data-rel=lightcase:myCollection:slideshow]').lightcase({
	transition: 'scrollHorizontal',
	showSequenceInfo: false,
	showTitle: false
});

Alternatively, it is even possible to apply you options directly with a tag attribute. (since v2.3.5)

<a href="path/to/media.jpg" data-lc-options='{"maxWidth":440, "maxHeight":550}' data-rel="lightcase">Your link description</a>
Hooks

There are several functions to intervene into the process Lightcase is doing until the content gets displayed. This may could be useful if you want to manipulate the standard process of Lightcase like pre-validating a form, changing something in the markup or anything else you could imagine.

$('a[data-rel=lightcase]').lightcase({
	// Would be called immediately after lightcase is initialized
	onInit : {
		foo: function() {
			alert('Lightcase process is initialized');
		}
	},
	// Would be called before generating content
	onStart : {
		bar: function() {
			alert('Lightcase process is started');
		}
	},
	// Would be called right before showing the content
	onFinish : {
		baz: function() {
			alert('Lightcase process is finished');
		}
	},
	// Would be called when aborting lightcase
	onClose : {
		qux: function() {
			alert('Lightcase closes now');
		}
	},
	// Would be called when lightcase does the cleanup
	onCleanup : {
		quux: function() {
			alert('Lightcase process is cleaned up');
		}
	}
});

How can I access all the DOM objects/elements of lightcase from e.g. within such a hook function above?

// All public available objects and methods
console.log(lightcase);

// Get the origin link object as a jQuery ready object
console.debug($(this));

// Get a specific Lightcase DOM object (since v2.3.0)
console.debug(lightcase.get('case'));

How can I open Lightcase in a blank popup?

// With javascript only and without any trigger link
lightcase.start({
  href: '#',
  // more options like width, height, etc.
});

// From a simple link within markup
<a href="#" data-rel="lightcase">Open blank popup</a>

How can I close Lightcase via function?

// Call public function to close lightcase
lightcase.close();

// Example for automatically closing lightcase after five seconds using a hook function
$('#foo').lightcase({
  onFinish: {
    autoClose: function () {
      setTimeout(function () {
        lightcase.close();
      }, 5000);
    }
  }
});

Resize

As mentioned, Lightcase is indeed really flexible. While you already are able to use several hooks to adjust, change, manipulate your content within the box, you're also able to initialize a recalculation of your content size. Use this call as soon as you did modifications with the current Lightcase content.

lightcase.resize();

Mobile

Swipe

For supporting swipe for touch devices, you additionally need to include the provided 'jquery.events.swipe.js' as well as to make sure that option 'swipe' is set to 'true'. This will make possible to browse though collections by just swiping to the left or right with fingers.

<script type="text/javascript" src="path/to/jquery.events.touch.js"></script>
$('a[data-rel^=lightcase]').lightcase({
	swipe: true
});

Fullscreen mode for mobile

There is an extra feature to use the full width for mobile devices only without respecting the 'shrinkFactor'. You just have to ensure that the option 'fullscreenModeForMobile' is enabled and for a proper display the following meta tag is included into the <head> part of your source code. Additionally, a special class name 'lightcase-fullScreenMode' will be set to the <html> tag in case you want to do some style adjustments as well.

<meta name="viewport" content="width=device-width, initial-scale=1">

API

Property Type Default Description
idPrefix String
'lightcase-'
Identifier prefix for the lightcase objects. (since v1.4.4)
classPrefix String
'lightcase-'
Class name prefix for the lightcase objects. (since v1.3.0)
attrPrefix String
'lc-'
Name prefix for all attributes related to lightcase. (since v2.2.0)
transition String
'elastic'
Transition between the sequences for groups and slideshow.
Available values are 'none', 'fade', 'fadeInline', 'elastic', 'scrollTop', 'scrollRight', 'scrollBottom', 'scrollLeft', 'scrollHorizontal' and 'scrollVertical'.
transitionOpen String|null
null
Extra definition for the transition while opening lightcase. (since 2.4.0)
transitionClose String|null
null
Extra definition for the transition while closing lightcase. (since 2.4.0)
transitionIn String|null
null
Extra definition for the 'in' transition. (since 1.4.0)
transitionOut String|null
null
Extra definition for the 'out' transition. (since 1.4.0)
cssTransitions Boolean
true
Enable transitions with css. (since 1.4.0)
speedIn Integer
350
Animation speed for the starting transition.
speedOut Integer
250
Animation speed for the ending transition.
width Integer|null
null
Exact width for the media content. (since 2.4.0)
height Integer|null
null
Exact height for the the media content. (since 2.4.0)
maxWidth Integer
800
Maximum width for the media content.
maxHeight Integer
500
Maximum height for the media content.
forceWidth Boolean
false
Force width to prevent from shrinking. (since v1.1.0)
forceHeight Boolean
false
Force height to prevent from shrinking. (since v1.1.0)
liveResize Boolean
true
Enable live resize. (since v1.2.0)
fullScreenModeForMobile Boolean
true
Enable fullscreen mode for mobile devices. (since v1.3.0)
mobileMatchExpression RegExp
/(iphone|ipod|ipad...)/
Mobile devices which should make use of fullscreen mode. (since v1.3.2)
fixedRatio Boolean
true
Keeps the ratio of the defined width and height proportionally if content is shrinked. (since v2.4.0)
disableShrink Boolean
false
Disable the shrink completely. (since v1.1.0)
shrinkFactor Integer
.75
Factor (in percent) to shrink the media content to recalculate dimensions.
overlayOpacity Integer
.9
Factor (in percent) for the overlay opacity.
slideshow Boolean
false
Default slideshow initialization for groups.
slideshowAutoStart Boolean
true
Starting slideshow automatically. (since v2.3.5)
timeout Integer
5000
Delayed time between the slideshow sequences.
swipe Boolean
true
Enable swipe event for mobile devices. (since v1.4.0)
useKeys Boolean
true
Activate keys to navigate.
useCategories Boolean
true
Enables or disables usage of categories within a specific collection. (since v2.2.0)
navigateEndless Boolean
true
If enabled, the slideshow will be never ending.
closeOnOverlayClick Boolean
true
Close Lightcase on overlay click.
title String|null
null
Value for the title text.(Since v1.6.0)
caption String|null
null
Value for the caption text. (Since v1.6.0)
showTitle Boolean
true
Display title defined if the link attribute is set.
showCaption Boolean
true
Display caption from the attribute 'alt'.
showSequenceInfo Boolean
true
Display information about the current sequence in groups.
inline Object
width : 'auto',
height : 'auto'
	
Options would be passed to the inline element.
ajax Object
width : 'auto',
height : 'auto',
type : 'get',
dataType : 'html',
data : {}
	
Option would be passed to the ajax element. (since v1.3.0)
Option would be passed to the ajax element. (since v1.3.0)
Type of request like 'get' or 'post' (since v1.5.0)
DataType of response like 'html', 'text', 'json', ... (since v1.5.0)
Data for request like a serialized array (since v1.5.0)
iframe Object
width : 'auto',
height : 'auto',
frameborder : 0
	
Options would be passed to the iframe element.
flash Object
width : 400,
height : 205,
wmode : 'transparent'
	
Options would be passed to the flash element.
video Object
width : 400,
height : 225,
poster : '',
preload : 'auto',
controls : true,
autobuffer : true,
autoplay : true,
loop : false
	
Options would be passed to the video element.
attr String
'data-rel'
Name of the attribute which should be used for initializing collections. (since v2.1.0)
href String
null
Force content source overriding the attributes 'href' and 'data-href'. (since v2.0.3)
type String
null
Force data type definition like 'inline' or 'ajax'. (since v1.4.2)
typeMapping Object
'image' : 'jpg,…',
'flash' : 'swf',
'video' : 'mp4,...',
'iframe' : 'html,...',
'ajax' : 'txt',
'inline' : '#'
	
Mapping for the media types. (since v1.4.0)
errorMessage String
'<p class="lightcase-error"...
Markup of the error message.
labels Object
'errorMessage': 'Source could not be found...',
'sequenceInfo.of': ' of ',
'close': 'Close',
'navigator.prev': 'Prev',
'navigator.next': 'Next',
'navigator.play': 'Play',
'navigator.pause': 'Pause'
	
Texts for several labels. (since v2.3.3)
markup Function
function() {
 $('body').append(...
}
Browse the whole the function in the source file 'lightcase.js'.
onInit Object
{foo: function () {}}
Hook object containing functions which would be executed before initializing the whole process. (since v1.6.0)
onStart Object
{bar: function () {}}
Hook object containing functions which would be executed before generating content.
onFinish Object
{baz: function () {}}
Hook object containing functions which would be executed after generating content.
onClose Object
{qux: function () {}}
Hook object containing functions which would be executed right before aborting. (since v2.1.0)
onCleanup Object
{quux: function () {}}
Hook object containing functions which would be executed after the DOM cleanup. (since v2.1.0)