g

EXT: Perfect Lightbox

Extension Key: perfectlightbox

Copyright 2000-2007, Benjamin Niediek, <typo3@channel-eight.de>

This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3 - a GNU/GPL CMS/Framework available from www.TYPO3.com

Table of Contents

EXT: Perfect Lightbox	1

Introduction	1

What does it do?	1

Screenshots	2

Users manual	6

Localization	6

Integration into tt_news	7

FAQ	7

Lightbox doesn't work at all. What's wrong?	7

How can i use individual captions for every image?	7

Are there any keyboard-shortcuts?	8

Can i change the images used in the lightbox?	8

I'm already using prototype/scriptaculous, mootools or jquery on my site. I don't want them included double!	8

After installing the extension my headerData is gone/corrupted. What's wrong?	8

Mootools, Protaculous or Jquery? Which should i choose?	8

I'm using dam_ttnews. Captionsplit does't work!?	8

I set “forceFirstImageIsPreview” in tt_news. With perfectlightbox installed the ONLY image in the news-record is displayed again!?	8

The javascripts and the css-files arent't included in my header at all!?	8

Adminstration	9

Access	9

Configuration	9

Reference	9

Tutorial	11

Using the lightbox with TS-Objects	11

Adding a watermark to the lightbox-images	11

Optimising loading time	12

Known problems	12

To-Do list	12

Changelog	12

Credits	14

Introduction

What does it do?

This extension provides the popular Lightbox2 written by Lokesh Dhakar (http://www.huddletogether.com) AND the Mootools/Jquery variants Slimbox/Slimbox2 (Christophe Beyls, http://www.digitalia.be) for displaying images in TYPO3. It features the effect for single images as well as imagesets and has an additional presentation mode and a slideshow integrated. NO XCLASS, only typoscript used for the configuration. VALID html-source. FLEXIBLE usage.

Constants can be set to use perfectlightbox globally, to add a link for saving the image and various other options to change the visual appearance of the lightbox.

You can simply switch back and to a mootools/slimbox or prototype/scriptaculous/lightbox version. As simple as setting a constant in your TS!

As of Version 3.0 you can now also have jquery/slimbox2! Have fun!

The three scripts behave identically and are feeded with the same configuration vars. Due to the different implementations of effects with jquery/mootools/protaculous there are small differences in the output and css but few enough to provide a shared css-file for all three of them.

So WHY ANOTHER lightbox extension, you ask? Well, there are already kj_imagelightbox2 and pmkslimbox which in general do the same thing, BUT there's a problem with both of them.
kj_imagelightbox2 does XCLASS inclusion and the generated html-source is not valid.
pmkslimbox is based on mootools (which is a good thing as i know now :-) but does only allow to enable it globally as an exchange for the classic popup-window.

UPDATE: Well, right now I think even mootools can't compare to jquery and if I ever use this extension myself the first thing i'll do is to turn jquery on...

In conclusion, perfectlightbox is a highly flexible and fancy popup-replacement which is easy to use, clean and which generates a 100% valid html-souce...

NOTE: As of Version 3.0.0 I use YUI-compressed scripts to drop the size of the JS-frameworks to a reasonable amount. Only Scriptaculous isn't compressed because, well... it's a pain to do. It's just poorly written in my opinion and I don't have the time to work around that.

Screenshots

1: A normal content-element with a few images ready to be opened in a lightbox/slimbox.

2: The above screenshot shows an image in activated lightbox, imageset enabled, next-link active.

3: This shows an image in activated lightbox-imageset, presentation mode enabled, saving allowed.

4: This one shows the lightbox with some more options (overlay-opacity reduced to 50%, imageset + presentation mode active, saving allowed, slideshow enabled (paused)).

5: Here the additional checkboxes for the lightbox-activation in the backend are shown.

Users manual

Getting started is REALLY easy...
Just import and install the extension via the Extension Manager, enable the static template “Perfect Lightbox” in your main TS-Template and everything is ready.

Now, if you want to enable the lightbox for your images, go to your content-element and tick “Click-enlarge” AND “Lightbox”.
If you want to additionally enable an imageset (given that your content-element has more than one image inside it) also enable “Imageset”.
Finally, if you would like to activate the presentation mode and/or a slideshow, tick them and you're done!

For finetuning of the appearance of the lightbox and max-image-sizes see the configuration-section. There are a bunch of constants you can edit! Furthermore you can specify your own css-file there for additional control over the visuals.

UPDATE: Since Version 2.0.0 you can also enable lightbox/slimbox globally. See configuration section.

NOTE: If any links are set for the images the lightbox is turned off and the standard behaviour (popup for the other images) is reactivated. That's because in my opinion links should take precedence over anything else.
So remember: you want a lightbox – no links should be set!

Localization

The original lightbox.js script was modified to allow localization of the “Image X of X” text shown in imagesets. Translation is done in EXT:perfectlightbox/locallang.xml. For now only english and german translations are provided.
If you would like to share values for other languages in new releases just email me.

UPDATE: Since Version 2.0.0 ALL images are specified in EXT:perfectlightbox/res/css/slightbox.css. For localization of the images do the following:

For a start, in EXT:perfectlightbox:res/img/ there are images named xxxlabel.gif. These are images with english texts printed on them. To use them instead of the “neutral” ones enabled by default make a copy of slightbox.css and put it in your fileadmin-folder. Change the paths to the images in there (Don't forget to define width/height also! See comments). Then go to the constant-editor and set “cssPath” to point to your newly created css-file. After that something similar to this should be shown in your TS-Constants:

plugin.perfectlightbox.cssPath = fileadmin/css/my-english-slightbox.css

Clear the cache and reload, open an image in the lightbox and see for yourself. To use “german” images you have to create them, put them somewhere in your fileadmin-folder, create a new css-file named (for example) “my-german-slightbox.css” and link to your new german images in there. Then change your constant to:

plugin.perfectlightbox.cssPath = fileadmin/css/my-german-slightbox.css

Voila! You got your “german” perfect lightbox. That way you can define own css-files for each language.
For example, if your site is english/german with english as the standard language the following lines are one possible solution for the localization of the slimbox:

###Language Configuration

config.linkVars = L

#English, sys_language.uid = 0

config.sys_language_uid = 0

config.language = en

config.locale_all = en_EN

page.includeCSS.file8 = fileadmin/css/my-english-slightbox.css

#German, sys_language.uid = 1

[globalVar = GP:L=1]

config.sys_language_uid = 1

config.language = de

config.locale_all = de_DE

page.includeCSS.file8 = fileadmin/css/my-german-slightbox.css

[global]

The same way you can set language-specific css/images for every language via global vars. Easy!

Integration into tt_news

Since Version 2.0.1 you can enable perfectlightbox for tt_news. Simply go to the Constant-Editor and set your preferred integration.
At this point all you can do is enable/disable tt_news-integration for each view of tt_news (SINGLE, LIST, LATEST). If more than one image is present in the active view the images are automatically opened as an imageset. Presentation mode and slideshow are disabled for tt_news (as it makes no sense in my opinion...).

FAQ

Lightbox doesn't work at all. What's wrong?

Check if extension is installed, static template is added and make sure javascript is enabled in your browser.
Go to your content-element and verify that no links are set and at least the following options are activated:

How can i use individual captions for every image?

First of all you have to decide which field to use for the caption. The choices are: titleText, altText or imagecaption (the default is imagecaption, see the Configuration section). Each of this fields is splitted by linebreak so if you want individual captions do sth. like this:

Are there any keyboard-shortcuts?

Yes, the original lightbox script featured the keys “p” and “n” (or the arrow-keys) for previous/next image and “c”, “x” or “Escape” to close the lightbox.
I added the “s” to toggle slideshow on/off.

Can i change the images used in the lightbox?

Yes, of course! Easily done via css. See the users manual (localization).

I'm already using prototype/scriptaculous, mootools or jquery on my site. I don't want them included double!

Go to the constant editor an set “Use included Javascript Librarys?” to 0.

After installing the extension my headerData is gone/corrupted. What's wrong?

Perfect Lightbox2 uses “page.headerData.1337” for including its files/vars. If you are already using this for your own configuration, you need to change your values. Or, if you're feeling adventurous, edit/overwrite “setup.txt” in EXT:static/.

Mootools, Protaculous or Jquery? Which should i choose?

If no special need is given to choose one particular option i would go for jquery. It's better code and i *believe* that the transitions are a bit smoother...
Well, as you can switch between the variants in a blink try them all and then you'll know...

I'm using dam_ttnews. Captionsplit does't work!?

UPDATE: The author of dam_ttnews did update his extension! It should all work properly now.
That's because dam_ttnews also uses user_imageMarkerFunc to extend the functionality of image-processing in tt_news. If dam_ttnews is loaded, perfectlightbox is configured to NOT include its userFunc for caption-splitting. I did write the author of dam_ttnews to add the necessary lines to his code to make it work together with perfectlightbox.

NOTE: If anybody could verirfy this for Version 3.0 i'd be grateful!

I set “forceFirstImageIsPreview” in tt_news. With perfectlightbox installed the ONLY image in the news-record is displayed again!?

Fixed since Since Version 2.2.4!

The javascripts and the css-files arent't included in my header at all!?

Very likely you're using another PAGE-object for your site. So page.headerData.1337 isn't referenced.
Just copy page.headerData.1337 to your PAGE-objects headerData. If you want to use the new option “bodyScripts” you have to adapt your settings accordingly.

EXAMPLE:

seite = PAGE

seite.headerData.1337 < page.headerData.1337
### For bodyScripts

#seite.1337 < page.1337

Adminstration

The extension brings all JS-Librarys needed for the lightbox to work. The included libraries are Prototype 1.6.1/Scriptaculous 1.8.3 (only effects.js&builder.js loaded), Mootools1.2.4 and Jquery 1.4.2.
They are included via the static template and are using “page.headerData.1337” to be rendered.

If you are having trouble with the newly introduced yui-compressed javascripts you can easily switch back to the uncompressed ones.

Change constants to:

plugin.perfectlightbox.prototypePath = EXT:perfectlightbox/res/js/prototype.1.6.1.js

plugin.perfectlightbox.lightboxPath = EXT:perfectlightbox/res/js/lightbox.2.0.4.js

plugin.perfectlightbox.mootoolsPath = EXT:perfectlightbox/res/js/mootools.core.1.2.4.js

plugin.perfectlightbox.slimboxPath = EXT:perfectlightbox/res/js/slimbox.1.7.1.js

plugin.perfectlightbox.jqueryPath = EXT:perfectlightbox/res/js/jquery.1.4.2.js

plugin.perfectlightbox.slimbox2Path = EXT:perfectlightbox/res/js/slimbox.2.0.4.js

Of course you can use your own versions of the libraries (if you need the “more” mootools1.2.4 for example). This is again done by editing the constants and specifying your files there.

For the modified link-configuration there have been overridden some settings of “tt_content.image.20.1”. If you already messed around with this object you may have to look at “setup.txt” in EXT:perfectlightbox:static/ for the changes made.

As of version 1.2.0 there is a small userfunc for additional link-processing included. This function adds the “rel”-attribute to the links to activate the lightbox and it shouldn't interfere with anything else. Just an info.

Access

The four new fields for the image-configuration are exclude-fields. So, to enable them for backend-usergroups you have to select them under “Allowed excludefields:“ in the usergroup-sheet.

Configuration

There are a bunch of options that can be configured via the constant-editor.
Localization is possible by editing “locallang.xml” in the extension folder.

NOTE: If you are using your own versions of any of the provided JS-frameworks make sure they are compatible with the respective lightbox-scripts. The included libraries are Prototype 1.6.1/Scriptaculous 1.8.3 (only effects.js&builder.js loaded), Mootools1.2.4 and Jquery 1.4.2.
Although the original lightbox/slimbox scripts were heavily modified to allow the added options and localization they do not introduce any more dependencies to prototype/scriptaculous/mootools/jquery-functions. If you need to put lightbox/slimbox.js in your fileadmin-folder make sure to make exact copies from EXT:perfectlightbox:res/js/.

Reference

plugin.perfectlightbox properties: TS Constants

Constant:	Data Type:	Description:	Default:
libraryToUse	string	This should be set to either "mootools","protaculous" or “jquery”. In case of “mootools” the slimbox-script + its necessary libraries are included , in case of “protaculous” the lightbox-script + its necessary libraries are included. For “jquery” it's slimbox2 and the Jquery-Library.	protaculous
includeJSLibrarys	boolean	Use included Javascript Librarys? You can set this to off when you are already using prototype and scriptaculous globally.	1
bodyScripts	boolean	Put JS in <body>?: You can set this to put all the needed scripts&css in the document's body (experimental).	0
enableGlobally	boolean	You can set this to on when you want to use the lightbox/slimbox as a general exchange for the standard popup-script. This way you get a lightbox for every image marked with "Click-enlarge". If more than one image is existent it's automatically an imageset. Of course you don't lose the other options (if set), they are still taken into account!	1
ignoreUids	booelan	You can set this to on when you want to ALWAYS display ALL images on a page in an imageset. (For all images with exactly the same options enabled!)	0
ttnews.enableSingle	boolean	If set lightbox will also work for the single-view of tt_news.	1
ttnews.enableList	boolean	If set lightbox will also work for the list-view of tt_news.	0
ttnews.enableLatest	boolean	If set lightbox will also work for the latest-view of tt_news.	0
cssPath	file	CSS file for the Lightbox/Slimbox. See EXT:perfectlightbox/res/css/slightbox.css for an example.	EXT:perfectlightbox/res/css/slightbox.css
prototypePath	file	Path to Prototype: You can change this if you need to modify prototype.	EXT:perfectlightbox/res/js/prototype-packed.js
scriptaculousPath	file	Path to Scriptaculous: You can change this if you need to modify scriptaculous.	EXT:perfectlightbox/res/js/scriptaculousEffects-packed.js
lightboxPath	file	Path to the Lightbox Script: WARNING: Refer to the original file at EXT:perfectlightbox/res/js/lightbox.js for the changes made in there (added localisation, presentation mode, slideshow, etc...)	EXT:perfectlightbox/res/js/lightbox-packed.js
mootoolsPath	file	Path to MooTools: You can change this if you need to modify mootools.	EXT:perfectlightbox/res/js/mootools1.11-packed.js
slimboxPath	file	Path to the Slimbox Script: WARNING: Refer to the original file at EXT:perfectlightbox/res/js/slimbox.js for the changes made in there (added localisation, presentation mode, slideshow, etc...)	EXT:perfectlightbox/res/js/slimbox-packed.js
jqueryPath	file	Path to JQuery: You can change this if you need to modify jquery.	EXT:perfectlightbox/res/js/jquery.1.4.2.min.js
slimbox2Path	file	Path to the Slimbox2 Script: WARNING: Refer to the original file at EXT:perfectlightbox/res/js/slimbox.2.0.4.js for the changes made in there (added localisation, presentation mode, slideshow, etc...)	EXT:perfectlightbox/res/js/slimbox.2.0.4.yui.js
lightBoxMaxW	int+	Defines the maxwidth of the image shown in the Lightbox.	900
lightBoxMaxH	int+	Defines the maxheight of the image shown in the Lightbox.	600
captionField	string	Which tt_content field to use as caption inside the Lightbox. Choices are titleText, altText or imagecaption.	imagecaption
overlayOpacity	string	This controls the transparency of the shadow overlay.	0.8
loopImages		Loop images?: Choose true if you want an image carousel.	true
resizeSpeed	int+	This controls the speed of the image resizing animations (in milliseconds).	400
lbBorderSize	int+	Whitespace around image in the Lightbox. If you adjust the padding in the CSS, you will need to update this variable. This is only relevant for protaculous/lightbox, for mootools/slimbox it's ignored.	10
allowSave	string	This toggles whether users are allowed to save the displayed image or not.	false
slideshowAutoplay	string	This toggles whether slideshows start automatically or only after user request.	true
slideshowAutoclose	string	This toggles whether the lightbox is closed after a slideshow reaches the last image in the set. If set to false the slideshow is just stopped and the lightbox remains active.	true
slideshowInterval	int+	The amount of time in milliseconds before a new image is loaded during a slideshow.	5000

[tsref:(cObject).plugin.perfectlightbox]

Tutorial

As this extension is not that hard to handle i believe looking at the users manual should be sufficient enough.

Using the lightbox with TS-Objects

If you want to use the lightbox with other TS-Objects you have to add a rel-attribute to the links (rel=”lightbox” for single lightbox, rel=”lightbox[myImageSet]” for imagesets). You can add the strings “present” and/or “slideshow” INSIDE the [ ] to additionally activate presentation mode and/or a slideshow.
The following lines will point you in the right direction:

page.20 = TEXT

page.20.value = Open an image in a lightbox

page.20.typolink {

title = This is my caption

parameter.cObject = IMG_RESOURCE

parameter.cObject.file = fileadmin/image01.jpg

parameter.cObject.file.maxW = 600

parameter.cObject.file.maxH = 600

ATagParams = rel="lightbox[mySet]"

}

page.30 < page.20

page.30.value = Open another one

page.30.typolink.title = The caption of the second image

page.30.typolink.parameter.cObject.file = fileadmin/image02.jpg

This will generate two simple textlinks which open the images in a imageset.

Adding a watermark to the lightbox-images

Recently i received a request if it's possible to add a watermark to the images in the lightbox... well it is!
Simply add the following lines in your TS-Setup an tweak the watermark as you like:

tt_content.image.20.1 {

imageLinkWrap {

typolink {

parameter.override.cObject = IMG_RESOURCE

parameter.override.cObject.file = GIFBUILDER

parameter.override.cObject.file.XY = [10.w],[10.h]

parameter.override.cObject.file.10 = IMAGE

parameter.override.cObject.file.10.file.import.data = TSFE:lastImageInfo|origFile

parameter.override.cObject.file.10.file.maxW = {$plugin.perfectlightbox.lightBoxMaxW}

parameter.override.cObject.file.10.file.maxH = {$plugin.perfectlightbox.lightBoxMaxH}

parameter.override.cObject.file.20 = TEXT

parameter.override.cObject.file.20 {

text.data = date:Y

text.noTrimWrap = |© | Watermark |

align = right

offset = -5,[10.h]-15

fontFile = fileadmin/templates/fonts/arial.ttf

fontSize = 36

fontColor= #555555

niceText = 1

shadow {

color = #ffffff

offset = 1,1

blur = 40

opacity = 50

}

}

}

}

}

Optimising loading time

Generally speaking it's a goog idea to minimize http-requests from clients. If speed matters for your site consider to put the lightbox-CSS in your main CSS-file (as all other "special" CSS).
Regarding the javascripts, they should be loaded as late as possible. I'm working on that (expect major changes in plb 2.4.0).
For now you can try and put all javascripts from the <head> late in the <body> instead. Advanced Typoscripters should be able to do so easily. Good luck!

UPDATE: New option “bodyScripts” since Version 3.0 to accomplish that. Not yet thoroughly tested so be careful.

Known problems

Don't mix javascript frameworks unless you know what to do! As of Version 3.0 you can choose between three popular frameworks in recent versions so hopefully your favorite one is in the package...

Very likely there are problems with TYPO3 < 4.0 but as i haven't got any installations left to test this it's just a guess.

I REALLY would appreciate your comments, feedback and/or bugnotices at typo3@channel-eight.de

To-Do list

Feel free to make suggestions!

Changelog

Perfectlightbox 3.1.0

Fixed TCA-settings for TYPO3 4.5

perfectlightbox 3.0.4

Changed CSS for a more convenient handling of the presentation mode

Modified Lightbox/Slimbox-Scripts slightly (Cosmetic changes)

perfectlightbox 3.0.3

Added keycode to toggle slideshow on/off (again)

perfectlightbox 3.0.1

Compressed versions of Prototype 1.6.1(YUI), MooTools 1.2.4(YUI) and Jquery 1.4.2(MIN) added

YUI-Compressed versions of Lightbox 2.0.4, Slimbox 1.7.1 and Slimbox 2.0.4 added

Updated Typoscript

Updated documentation

perfectlightbox 3.0.0

BIG UPDATE!

Javascripts rewritten from scratch. Based on the most recent scripts of Lightbox&Slimbox (Slimbox 2.0.4, Slimbox 1.7.1, Lightbox 2.04) and the corresponding frameworks (Jquery 1.4.2, Mootools 1.2.4, Prototype 1.6.1/Scriptaculous 1.8.3).

Optimized Typoscripts and CSS

Removed the option "animate" for Lightbox. You can set resizeSpeed to 0 for a similar effect.

Added an option to put the JS/CSS in the <body> for speed optimization (experimental).

Updated documentation

perfectlightbox 2.2.4

Perfect Lightbox should now FLAWLESSY support tt_news! (Thanks to Claus Helfenschneider for giving me the idea)

Added dutch translation (Again, thanks to Claus)

Updated documentation

perfectlightbox 2.2.3

Fixed small problems with tt_news-integration (with firstImageIsPreview and/or forceFirstImageIsPreview set). No confusion with the imagecaptions anymore! (Thanks to Steffen Thierock for this hint)

Added the option to completely ignore the uid of the content-element. If this is set, perfectlightbox will display ALL images on a page in an imageset! (For all images with exactly the same options enabled)

perfectlightbox 2.2.2

Added french translation (Thanks to Ismaël Bidau)

Added t3mootools.txt to allow T3Mootools to analyze for dependencies

Small change in ext_tables.php

perfectlightbox 2.2.1

Added danish translation (Thanks to Søren Thing Andersen)

Captionsplit now works with dam_ttnews (Thanks to Erich Bircher for the necessary changes in his extension)

Updated documentation

perfectlightbox 2.2.0

Added a more convenient call to initialise the lightbox for the protaculous version (it's now called on loading of the DOM, not on loading of the whole page). Thanks to Alexander McWilliam for giving me the hint.

Updated documentation

perfectlightbox 2.1.0

Support for tt_news added

Updated documentation

perfectlightbox 2.0.1

Updated documentation

perfectlightbox 2.0.0

Major changes in the structure of the extension

Included mootools/slimbox alternative!

Shared css for both variants

All images externalized in css

Option added to enable lightbox/slimbox globally

Small changes in userfunc

perfectlightbox 1.3.1

Modification in lightbox.js (resizeDuration is now properly updated)

perfectlightbox 1.3.0

Fixed a bug in lightbox.js

Introduced compressed scripts (lightbox.js is now only 9kb)

perfectlightbox 1.2.3

Updated documentation

Small modification in userfunc

Fixed little bug in lightbox.css

perfectlightbox 1.2.2

Updated documentation

Additional testing

First upload to TER

perfectlightbox 1.2.1

Updated manual

perfectlightbox 1.2.0

Added slideshow options

Inluded userfunc for additional link-processing

Transferred more lightbox-vars to constants

Updated manual

Thoroughly tested

perfectlightbox 1.2.0

Added slideshow options

Inluded userfunc for additional link-processing

Transferred more lightbox-vars to constants

Updated manual

perfectlightbox 1.1.0

Added option to save images, controlled globally via constant.

Updated manual

perfectlightbox 1.0.0

Initial release.

Credits

Lokesh Dhakar for sharing his lightbox script.

Christophe Beyls for sharing his slimbox script.

Markus F. Hay for the lightbox-extension “LyteBox” which inspired me to include a slideshow.

Michael Feinbier for general help.

Julian Kleinhans for kj_imagelightbox2 as an inspiration.

Peter Klein for pmkslimbox and some neat typoscripts in there.

Søren Thing Andersen for danish translation.

Steffen Thierock and Martin Holtz for constructive feedback.

Claus Helfenschneider for dutch translation and extensive feedback.

EXT: Perfect Lightbox - 15

EXT: Perfect Lightbox

--- ---

2007-09-13T14:14:03