Download the PHP package model/popup without Composer

model/popup

A simple JavaScript popup.

This is the ModEl 4 port of the legacy Popup module. It ships the popup's CSS/JS as an asset library declared through an AssetsProvider, so model/assets discovers and serves them automatically — no manual file inclusion needed.

Unlike the v3 module, it has no hard dependency on the legacy FrontEnd module: the helpers it used to borrow from it (_, ajax, loading, jsFill, changedHtml) are now implemented internally, and the FrontEnd implementations are used instead whenever they happen to be present.

Installation

Enabling the assets

The library is registered under the name popup but is not auto-enabled. Enable it (typically from a controller's init) wherever a page uses the popup:

This adds style.css (in the head) and js.js (in the foot) to the asset render list.

Usage

There can be only one popup open at a time. Open it with zkPopup:

It returns a Promise, resolved once the popup is fully open (and its content loaded).

Content

The first argument can take three different forms:

• a HTML string: used as-is as the popup content.
• a "#element-id" string: the content of that element is moved into the popup, and moved back to its original parent when the popup is closed. With the clone option it is copied instead (and the original is left untouched).
• an object in the form {url, get, post}: the content is loaded via ajax from url. get and post are both optional plain objects of parameters; if post is non-empty the request is made with the POST method.

Any <script> tag contained in the loaded HTML is executed.

Options

The second argument is an optional object of options:

• top, left (default false): the position of the popup, in pixels. If false, the popup is centered on that axis.
• width, height (default false): the size of the popup, either a number of pixels, a "400px"-like string or a "50%"-like string (a percentage of the window size). If false, the popup adapts to its content.
• background (default '#FFF'): any CSS background value. If falsy, the popup is rendered with no background and no shadow.
• border-radius (default '4px'), padding (default '15px'): any CSS value.
• showCover (default true): whether to render the dark cover behind the popup.
• closeOnCoverClick (default true): whether clicking the cover closes the popup.
• showClose (default true): whether to render the close button on the top-right corner.
• safeMargin (default 40): the minimum number of pixels to leave free between the popup and the window borders; the popup is shrunk if it would not fit.
• onLoad (default false): a callback called once the content has been loaded.
• onClose (default false): a callback called when the popup is about to be closed. Returning false from it vetoes the closing.
• clone (default false): with a "#element-id" content, copy the element content instead of moving it.
• observe-content (default true): watch the popup content via a MutationObserver and resize the popup accordingly whenever it changes.

The defaults can be changed globally by editing zkPopupDefaultOptions.

Closing the popup

The popup is also closed by pressing Esc or by clicking the cover (unless closeOnCoverClick is false) or the close button. Pass true to skip the onClose callback (and thus close the popup unconditionally): zkPopupClose(true).

Resizing the popup

zkPopupFill(), called with no arguments, re-calculates the size and the position of the popup against its current content. It is called automatically on window resize and, if observe-content is on, whenever the content changes; you only need it if you disabled the observer and changed the content by hand.