Fix for issue #1751666 by Karsa: Decrease the number of field formatters
[project/lightbox2.git] / README.txt
CommitLineData
6062372f
SP
1CONTENTS OF THIS FILE
2----------------------
b9e92e06 3
6062372f
SP
4 * Introduction
5 * Installation
6 * Adding Lightbox Functionality to your Images
7 - No Grouping
8 - With Grouping
5a1b1abf 9 - Slideshow
79573211 10 - Video
a7638576 11 - HTML Content Support
047b3b4e 12 - Inline Content Support
6062372f 13 - Turning the Image Caption into a Link
5297c314 14 * Keyboard Shortcuts
5827d5fc 15 * Translation of Configured Strings
6062372f 16 * Known Issues
5297c314 17 - Keyboard Shortcuts in Opera
40acd20e 18
40acd20e 19
6062372f
SP
20INTRODUCTION
21------------
22Maintainers:
6062372f 23 Stella Power (http://drupal.org/user/66894)
5827d5fc
SP
24 Daniel F. Kudwien (http://drupal.org/user/54136)
25 Mark Ashmead (http://drupal.org/user/52392)
b76b10e0 26 Fernando Correa da Conceição (http://drupal.org/user/889254)
40acd20e 27
4b31a439
SP
28Documentation: http://drupal.org/node/144469
29
6062372f 30Licensed under the GNU/GPL License
120536e1
SP
31Based on Lightbox v2.03.3 by Lokesh Dhakar
32<http://www.huddletogether.com/projects/lightbox2/>
ac8f2bef 33
120536e1
SP
34Originally written to make use of the Prototype framework, and Script.acalo.us,
35now altered to use jQuery.
40acd20e 36
120536e1
SP
37Permission has been granted to Mark Ashmead & other Drupal Lightbox2 module
38maintainers to distribute the original lightbox.js via Drupal.org under this
39license scheme. This file has been subsequently modified to make use of jQuery
40instead of prototype / script.acalo.us.
ac8f2bef 41
6062372f 42This module enables the use of lightbox2 which places images above your
120536e1
SP
43current page, not within. This frees you from the constraints of the layout,
44particularly column widths.
ac8f2bef 45
6062372f
SP
46This module will include the lightbox CSS and JS files in your Drupal
47Installation without the need to edit the theme. The module comes with a
5a1b1abf
SP
48Lightbox2 Lite option which does not use the jQuery libraries; it is therefore
49less likely to conflict with anything else.
ac8f2bef 50
40acd20e 51
6062372f 52INSTALLATION
40acd20e 53------------
6062372f 541. Copy lightbox2 folder to modules directory.
84ef6475
FC
552. At admin/modules enable the lightbox2 module.
563. Enable permissions at admin/people/permissions.
574. Configure the module at admin/config/user-interface/lightbox2.
6062372f
SP
585. Modify your image links to open in a lightbox where necessary, see "Adding
59 Lightbox Functionality to your Images' section below.
98eff5c2
SP
606. If you need to play flv files, then you may need to install a FLV player.
61 There are a number of freely available ones on the Internet, including
62 http://www.jeroenwijering.com/
6062372f
SP
63
64
65ADDING LIGHTBOX FUNCTIONALITY TO YOUR IMAGES
66--------------------------------------------
67No Grouping
68===========
5a1b1abf 69Add rel="lightbox" attribute to any link tag to activate the lightbox.
6062372f 70For example:
047b3b4e
SP
71<a href="images/image-1.jpg" rel="lightbox">image #1</a>
72<a href="images/image-1.jpg" rel="lightbox[][my caption]">image #1</a>
40acd20e 73
047b3b4e
SP
74Optional: To show a caption either use the title attribute or put in the second
75set of [] of the rel attribute.
40acd20e 76
6062372f
SP
77With Grouping
78==============
5a1b1abf
SP
79If you have a set of related images that you would like to group, follow step
80one but additionally include a group name between square brackets in the rel
81attribute. For example:
40acd20e
M
82
83<a href="images/image-1.jpg" rel="lightbox[roadtrip]">image #1</a>
047b3b4e
SP
84<a href="images/image-2.jpg" rel="lightbox[roadtrip][caption 2]">image #2</a>
85<a href="images/image-3.jpg" rel="lightbox[roadtrip][caption 3]">image #3</a>
40acd20e 86
5a1b1abf
SP
87No limits to the number of image sets per page or how many images are allowed
88in each set. Go nuts!
40acd20e 89
6062372f 90If you have a set of images that you would like to group together in a
c2092936 91lightbox, but only wish for one of these images to be visible on your page, you
72e1648d 92can assign the "lightbox_hide_image" class to hide the additional images. For
c2092936
SP
93example:
94
95<a href="images/image-1.jpg" rel="lightbox[roadtrip]">image #1</a>
72e1648d
SP
96<a href="images/image-2.jpg" rel="lightbox[roadtrip]" class="lightbox_hide_image">image #2</a>
97<a href="images/image-3.jpg" rel="lightbox[roadtrip]" class="lightbox_hide_image">image #3</a>
c2092936 98
5a1b1abf
SP
99Slideshow
100=========
101This is very similar to the grouping functionality described above. The only
102difference is that "rel" attribute should be set to "lightshow" instead of
103"lightbox". Using the same example as above, we could launch the images in a
104slideshow by doing:
105
106<a href="images/image-1.jpg" rel="lightshow[roadtrip]">image #1</a>
047b3b4e
SP
107<a href="images/image-2.jpg" rel="lightshow[roadtrip][caption 2]">image #2</a>
108<a href="images/image-3.jpg" rel="lightshow[roadtrip][caption 3]">image #3</a>
5a1b1abf 109
79573211
SP
110Video
111=====
112It's possible to show video content in the lightbox. In this case the "rel"
5827d5fc
SP
113attribute should be set to "lightvideo". It's possible to group videos and
114to control the size of the lightbox by setting the 'width' and 'height
115properties. The properties can be configured like
116"lightvideo[group|width:300px; height: 200px;]" and
117"lightvideo[|width:300px; height: 200px;][my caption]". The properties should
047b3b4e 118all be of the format "property: value;" - note the closing semi-colon. If no
79573211
SP
119properties are set, then the default width and height of 400px will be used.
120See below for more detailed examples.
121
122Basic example:
79573211
SP
123<a href="http://video.google.com/videoplay?docid=1811233136844420765"
124rel="lightvideo">Google video example - default size</a>
79573211 125
047b3b4e
SP
126Basic example with caption:
127<a href="http://video.google.com/videoplay?docid=1811233136844420765"
128rel="lightvideo[][my caption]">Google video example - default size</a>
129
5827d5fc
SP
130Grouped example:
131<a href="http://video.google.com/videoplay?docid=29023498723974239479"
132rel="lightvideo[group][caption 1]">Grouped example 1</a>
133<a href="http://video.google.com/videoplay?docid=1811233136844420765"
134rel="lightvideo[group][caption 2]">Grouped example 2</a>
135
79573211 136Controlling lightbox size example:
79573211 137<a href="http://video.google.com/videoplay?docid=1811233136844420765"
5827d5fc
SP
138rel="lightvideo[|width:400px; height:300px;][my caption]">Google video example -
139custom size</a>
79573211
SP
140
141Supported Video Formats
142asx, wmv, mov and swf videos should all be supported. A number of video
143providers are also supported, for example YouTube and Google Video. For full
144details on how to integrate these with lightbox, please see the online
145documentation.
146
a7638576
SP
147HTML Content Support
148====================
149It's possible to show webpage content in the lightbox, using iframes. In this
150case the "rel" attribute should be set to "lightframe". Again it's possible to
047b3b4e 151group the content, (e.g. "lightframe[search]") but in addition to that, it's
a7638576
SP
152possible to control some of the iframe properties. It's possible to set the
153'width', 'height' and 'scrolling' properties of the iframe. The properties are
154separated from the group name by a '|', for example
047b3b4e
SP
155"lightframe[search|width:100px;]" and
156"lightframe[search|width:100px;][my caption]". If no grouping is being used,
157then the '|' is still used and the format would be "lightframe[|width:100px;]".
158The properties should all be of the format "property: value;" - note the closing
a7638576
SP
159semi-colon. If no iframe properties are set, then the default width and height
160of 400px will be used. See below for more detailed examples.
161
162Basic example:
163<a href="http://www.google.com" rel="lightframe">Search google</a>
164
047b3b4e
SP
165Basic example with caption:
166<a href="http://www.google.com" rel="lightframe[][my caption]">Search google</a>
167
a7638576
SP
168Grouped example:
169<a href="http://www.google.com" rel="lightframe[search]">Search google</a>
5827d5fc 170<a href="http://www.yahoo.com" rel="lightframe[search][Search Yahoo]">Search yahoo</a>
a7638576
SP
171
172Controlling iframe property example:
173<a href="http://www.google.com" rel="lightframe[|width:400px; height:300px; scrolling: auto;]">Search google</a>
174
175Controlling iframe property when grouped example:
047b3b4e 176<a href="http://www.google.com" rel="lightframe[search|width:400px; height:300px; scrolling: auto;][Search Google]">Search google</a>
5827d5fc 177<a href="http://www.yahoo.com" rel="lightframe[search|width:400px; height:300px;]">Search yahoo</a>
047b3b4e
SP
178<a href="http://www.yahoo.com" rel="lightframe[search|width:400px; height:300px;][Search Yahoo]">Search yahoo</a>
179
180Inline Content Support
181=======================
182It's possible to show HTML snippets in the lightbox, that is on the same domain.
183In this case the "rel" attribute should be set to "lightmodal". Again it's
184possible to group the content, (e.g. "lightmodal[search]") but in addition to
185that, it's possible to control some of the inline / modal properties. It's
186possible to set the 'width', 'height' and 'scrolling' properties of the inline
187content. The properties are separated from the group name by a '|', for example
188"lightmodal[search|width:100px;]" and
189"lightmodal[search|width:100px;][my caption]". If no grouping is being used,
190then the '|' is still used and the format would be "lightmodal[|width:100px;]".
191The properties should all be of the format "property: value;" - note the closing
192semi-colon. If no properties are set, then the default width and height of
193400px will be used. See below for more detailed examples.
194
195Basic example:
196<a href="search.php" rel="lightmodal">Search</a>
197
198Basic example with caption:
199<a href="search.php" rel="lightmodal[][my caption]">Search</a>
200
201Grouped example:
202<a href="search.php" rel="lightmodal[search]">Search</a>
203<a href="search.php?status=1" rel="lightmodal[search][published]">Search published content</a>
204
205Controlling modal property example:
206<a href="search.php" rel="lightmodal[|width:400px; height:300px; scrolling: auto;]">Search</a>
207
208Controlling modal property when grouped example:
209<a href="search.php" rel="lightmodal[search|width:400px; height:300px; scrolling: auto;]">Search</a>
210<a href="search.php?status=1" rel="lightmodal[search|width:400px; height:300px;][Search published]">Search published content</a>
211<a href="search.php?status=0" rel="lightmodal[search|width:400px; height:300px;][Search Unpublished]">Search unpublished content</a>
a7638576
SP
212
213
5827d5fc 214
6062372f
SP
215Turning the Image Caption into a Link
216=====================================
5a1b1abf 217If you wish to turn the caption into a link, format your caption in the
6062372f 218following way:
40acd20e 219
047b3b4e
SP
220<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>
221
222Note, the < and > characters have been changed to their HTML entities, and the "
223have been escaped.
40acd20e
M
224
225
5297c314
SP
226KEYBOARD SHORTCUTS
227------------------
93160a45
SP
228Not all of the default keyboard shortcuts work in the Opera browser, for example
229'z' for toggling the zoom and 'spacebar' for toggling play / pause in
230slideshows. This can be overcome by updating your shortcut settings in the
231Opera preferences editor.
232
233The default keyboard shortcuts are listed below. You can override these on
234admin/settings/lightbox2.
5297c314
SP
235
236Close : x, o, c, ESC
237Previous Image : p, Left Arrow
238Next Image : n, Right Arrow
239Toggle Zoom : z (not available in slideshow)
240Toggle Play / Pause : Spacebar (slideshow only)
241
242
b2b7ae25
SP
243TRANSLATION OF CONFIGURED STRINGS
244----------------------------------
245In order to translate the lightbox2 configuration strings, such as the text for
246the "View Image Details" link and the image count, please install the i18n:
247internationalization module and follow the instructions at
5827d5fc 248http://drupal.org/node/134002.
b2b7ae25
SP
249
250
6062372f 251KNOWN ISSUES
ac8f2bef
M
252------------
253
5297c314
SP
254Keyboard Shortcuts in Opera
255---------------------------
93160a45
SP
256Not all of the default keyboard shortcuts work in the Opera browser, for example
257'z' for toggling the zoom and 'spacebar' for toggling play / pause in
258slideshows. This can be overcome by updating your shortcut settings in the
259Opera preferences editor.