Lightbox2 JS is a simple, unobtrusive script used to overlay images on the current page. It\'s a snap to setup and works on all modern browsers. The module comes with a Lightbox2 Lite option which does not use the JQuery libraries; it is therefore less likely to conflict with anything else.
Places images above your current page, not within. This frees you from the constraints of the layout, particularly column widths. Keeps users on the same page. Clicking to view an image and then having to click the back button to return to your site is bad for continuity (and no fun!).
Features
The version 2 module has several benefits over the plain Lightbox module. Note, not all of these features are available when the "Lightbox2 Lite" option is enabled.
Image Sets: group related images and navigate through them with ease - ideal for your image galleries.
Slideshow Capability: automatically transition between grouped images, includes play/pause and previous and next buttons.
HTML Content Support: ability to show websites or other HTML content in a lightbox.
Video Content Support: ability to show videos in a lightbox.
Visual Effects: fancy pre-loader and transition when you click on the image.
Keyboard Shortcuts: useful keyboard shortcuts for switching between images, toggling play / pause, etc.
Zoom Capability: larger images are reduced in size so they fit snugly inside the browser window. A zoom button can then be clicked on to see it in its original size.
Automatic Image Detection: configurable automatic re-formatting of
image thumbnails, so there is no need to add \'rel="lightbox"\' to each
image link on your site. Image, Inline, Flickr, Image Assist and CCK Imagefield modules are all
supported. It\'s also possible to configure a custom list of image classes
which should trigger the lightbox functionality.
Image Page Link: a link to the image node can be provided within the lightbox itself.
Page Exclusion Capability: exclude certain pages on your site from having the lightbox2 functionality.
Login Support: ability to modify all user/login links so the login form appears in a lightbox.
Skin and Animation Configuration: configure the order and speed of the lightbox animations, along with the lightbox colors, border size and overlay opacity.
Gallery 2 Support: support for Gallery 2 images via the Gallery module (beta).
Usage
Adding a Basic Lightbox
Add rel="lightbox" attribute to any link tag to activate the lightbox. For example:
Optional: To show a caption either use the title attribute or put in the second set of [] of the rel attribute.
Grouping Images
If you have a set of related images that you would like to group, follow
step one but additionally include a group name between square brackets in the
rel attribute. For example:
No limits to the number of image sets per page or how many images are allowed
in each set.
If you have a set of images that you would like to group together in a lightbox, but only wish for one of these images to be visible on your page, you can assign the "lightbox_hide_image" class to hide the additional images. For example:
This is very similar to the grouping functionality described above. The only difference is that "rel" attribute should be set to "lightshow" instead of "lightbox". Using the same example as above, we could launch the images in a slideshow by doing:
It\'s possible to show video content in the lightbox. In this case the "rel" attribute should be set to lightvideo. It\'s possible to group videos and to control the size of the lightbox by setting the \'width\' and \'height\' properties. The properties can be configured like lightvideo[group|width:300px; height: 200px;] and lightvideo[|width:300px; height: 200px;][my caption]. The properties should all be of the format "property: value;" - note the closing semi-colon. If no properties are set, then the default width and height of 400px will be used. See below for more detailed examples.
Basic example:
<a href="http://video.google.com/videoplay?docid=1811233136844420765" rel="lightvideo">Google video example - default size</a>
Basic example with caption:
<a href="http://video.google.com/videoplay?docid=1811233136844420765" rel="lightvideo[][my caption]">Google video example - default size</a>
Grouped example:
<a href="http://video.google.com/videoplay?docid=29023498723974239479" rel="lightvideo[group][my caption]">Grouped example 1</a>
<a href="http://video.google.com/videoplay?docid=1811233136844420765" rel="lightvideo[group][my caption]">Grouped example 2</a>
Controlling lightbox size example:
<a href="http://video.google.com/videoplay?docid=1811233136844420765" rel="lightvideo[|width:400px; height:300px;][my caption]">Google video example - custom size</a>
Supported Video Formats
asx, wmv, mov and swf videos should all be supported. A number of video providers are also supported, for example YouTube and Google Video. For full details on how to integrate these with lightbox, please see the online documentation.
HTML Content
It\'s possible to show webpage content in the lightbox, using iframes. In this case the "rel" attribute should be set to lightframe. Again it\'s possible to group the items, (e.g. lightframe[search]) but in addition to that, it\'s possible to control some of the iframe properties. It\'s possible to set the \'width\', \'height\' and \'scrolling\' properties of the iframe. The properties are separated from the group name by a |, for example lightframe[search|width:100px;] and lightframe[search|width:120px][my caption]. If no grouping is being used, then the | is still used and the format would be lightframe[|width:100px;]. The properties should all be of the format "property: value;" - note the closing semi-colon. If no iframe properties are set, then the default width and height of 400px will be used. See below for more detailed examples.
It\'s possible to show HTML snippets in the lightbox, that is on the same domain. In this case the "rel" attribute should be set to lightmodal. Again it\'s possible to group the content, (e.g. lightmodal[search]) but in addition to that, it\'s possible to control some of the inline / modal properties. It\'s possible to set the \'width\', \'height\' and \'scrolling\' properties of the inline content. The properties are separated from the group name by a |, for example lightmodal[search|width:100px;] and lightmodal[search|width:100px;][my caption]. If no grouping is being used, then the | is still used and the format would be lightmodal[|width:100px;]. The properties should all be of the format "property: value;" - note the closing semi-colon. If no properties are set, then the default width and height of 400px will be used. See below for more detailed examples.
The default keyboard shortcuts are listed below. You can override these on the admin page.
Close Lightbox
x
o
c
ESC
Previous Image
p
Left Arrow
Next Image
n
Right Arrow
Toggle Zoom
z (not available in slideshow)
Toggle Play / Pause
Spacebar (slideshow only)
Not all of the keyboard shortcuts work in the Opera browser, for example "z" for toggling the zoom and "spacebar" for toggling play / pause in slideshows. This can be overcome by updating your shortcut settings in the Opera preferences editor.
');
break;
}
}
/**
* Implementation of hook_perm().
*/
function lightbox2_perm() {
return array('administer lightbox2', 'download original image');
}
/**
* Implementation of hook_menu().
*/
function lightbox2_menu() {
$items = array();
$items['admin/settings/lightbox2'] = array(
'title' => 'Lightbox2',
'description' => 'Allows the user to configure the lightbox2 settings',
'file' => 'lightbox2.admin.inc',
'page callback' => 'lightbox2_settings_page',
'access callback' => 'user_access',
'access arguments' => array('administer lightbox2'),
);
$items['admin/settings/lightbox2/general'] = array(
'title' => 'General',
'description' => 'Allows the user to configure the lightbox2 settings',
'file' => 'lightbox2.admin.inc',
'page callback' => 'drupal_get_form',
'page arguments' => array('lightbox2_general_settings_form'),
'access callback' => 'user_access',
'access arguments' => array('administer lightbox2'),
'type' => MENU_DEFAULT_LOCAL_TASK,
'weight' => 0,
);
$items['admin/settings/lightbox2/slideshow'] = array(
'title' => 'Slideshow',
'description' => 'Allows the user to configure the lightbox2 slideshow functionality',
'file' => 'lightbox2.admin.inc',
'page callback' => 'drupal_get_form',
'page arguments' => array('lightbox2_slideshow_settings_form'),
'access callback' => 'user_access',
'access arguments' => array('administer lightbox2'),
'type' => MENU_LOCAL_TASK,
'weight' => 1,
);
$items['admin/settings/lightbox2/html_content'] = array(
'title' => 'HTML Content',
'file' => 'lightbox2.admin.inc',
'page callback' => 'drupal_get_form',
'page arguments' => array('lightbox2_iframe_settings_form'),
'access callback' => 'user_access',
'access arguments' => array('administer lightbox2'),
'description' => 'Allows the user to configure the lightbox2 HTML content functionality.',
'type' => MENU_LOCAL_TASK,
'weight' => 2,
);
$items['admin/settings/lightbox2/automatic'] = array(
'title' => 'Automatic image handling',
'description' => 'Allows the user to configure the lightbox2 automatic image handling settings',
'file' => 'lightbox2.admin.inc',
'page callback' => 'drupal_get_form',
'page arguments' => array('lightbox2_auto_image_handling_settings_form'),
'access callback' => 'user_access',
'access arguments' => array('administer lightbox2'),
'type' => MENU_LOCAL_TASK,
'weight' => 3,
);
if (module_exists('emfield') && module_exists('emvideo')) {
$items['video-cck/lightbox2'] = array(
'page callback' => 'lightbox2_emvideo',
'access callback' => 'user_access',
'access arguments' => array('access content'),
'type' => MENU_CALLBACK,
);
}
if (module_exists('acidfree') && module_exists('video')) {
$items['node/%nid/lightframevideo'] = array(
'page callback' => 'lightbox2_acidfree_video',
'page arguments' => array(1),
'access callback' => 'user_access',
'access arguments' => array('play video'),
'type' => MENU_CALLBACK,
);
}
$items['user/login/lightbox2'] = array(
'title' => 'Login',
'page callback' => 'lightbox2_login',
'access callback' => 'user_is_anonymous',
'type' => MENU_CALLBACK,
);
$items['contact/lightbox2'] = array(
'title' => 'Contact',
'page callback' => 'lightbox2_contact',
'access arguments' => array('access site-wide contact form'),
'type' => MENU_CALLBACK,
);
return $items;
}
/**
* Implementation of hook_init().
*/
function lightbox2_init() {
if (lightbox2_exclude_these_paths() != 1) {
lightbox2_add_files();
}
}
/**
* Implementation of hook_filter_tips().
*/
function lightbox2_filter_tips($delta, $format, $long = FALSE) {
if ($delta == 0) {
if (!$long) {
return t('Image links with \'rel="lightbox"\' in the <a> tag will appear in a Lightbox when clicked on.');
}
else {
$output = '
'. t('To add a lightbox to your images, add rel="lightbox" attribute to any link tag to activate the lightbox. For example:') .'
'. t('To show a caption either use the title attribute or put in the second set of square brackets of the rel attribute.') .'
';
$output .= '
'. t('If you have a set of related images that you would like to group, then you will need to include a group name between square brackets in the rel attribute. For example:') .'
';
return $output;
}
}
elseif ($delta == 1) {
return t('Image links from G2 are formatted for use with Lightbox2');
}
elseif ($delta == 2) {
if (!$long) {
return t('Image links with \'rel="lightshow"\' in the <a> tag will appear in a Lightbox slideshow when clicked on.');
}
else {
$output = '
'. t('To add a lightbox slideshow to your images, add rel="lightshow[slideshowname][slide caption]" attribute to any link tag to activate the slideshow. For example:') .'
'. t('The title attribute in the link tag is optional. The addition of this attribute enables the display of a caption with the image displayed in the lightbox.') .'
';
$output .= '
'. t('There are no limits to the number of slideshow image sets per page or how many images are allowed in each slideshow.') .'
';
$output .= '
'. t('If you wish to turn the caption into a link, format your caption in the following way:') .'
';
return $output;
}
}
elseif ($delta == 3) {
if (!$long) {
return t('Links to HTML content with \'rel="lightframe"\' in the <a> tag will appear in a Lightbox when clicked on.');
}
else {
$output = '
'. t('It\'s possible to show webpage content in the lightbox, using iframes. In this case the "rel" attribute should be set to "lightframe". Again it\'s possible to group the content, (e.g. lightframe[search][caption]) but in addition to that, it\'s possible to control some of the iframe properties. It\'s possible to set the "width", "height" and "scrolling" properties of the iframe. The properties are separated from the group name by a |, for example lightframe[search|width:100px;][caption]. If no grouping is being used, then the | is still used and the format would be lightframe[|width:100px;]. The properties should all be of the format "property: value;" - note the closing semi-colon. If no iframe properties are set, then the default width and height of 400px will be used. See below for more detailed examples.') .'
';
return $output;
}
}
elseif ($delta == 4) {
if (!$long) {
return t('Links to video content with \'rel="lightvideo"\' in the <a> tag will appear in a Lightbox when clicked on.');
}
else {
$output = '
'. t('It\'s possible to show video content in the lightbox. In this case the "rel" attribute should be set to lightvideo. It\'s possible to group videos and to control the size of the lightbox by setting the "width" and "height" properties. The properties can be configured like lightvideo[group|width:300px; height: 200px;][caption]. The properties should all be of the format "property: value;" - note the closing semi-colon. If no properties are set, then the default width and height of 400px will be used. See below for more detailed examples.') .'
';
$output .= '
'. t('Basic example:') .' ';
$output .= t('<a href="http://video.google.com/videoplay?docid=1811233136844420765" rel="lightvideo">Google video example - default size</a>') .'
';
$output .= '
'. t('Controlling lightbox size example:') .' ';
$output .= t('<a href="http://video.google.com/videoplay?docid=1811233136844420765" rel="lightvideo[group|width:400px; height:300px;][caption]">Google video example - custom size</a>') .'
';
$output .= '
'. t('Supported video formats include asx, wmv, mov and swf. A number of online video providers are also supported, including YouTube and Google Video. For a full list of the current supported video providers please see the documentation on drupal.org.') .'
';
return $output;
}
}
elseif ($delta == 5) {
if (!$long) {
return t('Links to inline or modal content with \'rel="lightmodal"\' in the <a> tag will appear in a Lightbox when clicked on.');
}
else {
$output = '
'. t('It\'s possible to show HTML snippets in the lightbox, that is on the same domain. In this case the "rel" attribute should be set to "lightmodal". Again it\'s possible to group the content, (e.g. lightmodal[group][caption]) but in addition to that, it\'s possible to control some of the modal properties. It\'s possible to set the "width", "height" and "scrolling" properties of the modal. The properties are separated from the group name by a |, for example lightmodal[group|width:100px;][caption]. If no grouping is being used, then the | is still used and the format would be lightmodal[|width:100px;]. The properties should all be of the format "property: value;" - note the closing semi-colon. If no modal properties are set, then the default width and height of 400px will be used. See below for more detailed examples.') .'