• Intro
    • Demonstrations
    • Installation
    • How to use
    • Documentation
    • Troubleshooting
    • License
    • Download
    • Contact
    Latest version:
    2.8.0 28-10-2011

    New Lightview - The jQuery Lightbox

  • Lightview was built to change the way you overlay content on a website.

    • Clean: Designed to compliment your content.
    • Fast: Smart image preloading.
    • Easy: Customizable without having to know CSS.
    • Rounded: Adjustable rounded corners, no PNG images required.
    • Smart: Content resizes to always fit on your screen.
    • Slideshow: One button slideshow.
    • Works on all modern browsers.
    6+ 2+ 2+ 9.5+

    Demonstrations

    Note: A new jQuery based version of this script is available: Lightview 3

    Gallery

    Mixed sets

    • Image
    • Quicktime
    • Flash

    Other media

    • Quicktime
    • Ajax & Forms
    • Anti-aliasing
    • Iframe
    • Inline content
    • Inline & API
    Gallery photos © Philippe Vieux-Jeanton | Mixed set & Anti-aliasing photo © Ian Grainger

    This demonstration shows how the Lightview API can be used to create a custom view.

    You might want your users to agree to some terms before proceeding, blocking access to the page below having only one clickable button. The 'take me back' button on this view is the only way to close it. Clicking on the overlay or pressing Esc to close is also disabled.

    This is just a basic example, by using the Lightview API you can customize everything to your liking creating more advanced views containing login forms, disclaimers, feedback forms etc.

    Installation

    Setup your doctype

    First make sure you have a valid doctype set as the very first line on the page. I recommend using the HTML5 doctype:

    <!DOCTYPE html>

    Upload the required files

    Upload all files from the lightview package to your server: Javascript, CSS and the images.

    Lightview requires Prototype 1.7.0 and Scriptaculous 1.8.3+. In the example below I'm including both using the Google AJAX Libraries API. As an alternative you could download and host Prototype and Scriptaculous yourself, but by including both using Google's AJAX Libraries API you don't have to worry about caching and bandwidth cost.

    Add Lightview to your page

    Add Lightview below these libraries, the correct order of the javascript files is as in the example below.

    <script type='text/javascript' src='https://ajax.googleapis.com/ajax/libs/prototype/1.7.0/prototype.js'></script>
    <script type='text/javascript' src='https://ajax.googleapis.com/ajax/libs/scriptaculous/1/scriptaculous.js'></script>
    <script type='text/javascript' src='/js/lightview.js'></script>
    

    Add lightview.css to your header.

    <link rel="stylesheet" type="text/css" href="css/lightview.css" />

    Note: The downloads have an example folder demonstrating the installation.

    How to use

    A simple view

    A view is created using a links class attribute. Single images should have the rel attribute set to 'image', but you can also use no rel attribute at all.

    <a href='image.jpg' class='lightview'>My image</a>

    Image galleries

    An image gallery can be created using rel='gallery[galleryname]'

    <a href='image1.jpg' class='lightview' rel='gallery[mygallery]'>Image 1</a>
    <a href='image2.jpg' class='lightview' rel='gallery[mygallery]'>Image 2</a>

    Mixed sets of content

    A set can contain any type of media, it's syntax is similar to that of a gallery except set is used instead of gallery. The slideshow button will be enabled when a set consists of images only.

    <a href='image.jpg' class='lightview' rel='set[myset]'>My image</a>
    <a href='movie.mov' class='lightview' rel='set[myset]'>A Quicktime movie</a>
    <a href='flash.swf' class='lightview' rel='set[myset]'>Flash movie</a>

    Setting title and description

    You can set the title and caption using the title attribute. Use the characters :: if you want both title and caption. This character combination can be changed using the titleSplit option.

    <a href='leopard.jpg' title='A title' class='lightview'>Leopard</a>
    <a href='gazelle.jpg' title='This image has a title :: And a caption' class='lightview'>Gazelle</a>
    <a href='cheetah.jpg' title=":: I don't have a title, just a caption" class='lightview'>Cheetah</a>
    <a href='rhino.jpg' title="Left in split characters will get stripped :: " class='lightview'>Rhino</a>
    

    Customization

    Media other then images supports a thirth parameter with options. There are a lot of options you can use, check the documentation for the available options on each type of media.

    <a href='http://google.com' rel='iframe' title='Google :: :: fullscreen: true' class='lightview'>Google</a>
    <a href='http://yahoo.com' rel='iframe' title='Yahoo :: caption :: width: 800, height: 600' class='lightview'>Yahoo</a>

    Detecting filetype

    Lightview will automatically try to detect what type of content you are viewing based on the extensions set in lightview.js. When Lightview can't detect your filetype you will have to set the rel attribute to match it. If you want to show flash for example and the filetype isn't automatically detected you'll have to set rel='flash', other options are quicktime, inline, ajax and iframe.

    It's also possible to force a filetype on a set using the following syntax rel='set[setname][type]'. It's impossible for Lightview to detect that the videos below are flash videos since there are no file extensions, forcing the filetype solves this problem. See the documentation for more information on filetypes and forcing them onto a view.

    <a href='http://www.youtube.com/v/CQzUsTFqtW0' class='lightview' rel='set[myset][flash]'>Youtube</a>
    <a href='http://vimeo.com/moogaloop.swf?clip_id=2874824&server=vimeo.com&autoplay=1' class='lightview' rel='set[myset][flash]'>Vimeo</a>

    Quicktime, Flash, Inline, Ajax & Iframe views

    Lightview will show inline content if you set the href attribute to '#id'. The autosize option can be used on ajax and inline views, this will automatically resize them to the content recieved. topclose can be used on ajax, iframe and inline content to have the close button that slides out instead of the static one.

    <a href='#hiddenform' class='lightview' title=" :: :: topclose: true, autosize: true">Show Form</a>
    <a href='/ajax/' class='lightview' rel='ajax' title=" :: :: ajax: { onComplete: callback }">Ajax Form</a>
    <a href='#anotherElement' class='lightview' title=" :: :: menubar: false">No menubar</a>

    Using the API

    It's possible to show a view using javascript:

    document.observe('lightview:loaded', function() {
      Lightview.show({
        href: '/ajax/',
        rel: 'ajax',
        title: 'Login',
        caption: 'Enter your username and password to login',
        options: {
          autosize: true,
          topclose: true,
          ajax: {
            method: 'get',
            evalScripts: true,
            onComplete: function(){ $('name').focus(); }
          }
        }
      });
    });
    
    // Here we observe an element and call Lightview.show, the lightview:loaded event
    // is used here to make sure Lightview.show is available.
    document.observe("lightview:loaded", function() {
      $("elementId").observe('click', function() {
        Lightview.show({ href: 'anotherElementId', rel: 'inline' });
      });
    });
    
    // If you have firebug installed you can run this from your console, have fun.
    Lightview.show({ href: 'http://www.google.com', rel: 'iframe', options: { width: 800, height: 500 }});

    The type of view will be auto-detected using the url you provide. If for some reason you want to force a specific type of view you can overwrite the auto-detection using the rel attribute.

    Lightview.show({
      href: 'http://www.youtube.com/v/0alNtVUy7YY&autoplay=1',
      rel: 'flash'
    });

    Documentation

    Configuration

    You can set the following options in lightview.js.

    • backgroundColor
      The background color of the view.
    • border
      Pixel size of the border
    • buttons.opacity
      Changes the opacity of the buttons inside the view for different states (normal, hover, disabled).
    • buttons[button].display
      Toggle the display of the side, inner previous/next and the slideshow buttons.
    • cyclic
      When true, galleries will be cyclic, allowing you to keep pressing next/back.
    • controller[options]
      Configure the Controller used with sets.
    • defaultOptions
      Configure the default options for each media type.
    • images
      The directory of the images, relative to the javascript file ('../images/lightview/') or an absolute url ('http://yoururl.com/images/lightview/').
    • imgNumberTemplate
      A string to go below title/caption, using #{position} and #{total}.
    • keyboard
      Enable or disable the keyboard buttons.
    • menubarPadding
      The padding in pixels between the menubar and the content.
    • overlay
      Toggle the overlay or set it's opacity. On Mac Safari and Firefox overlay.png is used, you will need to modify it for those browsers.
    • overlay.close
      Toggle if clicking the overlay should close Lightview.
    • preloadHover
      Preloads images on mouseover when true.
    • radius
      The pixel radius of the corners.
    • removeTitles
      Set to false if you want to preserve title attributes.
    • resizeDuration
      The duration of the resizing.
    • slideshowDelay
      The time each image is visible during a slideshow.
    • startDimensions
      The dimensions Lightview starts at when opened.
    • titleSplit
      The characters that split title caption and options, '::' by default. This means that if you only want to give options you use: title=' :: :: fullscreen: true '
    • transition
      Scriptaculous transition during resizing.
    • viewport
      Resizes images to stay within the viewport when they open, if true.
    • zIndex
      zIndex of the lightview, the overlay has this value - 1.

    Forcing media type using the rel attribute

    You can overwrite the auto detection of the media type. This is useful when Lightview is not detecting your media. For example, when including Youtube or Google video through flash you need to use rel='flash', on a set you will need to use rel='set[setname][flash]'. The following types can be set on the rel attribute.

    • ajax
      Get the content using an ajax call.
    • flash
      Treat the content as flash.
    • image
      Treat the content as an image.
    • iframe
      Load the url in an iframe.
    • inline
      Show the content as inline. A shortcut to this method is using '#id' as the href.
    • quicktime
      Show the content using Quicktime.

    View options

    These options can be used as thirth parameters in the title attribute, seperated by commas. title='title :: caption :: autosize: true, topclose: true'

    • ajax
      Additional options you would normal put as options on an Ajax.Request.
    • autosize
      For inline and ajax views, resizes the view to the element recieves. Make sure it has dimensions otherwise this will give unexpected results.
    • closeButton
      'small', 'large' or false to change/hide the close button inside the view.
    • width
      integer, sets the width of the view in pixels
    • height
      integer, sets the height of the view in pixels
    • flashvars
      flashvars to put on the swf object
    • fullscreen
      true or false, shows the view in fullscreen, usable on iframes.
    • innerPreviousNext
      true of false, toggle the inner previous and next button for this image.
    • keyboard
      true or false, toggle the keyboard buttons for this view
    • loop
      true of false, for quicktime movies
    • menubar
      'top', 'bottom' or false, shows the menubar above or below the content or hides it when false.
    • overflow
      Set the overflow CSS property to create or hide scrollbars for inline and ajax views. Possible values are 'auto' or 'hidden'.
    • overlayClose
      when false, disables the overlay close on click for this view.
    • slideshow
      true or false, toggle the slideshow button for this image.
    • topclose
      true or false, show the sliding close button instead of the static one.
    • wmode
      flash uses wmode: "transparent" by default, overwrite using wmode: "window" or "opaque".

    Functions

    The following function are available to you.

    • Lightview.updateViews()
      Force a reset of all Lightview elements on the page. Most of the time you won't need to do this since Lightview will pick up on newly inserted elements automatically. After updating existing elements it might be required to call this function.
    • Lightview.show(param)
      Accepts 'id', element and object as parameter and shows the view associated with it.
    • Lightview.show('#id')
      A shortcut for inline content, this shows the element with the id using an inline view.
    • Lightview.hide()
      Hides lightview.

    Custom Events

    Lightview comes with a set of useful custom events you can observe to attach your own callback functions.

    • lightview:opened

      You can observe the document or individual links for this event. A function can be called when the event fires. Within the function, event.target will refer to the element that was opened, a few examples:

      document.observe('lightview:opened', function(event) {
        alert('You opened ' + event.target.href);
      });
      
      $('myId').observe('lightview:opened', function(event) {
        new Effect.Pulsate($('lightview').down('.title'));
      });
      
    • lightview:hidden
      Fires when you hide lightview, can be used like the :opened event.
    • lightview:loaded

      Fires on the document when Lightview is loaded and ready for a Lightview.show call.

      document.observe('lightview:loaded', function() {
        Lightview.show('myId');
      });

    Keyboard shortcuts

    • Arrow left / right
      Previous and next image.
    • P / S
      Play and stop the slideshow.
    • Home / End
      First and last image of the set.
    • Esc
      Hide lightview.

    Troubleshooting

    I use jQuery but Lightview doesn't work with it out of the box, it tells me to enable jQuery noConflict, how should I do that?

    Since Lightview uses Prototype you'll have to enable jQuery.noConflict to avoid conflicts between jQuery and Prototype. You can find documentation about it on the jQuery website. Here's an example of a correct use of jQuery.noConflict so it works with third party code like Lightview:

    <!-- Include jQuery -->
    <script type='text/javascript' src='/js/jquery.min.js'></script>
    
    <!-- Enable noConflict -->
    <script type='text/javascript'>jQuery.noConflict();</script>
    
    <!-- Other scripts can now safely use their own $ function -->
    <script type='text/javascript' src='https://ajax.googleapis.com/ajax/libs/prototype/1/prototype.js'></script>
    <script type='text/javascript' src='https://ajax.googleapis.com/ajax/libs/scriptaculous/1/scriptaculous.js'></script>
    <script type='text/javascript' src='/js/lightview.js'></script>
    

    I've enabled jQuery.noConflict but now some of my jQuery code doesn't work, how do I fix that?

    Since the point of jQuery.noConflict is to remove the $ function out of the global scope and give it back to its original owner you should always use a closure that turns the jQuery object into the $ function. This makes it possible to use the jQuery object as the $ function within your own scope, making your code work with third party code. Here's an example:

    (function($) {
      /* The jQuery $ function can be used here without conflict.
       * It's recommended to always use a closure like this so your jQuery code will work 
       * with third party code without having to modify anything later on.
       * 
       * jQuery plugins that are properly coded already use a closure like this. 
       */
       
       $(document).ready(function() { alert('this is jQuery'); });
    })(jQuery);
    
    $(document).observe('dom:loaded', function() { alert('this is Prototype'); });
    

    Lightview doesn't open in the center of the window.

    Give your page a doctype, I recommend using the HTML5 doctype.

    The overlay doesn't cover the entire screen.

    See the solution above.

    When I click the lightview link, a new window opens instead of lightview.

    Lightview will look for links with the class lightview once the DOM is loaded. Even though this only takes a little while for most pages it could be that you've clicked the link before the documented was loaded.

    The effects don't work no matter what I try.

    You must have effects.js from the Scriptaculous package. Get the full scriptaculous download at script.aculo.us

    Lightview doesn't look the same when I use it on my website.

    This could be because lightview.css is not included or the images are not uploaded. It also happens when your own CSS is conflicting with lightview.css. Make sure you target elements in your CSS without setting things global, code like li { display: inline; } for example is bad practice when you use third party code like Lightview. When your CSS is properly coded and all the required files are uploaded and included you should have no problem implementing Lightview.

    It's still not working.

    Make sure you have the right versions of Prototype and Scriptaculous and validate your website using validator.w3.org before posting for support on the Lightview Forum. I also recommend getting Firefox with the Firebug addon, many problems posted on the forum are quickly solved with the debugging it provides.

    License

    Permission to use Lightview on your domain is required and can be obtained by paying a small fee. For non-commercial domains this will allow you to use Lightview under a Creative Commons by-nc-nd License. When you get permission for a commercial domain you may use Lightview under the terms of the Creative Commons by-nd License.

    • Non-Commercial

      Single domain

      A small fee is required for non-commercial use.
    • Non-Commercial

      Unlimited

      Get permission to use Lightview on all the non-commercial websites you develop in the future, at no further cost.
    • Commercial

      Single domain

      This will give you permission to use Lightview on a single commercial domain.

      When is my website considered commercial?

      • Websites an income is achieved with.
      • Websites that intend to achieve an income.
      • Websites that sell products or services.
      • Websites with banner or advertising revenues.
      • Portfolios.
      • Business websites.
      • Shop websites.
      • Club websites (membership corporation).
      • Erotic projects or erotic sites.
      • Radio stations.
      • Auction websites.
      • Bet, gamble and lot websites.
      • Paid mail services.
      • Websites which arouse public interest such as,
      • Churchly, honorary or other organizations,
      • Associations and parties.
      • Websites with sales and/or profit-making orientation.
      • Websites that are based on sponsors or endorsement.
      • Websites that run on a commercial basis.
    • Commercial

      Unlimited

      With unlimited permission you are allowed to use Lightview on any commercial website you develop in the future, at no further cost.

    Download

    Note: A new jQuery based version of this script is available: Lightview 3

    • Lightview 2.8.0

    Changelog

    The latest changelog entries. Subscribe to the feed if you want to be notified of updates.

    ...

    Contact

    Use the Lightview Forum for support related questions, feedback, feature requests and bug reports. If you are posting for support please read through the Troubleshooting section first.

    For anything non-support related you can contact me at nick@nickstakenburg.com or @staaky. Please use the Forum to get support, I don't have the time to answer every support related email individualy.

    lightview, overlay, images, prototype, photos, effects, scriptaculous, javascript, slideshow, gallery, video, quicktime, flash, inline, lightbox, thickbox, lytebox, lightwindow, light, box, lightbox, slimbox, lytebox, lytebox, litebox window, web2.0, Creative Commons by-nc-nd License, © 2008-2012 Nick Stakenburg

    lightbox alternative, prototype, thickbox, slimbox, overlay, photos, web2.0, quicktime, image lightbox, scriptaculous, litebox, modal, nick, stakenburg, include the lightbox, slideshow, reference lightbox, gallery, add rel lightbox, lightbox.js, lightwindow, script lightbox, css lightbox, language javascript lightbox, scriptaculous lightbox, lightbox is, set lightbox, lytebox, gallery lightbox, effects, javascript lightbox.