Pages built in the code editor, with the ef CLI or from a kit can open the same popups you build in Pages → Advanced → Popups, and run the same actions the page builder’s Interactions panel offers. The store edits the popup in the app; the page only says when to open it.
ef.popup and ef.interactions ship with the current runtime release. Until it is live on your pages, ef.popup is undefined.
Which one to use
Put data-ef-popup on any element. No script needed.
- The value is the popup’s name as it appears in Pages → Advanced → Popups, or its numeric id. Use the name in templates and kits: ids change when a kit is installed in another brand, names don’t.
- On a link, the click is taken over and the popup opens. Without JavaScript, or if the popup was deleted or renamed, the link goes where its
href says, so point it at something useful: an in-page section (#whats-inside) or a page.
- Close buttons inside the popup:
data-ef-popup-close (or the builder’s close element). Escape and a click outside the popup’s box (data-modal-window="true") close it too.
Other triggers on an element
Exit intent, timers and scroll depth belong in page events, where the store can see and change them.
Show it once
data-ef-popup-cap="tag:minutes" skips the popup while the visitor has the tag and adds the tag when it opens. It is the same tag the Has tag and Add tag nodes use, so a page event and a click can share one cap. Without minutes the tag lasts for the browser session.
Inline modals
When the modal shows what the visitor chose on this page, keep it in the page and open it the same way:
A <dialog> opens with showModal(), so the page behind is inert and Escape closes it. Any other element (for example a builder modal with data-modal="true") is shown, gets role="dialog", keeps focus inside and closes on Escape. Focus goes back to the button that opened it.
From JavaScript
open returns a promise of true when the popup opened, false when it was capped, already open, another popup was open (pass force: true to stack it) or it does not exist.
Events
Analytics
Platform popups report popup-show (once per page view, with the trigger) and popup-close (with dismissed_after_ms and via), whether a page event or a click opened them. Inline modals report modal-show and modal-close.
Builder interactions from code
ef.interactions runs the actions of the builder’s Interactions panel.
Or in markup, trigger:action:value, several separated by ;:
Triggers: click, hover, mouseenter, mouseleave, focus, blur, load, in-view, on-form-submit, on-form-success, on-form-error.
Actions: show_popup, hide_popup, show_modal, hide_modal, show_element, hide_element, visibility-toggle, focus-on-element, track-event, custom-event, split-test-goal, and the animate-* set (animate-fade-in, animate-pulse, animate-shake, …).
Kits and templates
A kit carries every popup its pages open, by name, in kit.json exit_popups, together with the page events that open them. When the kit is installed the popups are copied into the brand, page events point at the copies, and data-ef-popup="Free gifts" finds the copy by name. Building the kit warns when a page opens a popup by id or names one that doesn’t exist.
