EXT: DAM Lightbox¶

What does it do?¶

The DAM Lightbox provides a comfortable, flexible and universally applicable way to work with DAM images and their related metadata in the TYPO3 back- and frontend. The extension has three main features:

It provides you with two generic DAM fields that can be added to any TYPO3 table/record without changing the database: a field for image references and a flexform field for configuration. The fields are configured using the extension's backend module.

You can access any metadata of referenced DAM images for any TYPO3 record just using TypoScript.

All DAM images and their according metadata can be shown in a templateable popup or lightbox. The extension uses d4u_slimbox as an example but it's possible to connect other lightboxes as well.

Working examples of DAM Lightbox for tt_content, tt_news, tt_address and pages are shipped with this extension.

Screenshots¶

Feature list¶

• Generic DAM image & configuration field for any TYPO3 table that is registered in $TCA
• Transfers metadata of DAM images into TSFE with easy TypoScript access
• Full localization support
• Templateable HTML popup / lightbox
• Almost anything configurable with TypoScript
• Flexform configuration for each referenced image; general values can be set from TypoScript
• Individual flexforms can be configured on a per table basis via PageTSConfig
• Can also be used without any lightbox
• Full support for d4u_slimbox (2.2.0+), including printing and saving of click-enlarged images
• Can be used either standalone or together with dam_ttcontent (1.1.0+), dam_ttnews (0.1.9+) and dam_pages (0.1.7+)
• Sample configuration for tt_content, tt_news, tt_address and pages

Requirements¶

• TYPO3 (4.2+)
• dam (1.1.1+)

Optional extensions¶

• dam_ttcontent (1.1.0+)
• dam_ttnews (0.1.9+)
• dam_pages (0.1.7+)
• d4u_slimbox (2.2.0+)

Credits¶

• Thanks to René Fritz who first provided us with the DAM
• Thanks to the DAM development team. You do an excellent job!
• Thanks to Peter Klein for pmkslimbox
• Thanks to Alex Schwethelm and Ralf-Peter Dumont for taking over pmkslimbox as d4u_slimbox
• Further credits go to the DAM mailinglist for feedback and suggestions

This extension is maintained and developed by the team of the Digital Academy Mainz for our D igital Humanities projects. We are glad if you find it useful too.

Please rate¶

No matter if you like or don't like the extension, please rate it in TER. Each good rating motivates us to keep going. Each bad rating motivates us to make the stuff better :)

Basic principles¶

In it's early days, DAM Lightbox started out as an extension for DAM and dam_ttcontent. While the lightbox functionality is still a major feature of this extension, the general focus nowadays is to provide a connector between DAM and TSFE. Please have a look at the following sketch:

All references from a DAM item to a record in the TYPO3 system are kept within a reference table (tx_dam_mm_ref). Extensions like dam_ttcontent provide dedicated database fields for specific TYPO3 tables with which the references between the records and the DAM items are managed. So far so good. But as soon as you work with a TYPO3 table for which there doesn't exist a “dam_xxx” extension, you have to build a clone that provides this functionality. Generally speaking, those dedicated database fields are not really necessary. They just provide a view on the relationship table and don't contain any useful data by themselves.

The approach of DAM Lightbox is different. Here the image references are handled by a “generic” field that is included “on the fly” when a backend form is loaded. This image field can be displayed for any TYPO3 table that is configured in the Table Configuration Array ($TCA). It acts like a normal field, but it's not in the database.

Besides the generic image field the extension provides another “on the fly” field. This second field is a generic flexform field. The idea of the generic flexform field is to provide editors with the possibility to configure the display of the DAM images and their metadata.

Basic functionality¶

Since there are many ways of how you could display your DAM metadata together with your DAM images in the frontend, this extension just implements some basic functionality. The Howto section of this manual provides you with step-by-step guides on how to do more. This is what works out of the box:

Image previews:

In cases where you have more than one image attached to a record you can use this checkbox to just show the first one while the others will be browsable in the popup/lightbox.

Use as caption:

Gives you the possibility to select between media:title, media:caption and media:description for your image captions. The content can be overridden with the standard caption field.

Show copyright:

If this is checked, the value from media:copyright will be prepended to the image caption.

Lightbox - Show as caption:

Lets you decide if you want to show media:title, media:caption or media:description as caption of the lightbox. The standard value set from TS is media:description.

Lightbox - Custom dimensions:

In some situations the dimensions of the lightbox need to be adjusted. Here you can insert custom dimensions for d4u_slimbox using the following notation: imagenumber:pixelwidth,pixelheight;

Installation & Configuration¶

Deinstallation¶

Drop the TypoScript from your template.

Deinstall the extension with EM.

Drop the tx_damlightbox_ds table from the database using the COMPARE function of the install tool.

Upgrading from version 0.0.2¶

In case you already use an older version of DAM Lightbox (very likely 0.0.2), you will have to perform a database update before you can continue to use the extension. First of all, please make a backup of your database! Next, go to the extension manager, select DAM Lightbox and check the UPDATE! function in the upper left dialogue:

A notice appears that tells you some details about the DB update. Press “Do the Update” and continue with step 3 of the Installation & Configuration section.

Upgrading from version 0.1.2 to 0.2.0¶

Up to version 0.1.2 damlightbox could be used together with the extension pmkslimbox. The extension is no longer maintained and due to some security issues it has been removed from TER. But luckily some devs stepped in and there is an alternative: d4u_slimbox, a security patched fork of pmkslimbox with exactly the same functionality. Consequently,from version 0.2.0 of damlightbox, support for pmkslimbox is dropped and d4u_slimbox is supported instead .

What do you have to take care of when upgrading? Not much! If you used pmkslimbox, just install d4u_slimbox and replace the two TypoScript snippets “SlimboxPlus t3m (pmkslimbox)” and “DAM Lightbox: pmkslimbox” with the new snippets “SlimboxPlus t3m (d4u_slimbox)” and “DAM Lightbox: d4u_slimbox”. Everything should be working exactly as before. Note: The TS library “lib.damlightbox.pmkslimbox” is now named “lib.damlightbox.d4u_slimbox”. If you customized the old library you will have to adapt your TS to the new key.

Controlling field access¶

The two generic fields (image & flexform) are defined as exclude fields. Once you have configured them in the DAM Lightbox backend module, they will appear in the exclude list of BE group records for the configured tables. You can exclude/include the generic fields just like you do with dedicated database fields.

Defining custom flexforms¶

You can define custom flexforms for each configured DAM Lightbox table using PageTSConfig. This comes in handy when you need different configuration options on a per table basis. Its also possible to make the field look different for the same table depending on the section of the website. Here is the syntax:

TCEFORM.[table].tx_damlightbox_flex.config.ds.default = FILE:path/to/your/custom_flexform.xml

Please make sure that you always prepend your path with “FILE:”. Your custom flexform needs to be in a correct T3DataStructure format. You can learn more about that in the core documentation. The extension's default flexform (flexform_ds.xml) may also serve as an example.

Fetching metadata: plugin.tx_damlightbox_pi1¶

The plugin part of the extension is responsible for fetching the metadata of any referenced DAM item for the current record. During page rendering it builds a database query for the current record in question and writes its DAM metadata into TSFE. For this to work, the plugin always needs to be executed in the right context. “Context” means that the call to plugin.tx_damlightbox_pi1 should always happen within the setup of the TYPO3 record in question but before the record itself is rendered. In other words, you always need to execute the plugin in the context of the $cObj->data of the record you want to match with DAM images.

The tricky thing is that the locations will always be a bit different – it depends on how the content generation was implemented for a specific extension. Don't worry to much, due to the fact that DAM Lightbox already has an implementation for tt_content, tt_news, tt_address and pages there are good examples for the different possibilities at hand.

To illustrate this point, please have a look at the following example.

Localization / translation handling¶

DAM Lightbox supports TYPO3's localization features. As soon as you have correctly localized your DAM records, the plugin automatically fetches the according language overlays for the DAM records shown in the frontend depending on the value given in the well known “L” variable. Please refer to the "Multi language sites in TYPO3" document and the DAM documentation and to get a detailed insight.

In brief, you have to perform the following steps to localize your DAM records:

Add a new website-language in the root page

Add the L variable and sys_language_uid setting to the config part of your TypoScript setup

Create a translation for the Media sysfolder (like you would do for a normal page)

Translate your DAM records using the language selector that now appears above each record

Translate the pages that you want to see in another website language

Translate the content records in which you use your DAM images

As soon as a page get's called with the “L” variable damlightbox will fetch the localized DAM record based on the integer value of the variable. In case you have a very special setup, it's also possible to override the automatic setting using the TypoScript option “plugin.tx_damlightbox_pi1.select.language”.

Reference¶

AND tx_dam_mm_ref.tablenames='tx_my_extension' AND tx_my_extension.uid={field:uid}

[globalVar = GP:MY_LANGUAGE_VAR = 1]
plugin.tx_damlightbox_pi1.select.language = 1
[global]
[globalVar = GP:MY_LANGUAGE_VAR = 2]
plugin.tx_damlightbox_pi1.select.language = 2
[global]

config.SHEETNAME.field = value

config.sDEF.imgPreview = 0

Accessing metadata: lib.damlightbox¶

During page rendering plugin.tx_damlightbox_pi1 fetches the DAM metadata of the images that belongs to the current record and writes it into the global register tx_damlightbox. This ensures that all DAM data is globally accessible with TypoScript. The following picture (produced with plugin.tx_damlightbox_pi1.debugData = 1) illustrates this:

Three areas are relevant:

• query: This holds the query that was built to fetch the metadata for the current record. Useful for debugging purposes
• metadata: The sets of DAM metadata that were fetched for the images of the current record. They are stored using the imagenumber from the record as key (starting with “0”)
• config: This config array holds the values of the backend flexform of the current record merged with the standard values set from TypoScript

TSRef tells us that we can read values from an array using the “pipe syntax”. You can therefore get the metadata for the images by using the following notation:

TSFE:register|tx_damlightbox|metaData|IMAGENUMBER|FIELDNAME

To make life easier, DAM Lightbox comes with a predefined TypoScript library that does this job for you. Its called lib.getDAMvalues:

lib.getDAMvalues = TEXT
lib.getDAMvalues {
        wrap = {|}
        cObject = TEXT
        cObject {
                value = TSFE:register|tx_damlightbox|metaData|IMAGENUMBER|FIELDNAME
                insertData = 1
        }
        insertData = 1
        htmlSpecialChars = 1
}

It consists of two nested TEXT objects. The inner one dynamically builds the string that is needed to fetch the values from the TSFE array using the insertData property. The outer one executes the inner TEXT object using insertData property.

tt_content.image.20.caption {
        10 < lib.getDAMvalues
        10.cObject.value = TSFE:register|tx_damlightbox|metaData|{register:IMAGE_NUM_CURRENT}|description
}

Reference¶

tx_my_extension.imagecaption < lib.getDAMvalues
tx_my_extension.imagecaption.cObject.value = TSFE:register|tx_damlightbox|metaData|{register:currentImg}|caption

Click-Enlargement: pagetype 313¶

Why 313? Well, its the number plate of Donald Duck's car... :) And in our case its also the typeNum of the damlightbox PAGE object. Regardless if you use d4u_slimbox or if just open the images in a classic popup, the basic principle remains is the same: The click- enlarged images are opened using a PAGE object that is called by pagetype 313. This pagetype is responsible for displaying the lightbox/popup content.

In comparison to the classic TYPO3 showpic function this approach has the advantage that every part of the HTML content of the popup can be influenced. For opening a DAM image in the DAM Lightbox pagetype three parameters are relevant:

type: This makes TYPO3 using the DAM Lightbox pagetype for record display

content: This contains the record & table that should be displayed

img: This is the image number that should be displayed

http://mywebsite.com/index.php?id=5&type=313&content=tt_content_2&img=0&cHash=ef8a779cdc

imageLinkWrap = 1
imageLinkWrap {
        enable = 1
        typolink {

                ## caching ##
                no_cache = 0
                useCacheHash = 1

                parameter.data = TSFE:id

                additionalParams.cObject = TEXT
                additionalParams.cObject {
                        htmlspecialchars = 1
                        dataWrap = |&type=313&content=tt_content_{field:uid}&img={register:IMAGE_NUM_CURRENT}
                }
        }
}

damlightbox {
        10.10.tables := addToList(tx_mytable)
        10.10.conf.tx_mytable =< lib.damlightbox.clickEnlargeConf
}

lib.damlightbox.clickEnlargeConf.20.marks.DAM_CREATOR {

        10 < lib.damlightbox.getDAMvalues
        10.cObject.value = TSFE:register|tx_damlightbox|metaData|{register:currentImg}|creator
        10.outerWrap = <span id=”creator”>|</span>

}

damlightbox.10.10.conf.tx_mytable.20.marks.DAM_CREATOR.[...]

Reference¶

d4u_slimbox¶

There are many very good lightbox in extensions in the TER. Some of them based on jquery, some of them based on mootools, some of them based on other cool JavaScript libraries. Why d4u_slimbox as implementation example for DAM Lightbox? Well,

It is very configurable with TypoScript

It offers to open up external HTML content within an iframe, which is a crucial feature for the click-enlargement strategy of DAM Lightbox

Its very stable, cross browser and can be used together with t3mootools

Its impossible to do justice to all ;)

That doesn't mean that its not possible to customize other lightbox extension for DAM Lightbox. In most cases you will only need to study how a specific lightbox extension utilizes the a tag parameters and/or link attributes that lead to the activation of it's JavaScript functionality. Once you know, its only peace of cake to adapt the image links generated by DAM Lightbox to fit the specific needs of your lightbox extension. In future versions it is planned to add support to other lightbox extensions from TER besides d4u_slimbox. Just send in your candidates or do a feature request on the TYPO3 forge.

This screenshot shows du4_slimbox in action together with damlightbox. The caption besides the print and save buttons was generated from the DAM description field and inserted into the title attribute of the link tag. The content inside d4u_slimbox (title, image, creator, url) is “external” HTML content generated by pagetype 313 and opened inside an iframe. The print and save buttons reference the original file from the fileadmin directory.

Reference¶

myImage.imageLinkWrap.typolink < lib.damlightbox.d4u_slimbox.imageLinkWrap.typolink.ATagParams

How to: Implement a custom flexform feature¶

<showSquares>
        <TCEforms>
                <label>LLL:fileadmin/custom_flexform_locallang.xml:tx_damlightbox.showSquares</label>
                <config>
                        <type>check</type>
                </config>
        </TCEforms>
</showSquares>

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<T3locallang>
        <meta type="array">
                <type>database</type>
                <description>Language labels for the flexform belonging to damlightbox</description>
        </meta>
        <data type="array">
                <languageKey index="default" type="array">
                        <label index="tx_damlightbox.showSquares">Square thumbnails</label>
                </languageKey>
                <languageKey index="de" type="array">
                        <label index="tx_damlightbox.showSquares">Quadratische Thumbnails</label>
                </languageKey>
        </data>
</T3locallang>

TCEFORM.tt_content.tx_damlightbox_flex.config.ds.default = FILE:fileadmin/tt_content_flexform.xml

plugin.damlightbox.debugData = 1

TSFE:register|tx_damlightbox|config|sDEF|showSquares

## first clear the equalH object; its in our way because it overrides dimension settings ##
tt_content.image.20.equalH >

## implement new dimensions ##
tt_content.image.20.1.file {

        # clear old calculation
        width >

        # new width calculation including crop scaling depending on showSquares value
        width.cObject = TEXT
        width.cObject {
                field = imagewidth
                outerWrap = |c
                outerWrap.if.isTrue.data = TSFE:register|tx_damlightbox|config|sDEF|showSquares
        }

        # new height object with two possibilities
        height.cObject = COA
        height.cObject {

                # 1: in case showSquares is not checked use the height field
                10 = TEXT
                10 {
                        field = imageheight
                        if.isFalse.data = TSFE:register|tx_damlightbox|config|sDEF|showSquares
                }

                # 2: in case showSquares is checked take the width as basis and do crop scaling
                20 = TEXT
                20 {
                        field = imagewidth
                        wrap = |c
                        if.isTrue.data = TSFE:register|tx_damlightbox|config|sDEF|showSquares
                }
        }
}

How to: DAM Lightbox & other extensions¶

Due to the fact that almost every functionality of DAM Lightbox is customizable with TypoScript, in most cases it becomes straightforward to connect other extensions it. The following tutorial is a brief step-by-step guide that shows you an example implementation for the tt_address table. Since every extension is coded differently, the steps might sometimes be a bit different. Nevertheless tt_address can serve as a good example to illustrate the basic principles.

$TYPO3_CONF_VARS['EXT']['extList'] = '...OTHER EXTS...,tt_address,damlightbox';

// tt_address hook
$TYPO3_CONF_VARS['EXTCONF']['tt_address']['extraItemMarkerHook']['tx_damlightbox_pi1'] = 'fileadmin/class.tx_damlightbox_ttaddress.php.inc:tx_damlightbox_ttaddress';

class tx_damlightbox_ttaddress extends tx_ttaddress_pi1 {

        public function extraItemMarkerProcessor($markerArray, $address, &$lConf, &$pObj) {

                // prepare the context: set the address record as current cObject
                $pObj->cObj->data = $address;
                $pObj->cObj->currentRecord = 'tt_address:'.$address['uid'];

                // insert marker for DAM images with stdWrap properties
                $markerArray['###DAM_IMAGE###'] = $pObj->cObj->stdWrap($lConf['dam_image.'], $lConf['dam_image.']);

                return $markerArray;
        }
}

plugin.tx_ttaddress_pi1.templates.default.dam_image.cObject = COA
plugin.tx_ttaddress_pi1.templates.default.dam_image.cObject {

        10 =< plugin.tx_damlightbox_pi1
        10.debugData = 1
}

plugin.tx_ttaddress_pi1.templates.default.dam_image.cObject {
20 = USER
20 {
        userFunc = tx_damlightbox_pi1->frontendImageIterator

        file {
                import.cObject < lib.damlightbox.getDAMvalues
                import.cObject {
                        cObject.value = TSFE:register|tx_damlightbox|metaData|{register:currentImg}|fullPath
                }
                maxW = 300
                maxH = 200
        }

        ## alt texts from DAM ##
        altText.cObject < lib.damlightbox.getDAMvalues
        altText.cObject.cObject.value  = TSFE:register|tx_damlightbox|metaData|{register:currentImg}|alt_text

        ## title texts from DAM ##
        titleText.cObject < lib.damlightbox.getDAMvalues
        titleText.cObject.cObject.value  = TSFE:register|tx_damlightbox|metaData|{register:currentImg}|title

        ## image link for click enlarge ##
        imageLinkWrap = 1
        imageLinkWrap {
                enable = 1
                typolink {

                        ## caching ##
                        no_cache = 0
                        useCacheHash = 1

                        parameter.data = TSFE:id

                        parameter.append = TEXT
                        parameter.append {
                                if.isFalse.field = image_link
                                value = {$plugin.damlightbox.jsParams}
                                noTrimWrap = | ||
                        }

                        additionalParams.cObject = TEXT
                        additionalParams.cObject {
                                htmlspecialchars = 1
                                dataWrap = |&type=313&content=tt_address_{field:uid}&img={register:currentImg}
                        }

                        ATagParams.cObject = TEXT
                        ATagParams.cObject {
                                value = {$plugin.damlightbox.imageLinkAttributes}
                        }
                }
        }
}

## register tt_address table in the click-enlargement pagetype ##
damlightbox {
        10.10.tables := addToList(tt_address)
        10.10.conf.tt_address =< lib.damlightbox.clickEnlargeConf
}

plugin.tx_ttaddress_pi1.templates.default.dam_image.cObject {

        20.imageLinkWrap.typolink {

                parameter.append >

                ATagParams >
                ATagParams < lib.damlightbox.d4u_slimbox.imageLinkWrap.typolink.ATagParams
        }
        stdWrap.postCObject = TEXT
        stdWrap.postCObject {
                if.isTrue.data = TSFE:register|tx_damlightbox|config|sDEF|imgPreview
                cObject = USER
                cObject.userFunc = tx_damlightbox_d4u_slimbox->addHiddenImgs
                cObject {
                        content.data = field:uid
                        content.table = tt_address
                        hCalc.cObject = TEXT
                        hCalc.cObject.value = {$plugin.damlightbox.d4u_slimbox.hCalc}
                        vCalc.cObject = TEXT
                        vCalc.cObject.value = {$plugin.damlightbox.d4u_slimbox.vCalc}
                }
        }
}

damlightbox {
        10.10.conf.tt_address.20 {

                template.file = {$plugin.damlightbox.d4u_slimbox.templateFile}
                marks.DAM_TITLE.outerWrap >
        }
}

Version:¶

0.2.1¶

0.2.0¶

0.1.2¶

0.1.1¶

0.1.0¶

0.0.2¶

0.0.1¶

28