asconsulting/contao-zyppy-popup

Turns any article or front end module into a pop-up for Contao 5. Tick Popup on the record, choose how and when it opens, and the bundle wraps it in an overlay frame at the end of <body>.

A pop-up can also carry an Accept/Reject step. In its decorative form that is a client-side nag box; in its enforced form it is a real server-side gate that withholds the content until the visitor has accepted, which is what an age check or a terms-of-service gate needs.

Requirements

Installation

composer require asconsulting/contao-zyppy-popup:^5.0

Then run the database migration. Contao Manager does this on install and on update; on the command line it is vendor/bin/contao-console contao:migrate. Besides adding the pop-up columns to tl_article and tl_module, the migration adds a custom Pop-up section, ID popup, to every existing page layout, and new layouts get it as their default. You do not have to create that section by hand, and you do not have to open each layout in the back end to make the bundle notice it.

If a site builder deliberately removes the Pop-up section from a layout, the migration puts it back the next time it runs. If a section with ID popup already exists under a different title, only its title is corrected; its template and position are left alone.

Usage

Setting up a pop-up

  1. Edit the article or front end module and tick Popup in its Popup Settings legend. The pop-up fields below appear.
  2. Put the record where the bundle looks for it. Where that is depends on the page layout type — see Page layout type.

Pop-up settings

Field Meaning
Unique ID (popupUuid) Generated automatically. It is the key of the consent cookie, so it is made with random_bytes(); do not hand-edit it to something guessable.
CSS Class A class added to the pop-up frame.
Delay Milliseconds to wait before the pop-up is shown.
Reshow Delay Minutes before the same visitor sees the pop-up again.
Scroll Trigger Show the pop-up once the visitor has scrolled this many pixels.
Fade Duration Length of the fade-out, in milliseconds.
Trigger A CSS selector; clicking a matching element opens the pop-up.
Add Close Button Adds a close button to the frame.
Accept Popup The visitor must accept the pop-up. Reveals Consent mode and Popup Reject — see Consent modes.
Popup Reject Where to send a visitor who rejects.
Clear on Popup (modules only) With asconsulting/contao-zyppy-search installed, clears a live search's results when the pop-up opens.

Page layout type

Pop-ups work on both Contao page layout types.

The two layout types take completely different code paths inside Contao - a modern layout never fires the generatePage hook - but both go through the same consent gate here, so an "Enforced" pop-up withholds its content identically on either. If anything at all goes wrong while building a pop-up on a modern layout, the pop-up is dropped and an error is written to the application log; it is never published without its gate.

If a default layout ends up with no section whose ID is exactly popup, a module pop-up on that layout is generated and then dropped by Contao without being rendered. The bundle writes a clear error to the application log (var/logs/, the Monolog app channel) when that happens. It is not the back end "System log": that table is only fed by records carrying a Contao ContaoContext, which this bundle does not add.

Ticking "User must accept popup" adds a "Consent mode" field with two options. These are two different features with two different guarantees - pick deliberately, not by habit:

The template

To edit the pop-up markup (close button, Accept/Reject controls, etc), see the fe_popup_wrapper template. It is used for both module and article pop-ups. It is a Twig template (contao/templates/frontend/fe_popup_wrapper.html.twig); override it the way you override any Contao template, under the same flat fe_popup_wrapper identifier. Twig autoescapes, so a value you add to it is escaped by default; only body is deliberately raw.

Migration from legacy version

This package replaces the legacy package asconsulting/zyppy_popup (namespace ZyppyPopup\). The old name does not resolve any more.

The four legacy Zyppy packages — page, classes, popup and search — have to be upgraded together, in one composer update: old and new packages register the same DCA fields and module types, so a site that briefly has both installed double-registers. The walkthrough for the whole suite, including the order of operations and a verification checklist, is UPGRADING.md in the contao-zyppy-page repository. The part specific to this package:

Development

composer install
vendor/bin/phpunit --no-coverage

Licence

Licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). See LICENSE. Copyright Andrew Stevens.

Downloads

VersionReleasedFile
5.0.1contao-zyppy-popup-5.0.1.zip 101 KB
5.0.0contao-zyppy-popup-5.0.0.zip 101 KB