README.txt 10.8 KB
Newer Older
1 2
CONTENTS OF THIS FILE
----------------------
3

4 5 6 7 8
  * Introduction
  * Installation
  * Adding Lightbox Functionality to your Images
    - No Grouping
    - With Grouping
9
    - Slideshow
stella's avatar
stella committed
10
    - Video
11
    - HTML Content Support
12
    - Inline Content Support
13
    - Turning the Image Caption into a Link
14
  * Keyboard Shortcuts
stella's avatar
stella committed
15
  * Translation of Configured Strings
16
  * Known Issues
17
    - Keyboard Shortcuts in Opera
18 19


20 21 22 23
INTRODUCTION
------------
Maintainers:
  Stella Power (http://drupal.org/user/66894)
stella's avatar
stella committed
24 25
  Daniel F. Kudwien (http://drupal.org/user/54136)
  Mark Ashmead (http://drupal.org/user/52392)
26
  Fernando Correa da Conceição (http://drupal.org/user/889254)
27

28 29
Documentation: http://drupal.org/node/144469

30
Licensed under the GNU/GPL License
31 32
Based on Lightbox v2.03.3 by Lokesh Dhakar
<http://www.huddletogether.com/projects/lightbox2/>
33

34 35
Originally written to make use of the Prototype framework, and Script.acalo.us,
now altered to use jQuery.
36

37 38 39 40
Permission has been granted to Mark Ashmead & other Drupal Lightbox2 module
maintainers to distribute the original lightbox.js via Drupal.org under this
license scheme.  This file has been subsequently modified to make use of jQuery
instead of prototype / script.acalo.us.
41

42
This module enables the use of lightbox2 which places images above your
43 44
current page, not within. This frees you from the constraints of the layout,
particularly column widths.
45

46 47
This module will include the lightbox CSS and JS files in your Drupal
Installation without the need to edit the theme. The module comes with a
48 49
Lightbox2 Lite option which does not use the jQuery libraries; it is therefore
less likely to conflict with anything else.
50

51

52
INSTALLATION
53
------------
54
1. Copy lightbox2 folder to modules directory.
55 56 57
2. At admin/modules enable the lightbox2 module.
3. Enable permissions at admin/people/permissions.
4. Configure the module at admin/config/user-interface/lightbox2.
58 59
5. Modify your image links to open in a lightbox where necessary, see "Adding
   Lightbox Functionality to your Images' section below.
60 61 62
6. If you need to play flv files, then you may need to install a FLV player.
   There are a number of freely available ones on the Internet, including
   http://www.jeroenwijering.com/
63 64 65 66 67 68


ADDING LIGHTBOX FUNCTIONALITY TO YOUR IMAGES
--------------------------------------------
No Grouping
===========
69
Add rel="lightbox" attribute to any link tag to activate the lightbox.
70
For example:
71 72
<a href="images/image-1.jpg" rel="lightbox">image #1</a>
<a href="images/image-1.jpg" rel="lightbox[][my caption]">image #1</a>
73

74 75
Optional: To show a caption either use the title attribute or put in the second
set of [] of the rel attribute.
76

77 78
With Grouping
==============
79 80 81
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:
82 83

<a href="images/image-1.jpg" rel="lightbox[roadtrip]">image #1</a>
84 85
<a href="images/image-2.jpg" rel="lightbox[roadtrip][caption 2]">image #2</a>
<a href="images/image-3.jpg" rel="lightbox[roadtrip][caption 3]">image #3</a>
86

87 88
No limits to the number of image sets per page or how many images are allowed
in each set. Go nuts!
89

90
If you have a set of images that you would like to group together in a
91
lightbox, but only wish for one of these images to be visible on your page, you
stella's avatar
stella committed
92
can assign the "lightbox_hide_image" class to hide the additional images.  For
93 94 95
example:

<a href="images/image-1.jpg" rel="lightbox[roadtrip]">image #1</a>
stella's avatar
stella committed
96 97
<a href="images/image-2.jpg" rel="lightbox[roadtrip]" class="lightbox_hide_image">image #2</a>
<a href="images/image-3.jpg" rel="lightbox[roadtrip]" class="lightbox_hide_image">image #3</a>
98

99 100 101 102 103 104 105 106
Slideshow
=========
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:

<a href="images/image-1.jpg" rel="lightshow[roadtrip]">image #1</a>
107 108
<a href="images/image-2.jpg" rel="lightshow[roadtrip][caption 2]">image #2</a>
<a href="images/image-3.jpg" rel="lightshow[roadtrip][caption 3]">image #3</a>
109

stella's avatar
stella committed
110 111 112
Video
=====
It's possible to show video content in the lightbox.  In this case the "rel"
stella's avatar
stella committed
113 114 115 116 117
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
118
all be of the format "property: value;" - note the closing semi-colon.  If no
stella's avatar
stella committed
119 120 121 122 123 124 125
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>

126 127 128 129
Basic example with caption:
<a href="http://video.google.com/videoplay?docid=1811233136844420765"
rel="lightvideo[][my caption]">Google video example - default size</a>

stella's avatar
stella committed
130 131 132 133 134 135
Grouped example:
<a href="http://video.google.com/videoplay?docid=29023498723974239479"
rel="lightvideo[group][caption 1]">Grouped example 1</a>
<a href="http://video.google.com/videoplay?docid=1811233136844420765"
rel="lightvideo[group][caption 2]">Grouped example 2</a>

stella's avatar
stella committed
136 137
Controlling lightbox size example:
<a href="http://video.google.com/videoplay?docid=1811233136844420765"
stella's avatar
stella committed
138 139
rel="lightvideo[|width:400px; height:300px;][my caption]">Google video example -
custom size</a>
stella's avatar
stella committed
140 141 142 143 144 145 146

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.

147 148 149 150
HTML Content Support
====================
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
151
group the content, (e.g. "lightframe[search]") but in addition to that, it's
152 153 154
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
155 156 157 158
"lightframe[search|width:100px;]" and
"lightframe[search|width:100px;][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
159 160 161 162 163 164
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.

Basic example:
<a href="http://www.google.com" rel="lightframe">Search google</a>

165 166 167
Basic example with caption:
<a href="http://www.google.com" rel="lightframe[][my caption]">Search google</a>

168 169
Grouped example:
<a href="http://www.google.com" rel="lightframe[search]">Search google</a>
stella's avatar
stella committed
170
<a href="http://www.yahoo.com" rel="lightframe[search][Search Yahoo]">Search yahoo</a>
171 172 173 174 175

Controlling iframe property example:
<a href="http://www.google.com" rel="lightframe[|width:400px; height:300px; scrolling: auto;]">Search google</a>

Controlling iframe property when grouped example:
176
<a href="http://www.google.com" rel="lightframe[search|width:400px; height:300px; scrolling: auto;][Search Google]">Search google</a>
stella's avatar
stella committed
177
<a href="http://www.yahoo.com" rel="lightframe[search|width:400px; height:300px;]">Search yahoo</a>
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211
<a href="http://www.yahoo.com" rel="lightframe[search|width:400px; height:300px;][Search Yahoo]">Search yahoo</a>

Inline Content Support
=======================
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.

Basic example:
<a href="search.php" rel="lightmodal">Search</a>

Basic example with caption:
<a href="search.php" rel="lightmodal[][my caption]">Search</a>

Grouped example:
<a href="search.php" rel="lightmodal[search]">Search</a>
<a href="search.php?status=1" rel="lightmodal[search][published]">Search published content</a>

Controlling modal property example:
<a href="search.php" rel="lightmodal[|width:400px; height:300px; scrolling: auto;]">Search</a>

Controlling modal property when grouped example:
<a href="search.php" rel="lightmodal[search|width:400px; height:300px; scrolling: auto;]">Search</a>
<a href="search.php?status=1" rel="lightmodal[search|width:400px; height:300px;][Search published]">Search published content</a>
<a href="search.php?status=0" rel="lightmodal[search|width:400px; height:300px;][Search Unpublished]">Search unpublished content</a>
212 213


stella's avatar
stella committed
214

215 216
Turning the Image Caption into a Link
=====================================
217
If you wish to turn the caption into a link, format your caption in the
218
following way:
219

220 221 222 223
<a href="images/image-1.jpg" rel="lightbox[][&lt;a href=\"http://www.yourlink.com\"&gt;Clicky Visit Link&lt;/a&gt;'>image #1</a>

Note, the < and > characters have been changed to their HTML entities, and the "
have been escaped.
224 225


226 227
KEYBOARD SHORTCUTS
------------------
stella's avatar
stella committed
228 229 230 231 232 233 234
Not all of the default 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.

The default keyboard shortcuts are listed below.  You can override these on
admin/settings/lightbox2.
235 236 237 238 239 240 241 242

Close : 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)


243 244 245 246 247
TRANSLATION OF CONFIGURED STRINGS
----------------------------------
In order to translate the lightbox2 configuration strings, such as the text for
the "View Image Details" link and the image count, please install the i18n:
internationalization module and follow the instructions at 
stella's avatar
stella committed
248
http://drupal.org/node/134002.
249 250


251
KNOWN ISSUES
252 253
------------

254 255
Keyboard Shortcuts in Opera
---------------------------
stella's avatar
stella committed
256 257 258 259
Not all of the default 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.