README

A configurable layer/popup module for Contao CMS 5.x.
No jQuery, no external dependencies — pure vanilla JavaScript.

Requirements

• PHP ^8.2
• Contao ^5.3

Installation

composer require srhinow/srlayer

Then run the Contao install tool (or contao:migrate) to apply the database schema:

php bin/console contao:migrate --no-interaction
php bin/console assets:install --symlink

Usage

1. Go to Modules in the Contao back end and create a new module of type SR-Layer.
2. Configure the module (see options below).
3. Include the module in a page layout or add it to a page via an article.

The module renders an overlay and a layer container. Both elements are hidden by default and shown/hidden via JavaScript.

Module options

Layer content (layer_legend)

Visibility settings (show_legend)

Controls when the layer is triggered.

Tip: Show without parameter and GET parameter can both be active at the same time. The layer opens if either condition is met.

Session cookie (session_legend)

Domain cookie (cookie_legend)

Set domain cookie

Restrict repeated display via a persistent cookie.

When active, the layer is shown once and then suppressed for the cookie lifetime. The cookie is set by the server on the first display.

Evaluate domain cookie

Show the layer only when a specific cookie is already present in the browser. This is useful for showing a popup to users who previously submitted a form (see Form-triggered cookies).

Expert options (expert_legend)

JavaScript options (js_legend)

Activate this section to override the default element IDs, CSS classes and behaviour.

Styling

The default stylesheet (bundles/srhinowsrlayer/css/srl_default.css) sets up a centered, fixed-position popup with a dark overlay. Override any rule in your own CSS or select a custom stylesheet in the module settings.

The default HTML structure rendered by the module:

<div id="srl_overLay"></div>
<div id="srl_layer">
    <div id="srl_closeBtn">Schließen</div>
    <div class="srl_content">
        <!-- your layer content -->
    </div>
</div>

The close button label uses the translatable string MSC.srl_close (German: Schließen, English: Close, and several other languages).

Opening the layer from a link

Set the module option Open layer via link and add the CSS class openlayer to any anchor tag on the same page:

<a href="#" class="openlayer">Open popup</a>

Alternatively use the rel attribute (legacy):

<a href="#" rel="openlayer">Open popup</a>

Closing the layer from a custom element

Any element with the CSS class srl_closer (or the class configured in Close link class) closes the layer when clicked. You can place these elements inside or outside the layer container:

<a href="#" class="srl_closer">Cancel</a>

Additional JS options

The Additional JS options field lets you pass extra key-value pairs directly to the SrLayer constructor without writing any PHP. The content is inserted verbatim, so standard JavaScript syntax applies:

showNow: true, centerX: false

The full list of available options with their defaults:

new SrLayer({
    overLayID:          'srl_overLay',
    layerID:            'srl_layer',
    closeID:            'srl_closeBtn',
    closeClass:         'srl_closer',
    openClass:          'openlayer',
    overLayOpacity:     0.7,
    closePerLayerClick: true,
    closePerEsc:        true,
    mkLinkEvents:       true,
    centerX:            true,
    centerY:            true,
    duration:           300,   // ms
    layerWidth:         0,     // 0 = use CSS
    layerHeight:        0,     // 0 = use CSS
    delay:              0,     // ms — only delays auto-open; click listeners register immediately
    openParam:          '',    // GET parameter key whose presence in a link href opens the layer on click
    showNow:            false
});

Form-triggered cookies

Use the PrepareFormDataListener to set a cookie when a Contao form is submitted. Add hidden fields to the form:

Workflow example — show a newsletter teaser only to visitors who have not yet subscribed:

1. Create a newsletter signup form with the hidden fields above.
2. Create an SR-Layer module with Evaluate domain cookie → NEWSLETTER_COOKIE.
3. Add both to the page layout.

After the visitor submits the form the cookie is set and the layer is suppressed on all future visits.

Multilingual back end

The module back end labels are available in:

de · en · cs · es · fr · it · nl · pl · pt · ru

Development

Running tests

The unit tests require PHPUnit and symfony/http-foundation. When working inside a Contao project where the bundle is symlinked into vendor/, point the bootstrap to the project's autoloader:

SRLAYER_AUTOLOAD=/path/to/contao5/vendor/autoload.php phpunit

For standalone use, run composer install in the package directory first, then:

composer test

Code style

PHP_CS_FIXER_IGNORE_ENV=1 php-cs-fixer fix

Changelog

See CHANGELOG.md.

License

LGPL-3.0-or-later — see LICENSE for details.
Author: Sven Rhinow