API

Usage

The easiest way to use Lightview is by adding the class lightview to a link.

<a href="image.jpg" class="lightview">Show image</a>

The alternative is using the Javascript API. See the API documentation for more on it, this section will cover just the HTML approach.

Lightview.show('image.jpg');

A title and caption can be added by using data-attributes:

<a href="image.jpg" 
   class="lightview" 
   data-lightview-title="The title goes above the caption" 
   data-lightview-caption="Use a caption to give your visitors some more information">Title & caption</a>

More advanced overlay windows can be created by putting Options and/or Callbacks on the data-lightview-options attribute:

<a href="image.jpg" class="lightview" data-lightview-options="skin: 'mac'">Link with options</a>

Groups

Create groups by giving links a data-lightview-group attribute. Each group should have a unique name. Groups can contain multiple types of content, images can be mixed with video for example:

<a href="image1.jpg" 
   class="lightview" 
   data-lightview-group="mixed">Image 1</a>
<a href="image2.jpg" 
   class="lightview" 
   data-lightview-group="mixed">Image 2</a>
<a href="video.mov" 
   class="lightview" 
   data-lightview-group="mixed" 
   data-lightview-options="width: 640, height: 272">Video</a>

Whenever links in a group share options repeating those can be avoided by using the data-lightview-group-options attribute. Options set on this attribute will be used by the entire group:

<a href="image1.jpg" 
   class="lightview" 
   data-lightview-group="shared_options" 
   data-lightview-group-options="skin: 'mac'">This group</a>
<a href="image2.jpg" 
   class="lightview" 
   data-lightview-group="shared_options">has shared</a>
<a href="image3.jpg" 
   class="lightview" 
   data-lightview-group="shared_options">options</a>

Controls

There are a number of control types that can be selected by setting the controls option. The default is relative.

controls: 'relative'

Relative controls surround the window, this also gives a slider with item numbers. The amount of items can be set within the slider option:

controls: { type: 'relative', slider: { items: 5 } }

The slider can also be disabled:

controls: { slider: false }

The close button can be set to relative or top. Use false to disable it.

controls: { close: 'top' }

By setting controls to top they will appear fixed at the top of the screen.

controls: { type: 'top' }

Controls set to thumbnails will give thumbnail navigation below the content.

controls: { type: 'thumbnails' }

Thumbnails

The control type thumbnails will automatically create a thumbnail for images based on the original. It is best set as an option for the entire group:

data-lightview-group-options="controls: 'thumbnails'"

Thumbnails are automatically generated for images, here's an example:

<a href="image1.jpg" 
   class="lightview" 
   data-lightview-group="thumbnail-demo" 
   data-lightview-group-options="controls: 'thumbnails'">Thumbnail 1</a>
<a href="image2.jpg" 
   class="lightview" 
   data-lightview-group="thumbnail-demo">Thumbnail 2</a>
<a href="image3.jpg" 
   class="lightview" 
   data-lightview-group="thumbnail-demo">Thumbnail 3</a>

The default thumbnail is created using the original image. A different source for this thumbnail can be set using the thumbnail option. This is useful in cases where a thumbnail can't be created from the given url, on Quicktime movies for example:

<a href="movie1.mov" 
   class="lightview" 
   data-lightview-group="thumbnail-example" 
   data-lightview-group-options="controls: 'thumbnails'" 
   data-lightview-options="
     thumbnail: '/thumbnails/movie1.jpg', 
     width: 640, 
     height: 272
   ">Thumbnail Quicktime 1</a>
<a href="movie2.mov" 
   class="lightview" 
   data-lightview-group="thumbnail-example" 
   data-lightview-options="
     thumbnail: '/thumbnails/movie2.jpg', 
     width: 640, 
     height: 272
   ">Thumbnail Quicktime 2</a>

Thumbnails added to Quicktime video's automatically get a video icon. By setting the thumbnail option as an Object an icon option can be set to toggle this.

thumbnail: { image: 'thumbnail.jpg', icon: 'video' }

A common usecase for this is video embedded through an iframe. Youtube and Vimeo for example both recommend iframe embeds to get their HTML5 players instead of the Flash, but because these embeds require an iframe the icon will have to be set manually:

<a href='http://player.vimeo.com/video/32071937?autoplay=1'
   class="lightview" 
   data-lightview-type="iframe"  
   data-lightview-group="thumbnail-icon-example" 
   data-lightview-group-options="controls: 'thumbnails'" 
   data-lightview-options="
     width: 600, 
     height: 333, 
     viewport: 'scale', 
     thumbnail: { image: '/thumbnails/vimeo.jpg', icon: 'video' }
   ">Thumbnail Vimeo</a>
<a href='http://www.youtube.com/embed/nTFEUsudhfs?autoplay=1&autohide=1&border=0&egm=0&showinfo=0&showsearch=0' 
   class="lightview" 
   data-lightview-type="iframe"  
   data-lightview-group="thumbnail-icon-example" 
   data-lightview-options="
     width: 638,
     height: 360,
     viewport: 'scale',
     thumbnail: { image: '/thumbnails/youtube.jpg', icon: 'video' }
   ">Thumbnail Youtube</a>

Media types

Lightview attempts to automatically detect the media type using the urls file extension. The type can also be set to one of the following values using the data-lightview-type attribute: image, flash, quicktime, iframe, inline or ajax.

Image

Most of the time setting the type will not be required, it will be needed in cases where Lightview cannot detect it based on the url:

<a href="/images/?id=123" class="lightview" data-lightview-type="image">Image</a>

Flash

Swf files can be embedded by using flash as the type. Some extra options are available for this type. The params option can be used to set parameters normally set on an object/embed element. flashvars can be used to set flashvars as key/value pairs. The following example embeds a video through flash using JWPlayer, it uses flashvars to configure the player:

<a href="/jwplayer/player.swf" 
   class="lightview" 
   data-lightview-type="flash" 
   data-lightview-options="
     width: 720, 
     height: 406, 
     keyboard: { esc: false }, 
     flashvars: { 
       file: 'video.mp4', 
       autostart: true 
     }
   ">Flash</a>

Quicktime

The quicktime type also gives the params option, it can be used to set things like controller and autoplay:

<a href="movie.mov" 
   class="lightview" 
   data-lightview-type="quicktime" 
   data-lightview-options="
     width: 640, 
     height: 272, 
     params: { 
       controller: true, 
       autoplay: true 
     }
   ">Quicktime</a>

Iframe

This type is useful for loading the url in an iframe instead of navigating to it. When using an iframe the dimensions can be set as a percentage of the available space in the viewport:

<a href="http://docs.jquery.com" 
   class="lightview" 
   data-lightview-type="iframe" 
   data-lightview-options="width: 1000, height: '100%'">Iframe</a>

Inline

Elements inline on the page can be pulled into Lightview by making sure the href attribute starts with a hash (#), followed by the id of the element to pull in:

<a href="#inline_example" class="lightview">Inline</a>
<div id="inline_example" style="display:none">This element is pulled into Lightview.</div>
Inline

Ajax

By setting the type to ajax an Ajax request will be made to the url to fetch content. The ajax option can be used to set the request type and data to send along with the request.

<a href="helloworld.php" 
   class="lightview" 
   data-lightview-type="ajax" 
   data-lightview-options="
     ajax: { 
       type: 'post',
       data: { string: 'Hello world' } 
     }
   ">Ajax</a>

The above example links to a php file that outputs a simple snippet, here's its content:

<?php // content of helloworld.php ?>
<p>A string was send to the server containing the following:</p>
<pre><code><?php echo $_POST['string']; ?></code></pre>

The afterUpdate callback can be used to work with the content inserted into the window:

<a href="helloworld.php" 
   class="lightview" 
   data-lightview-type="ajax" 
   data-lightview-options="
     ajax: {
       type: 'post',
       data: { string: 'Hello world' } 
     },
     afterUpdate: function(element) {
       $(element).find('pre').css({ color: 'red' });
     }
   ">Ajax with callback</a>

Note: Ajax should only be used to load snippets since the fetched markup is inserted into the current page. Use the iframe type to load entire pages.

Embedding

The following examples are best practices for embedding third party content.

Youtube

Youtube provides HTML5 support by embedding videos through iframes. It's recommended to use this so that video will work on mobile devices without Flash support (iPhone/iPad). Here's an example of a Youtube <iframe> embed based on the Youtube Player API.

<a href='http://www.youtube.com/embed/nTFEUsudhfs?autoplay=1&autohide=1&border=0&egm=0&showinfo=0' 
   class="lightview" 
   data-lightview-type="iframe" 
   data-lightview-options="
     width: 638,
     height: 360,
     viewport: 'scale'
   ">Youtube</a>

The viewport option is set to scale so that the iframe will scale instead of crop to stay within the viewport. Without this the dimensions will be incorrect once the video is resized.

Vimeo

Vimeo also supports HTML5 through iframes. Here's an example of it, see the Vimeo documentation for all the available options.

<a href='http://player.vimeo.com/video/32071937?autoplay=1' 
   class="lightview" 
   data-lightview-type="iframe" 
   data-lightview-options="
     width: 600, 
     height: 333, 
     viewport: 'scale'
   ">Vimeo (HTML5)</a>

Javascript API

For more advanced use see the documentation on the Javascript API. All of the demonstrations on this page can also be created using the Javascript API, you might even prefer it over the HTML approach.

Lightview.show({
  url: '/movies/movie.mov',
  type: 'quicktime',
  title: 'Javascript API',
  caption: 'This video was shown using the Javascript API',
  options: {
    width: 640,
    height: 272,
    params: {
      controller: false
    }
  }
});
Sign in