srhinow / srlayer
Dependency-free layer/popup front-end module for Contao 5. Displays a configurable overlay without any JavaScript library. Supports auto-show on page load, click triggers via CSS class or rel="openlayer", GET-parameter triggers for landing pages, and cookie/session-based display control.
Maintainers
Requires
- php: ^8.2
- contao/core-bundle: ^5.3
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
- Go to Modules in the Contao back end and create a new module of type SR-Layer.
- Configure the module (see options below).
- 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)
| Field | Description |
|---|---|
| Layer content | HTML content of the layer. Contao insert tags like {{insert_content::23}} or {{insert_article::5}} are fully supported. |
| CSS file | Optional custom CSS file (file picker). If none is selected the bundled srl_default.css is used automatically. |
Visibility settings (show_legend)
Controls when the layer is triggered.
| Field | Description |
|---|---|
| Show without parameter | The layer opens immediately on page load. |
| Open layer via link | Links with the CSS class openlayer (or rel="openlayer") open the layer on click. The layer is rendered but stays hidden until a matching link is clicked. |
| GET parameter | The layer opens when the given key appears in the URL query string — e.g. set srl and the layer opens for https://example.com/page?srl=1. The value of the parameter is irrelevant; only the key is matched. |
| Display delay (ms) | Number of milliseconds to wait before opening the layer after the page has loaded (e.g. 2000 = 2 seconds). Works together with Show without parameter and GET parameter. |
| Show from | Date/time from which the layer becomes active. |
| Show until | Date/time after which the layer is no longer shown. |
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)
| Field | Description |
|---|---|
| Set session cookie | The layer is shown only once per browser session. On the next page load within the same session it is suppressed. |
Domain cookie (cookie_legend)
Set domain cookie
Restrict repeated display via a persistent cookie.
| Field | Default | Description |
|---|---|---|
| Cookie name | LAYER_<id>_COOKIE | Name of the cookie. Leave empty to use the auto-generated name. |
| Cookie lifetime (seconds) | 3600 | How long the cookie persists. 86400 = 1 day, 604800 = 1 week. |
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).
| Field | Description |
|---|---|
| Cookie name | Exact name of the cookie that must be present for the layer to appear. |
Expert options (expert_legend)
| Field | Description |
|---|---|
| Hide overlay | Suppresses the semi-transparent background overlay. Only the layer container is rendered. |
JavaScript options (js_legend)
Activate this section to override the default element IDs, CSS classes and behaviour.
| Field | Default | Description |
|---|---|---|
| Overlay ID | srl_overLay | id attribute of the overlay <div>. |
| Layer ID | srl_layer | id attribute of the layer <div>. |
| Open link class | openlayer | CSS class that turns any <a> tag into an open-trigger. |
| Close button ID | srl_closeBtn | id of the built-in close button inside the layer. |
| Close link class | srl_closer | Any element with this class closes the layer on click. |
| Overlay opacity | 0.7 | Opacity of the background overlay (0.0 = invisible, 1.0 = fully opaque). |
| Transition speed (ms) | 300 | Duration of the fade-in/fade-out animation in milliseconds. Set to 0 to disable animation. |
| Layer width (px) | (CSS default) | Fixed pixel width applied to the layer element via JavaScript. Leave empty to rely on CSS. |
| Layer height (px) | (CSS default) | Fixed pixel height applied to the layer element via JavaScript. |
| Close with ESC key | ✔ | When checked, pressing the Escape key closes the layer. |
| Close by clicking overlay | ✔ | When checked, clicking the background overlay closes the layer. |
| Center horizontally | ✔ | JavaScript keeps the layer centered on the X axis, even on window resize. |
| Center vertically | ✔ | JavaScript keeps the layer centered on the Y axis, even on window resize. |
| Additional JS options | — | Raw key-value pairs appended to the SrLayer constructor. See below. |
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:
| Field name | Example value | Description |
|---|---|---|
srlayer_set_cookie | NEWSLETTER_COOKIE | Name of the cookie to set on submit. |
srlayer_check_field | email | The form field that must be non-empty for the cookie to be set. |
srlayer_cookie_duration | 2592000 | Cookie lifetime in seconds (default: 3600). |
Workflow example — show a newsletter teaser only to visitors who have not yet subscribed:
- Create a newsletter signup form with the hidden fields above.
- Create an SR-Layer module with Evaluate domain cookie →
NEWSLETTER_COOKIE. - 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
Changelog
See CHANGELOG.md.
License
LGPL-3.0-or-later — see LICENSE for details.
Author: Sven Rhinow