EXT: Perfect Lightbox¶

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.

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 everylanguage 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…).

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

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.

Reference¶

plugin.perfectlightbox properties: TS Constants

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.

((generated))¶