Kindly EditDocumentationTry the editor

popups.php

Registers popup records, validates settings and display rules, resolves public payloads, records bounded event statistics, and manages library operations.

Responsibility#

Registers popup records, validates settings and display rules, resolves public payloads, records bounded event statistics, and manages library operations.

This is an implementation reference for the released 0.9.13 module. Internal PHP helpers are not a compatibility promise for third-party callers. Prefer the documented REST, Abilities, theme, and filter contracts.

element-js, forms, render, responsive, rest, templates, theme.

Module constants#

const CANTATA_EDIT_POPUP = 'kindly_popup';

These values describe this release. Defined configuration constants and generated identifiers can have different ownership; do not edit stored values directly without following the corresponding workflow.

WordPress hooks#

Operation Hook
apply_filters cantata_edit_popups_cap
add_action init
add_filter cantata_edit_content_owner_check
add_action cantata_edit_saved
add_action template_redirect
add_filter oembed_request_post_id
add_filter template_include
add_filter the_content
add_filter widget_text
add_filter render_block
add_action wp_footer
add_action rest_api_init
apply_filters cantata_edit_popup_events_per_minute

add_action and add_filter subscribe to a hook; do_action and apply_filters expose a hook. A subscription is not itself a new extension API. Dynamic hook names are not included in this literal inventory.

Function and method reference#

cantata_edit_can_popups#

function cantata_edit_can_popups(): bool

People who create, change and see popups (their stage, drafts and settings).

Source location: includes/popups.php:26.

cantata_edit_popup_schema#

function cantata_edit_popup_schema(): array

Every popup setting, once: its kind, its choices or range, its default and what it does. The parser below checks against it, the editor builds its defaults from it, GET cantata-edit/v1/popups/schema hands it to connected builders and agents, and the source design notes and docs/popup-settings.schema.json describe the same table. A setting not listed here does not exist: settings JSON naming anything else is refused, never silently dropped.

Kinds: bool; int (min, max); enum (options); list (options, several, no repeats); len (units; zero: 0 allowed; also: words accepted as well as lengths); color (empty: '' allowed, meaning the theme's own); sel (a CSS selector); str (pattern, max); strs (a list of str, max items); time (HH:MM); when (YYYY-MM-DDTHH:MM in the site's time zone); days (weekday numbers, 0 Sunday to 6 Saturday); size (a screen size's own overrides: width, height, h, v, edge).

Source location: includes/popups.php:53.

cantata_edit_popup_rule_kinds#

function cantata_edit_popup_rule_kinds(): array

Where rules (include and exclude), and when (triggers), described for agents and the editor.

Source location: includes/popups.php:134.

cantata_edit_popup_defaults#

function cantata_edit_popup_defaults(): array

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Implementation connections: cantata_edit_popup_schema.

Source location: includes/popups.php:165.

cantata_edit_popup_length#

function cantata_edit_popup_length( $v, array $units, bool $zero = false ): ?string

A CSS length within reason: digits and one of the given units ("0" too when zero is allowed).

Source location: includes/popups.php:172.

cantata_edit_popup_colour#

function cantata_edit_popup_colour( $v ): ?string

A color: #rgb(a), #rrggbb(aa), rgb()/rgba() or hsl()/hsla() with plain numbers.

Source location: includes/popups.php:179.

cantata_edit_popup_selector#

function cantata_edit_popup_selector( $v ): ?string

A CSS selector the browser can match: no braces, semicolons, tags or comments (checked again in the browser).

Source location: includes/popups.php:185.

cantata_edit_popup_value#

function cantata_edit_popup_value( array $d, $v )

One value checked against its schema entry: the clean value, or null when it is not valid.

Implementation connections: cantata_edit_popup_colour, cantata_edit_popup_length, cantata_edit_popup_schema, cantata_edit_popup_selector.

Source location: includes/popups.php:191.

cantata_edit_popup_parse#

function cantata_edit_popup_parse( $json )

A popup's settings (the data-ke-popup JSON) made whole and checked: the clean settings, or WP_Error naming what is wrong. Anything left out takes its default; anything present must be valid (nothing is silently dropped).

Implementation connections: cantata_edit_popup_defaults, cantata_edit_popup_schema, cantata_edit_popup_selector, cantata_edit_popup_value.

Source location: includes/popups.php:243.

cantata_edit_popup_box#

function cantata_edit_popup_box( string $html )

The first data-ke-popup box in a popup's HTML: [ settings or WP_Error, the box's tag count position ], or null.

Implementation connections: cantata_edit_popup_parse.

Source location: includes/popups.php:329.

cantata_edit_popup_settings#

function cantata_edit_popup_settings( WP_Post $p, bool $draft = false ): ?array

A popup's published settings (cached on publish), or its draft's while it is edited. Null: it has no valid box.

Implementation connections: cantata_edit_popup_box, cantata_edit_popup_defaults.

Source location: includes/popups.php:340.

cantata_edit_popup_where_rule#

function cantata_edit_popup_where_rule( array $r ): bool

One include or exclude rule against the page being shown.

Source location: includes/popups.php:393.

cantata_edit_popup_excluded#

function cantata_edit_popup_excluded( array $where ): bool

Whether a Not on rule leaves this page out: then not even a link brings the popup here.

Implementation connections: cantata_edit_popup_where_rule.

Source location: includes/popups.php:427.

cantata_edit_popup_where#

function cantata_edit_popup_where( array $where ): bool

Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.

Implementation connections: cantata_edit_popup_where_rule.

Source location: includes/popups.php:431.

cantata_edit_popup_people#

function cantata_edit_popup_people( array $rules ): bool

Signed-in rules, decided for the person asking.

Source location: includes/popups.php:437.

cantata_edit_popups_here#

function cantata_edit_popups_here(): array

The popups this request gets: [ id => [ post, settings, auto ] ]. auto false: only opened by hand (the popup a form on this page opens after sending, where its own rules don't load it). Decided once, before headers.

Implementation connections: cantata_edit_form_settings, cantata_edit_is_editing, cantata_edit_popup_ended, cantata_edit_popup_excluded, cantata_edit_popup_menu_refs, cantata_edit_popup_people, cantata_edit_popup_refs, cantata_edit_popup_settings, cantata_edit_popup_where.

Source location: includes/popups.php:447.

cantata_edit_popup_refs#

function cantata_edit_popup_refs( string $html ): array

The popups some HTML opens, toggles or closes by number: links to #kindly-popup-ID(-toggle|-close) and data-ke-popup-open.

Source location: includes/popups.php:494.

cantata_edit_popup_menu_refs#

function cantata_edit_popup_menu_refs(): array

The popups the site's menus open (custom links to #kindly-popup-ID): those menus can be on any page.

Implementation connections: cantata_edit_popup_refs.

Source location: includes/popups.php:503.

cantata_edit_popup_ended#

function cantata_edit_popup_ended( array $rules ): bool

Whether a popup's schedule has ended (then no page loads it at all).

Source location: includes/popups.php:514.

cantata_edit_popup_ms#

function cantata_edit_popup_ms( string $when ): int

A schedule's start or end as milliseconds since 1970 (for the visitor's browser), or 0.

Implementation connections: cantata_edit_popups_here.

Source location: includes/popups.php:523.

cantata_edit_popup_devices#

function cantata_edit_popup_devices(): array

The site's screen sizes, as the widest tablet and phone in pixels (the editor's own ranges).

Implementation connections: cantata_edit_screen_ranges.

Source location: includes/popups.php:560.

cantata_edit_popup_run#

function cantata_edit_popup_run( WP_Post $p, array $s, bool $auto ): array

What the visitor's browser needs to run a popup (assets/elements.js); signed-in rules were decided above.

Implementation connections: cantata_edit_can_popups, cantata_edit_popup_devices, cantata_edit_popup_ms, cantata_edit_popup_split_members.

Source location: includes/popups.php:566.

cantata_edit_popup_split_members#

function cantata_edit_popup_split_members( string $group ): array

A split-test group's members site-wide: published popups in the group that can open by themselves and haven't ended. The browser picks one of these once, and picks again only when its pick has left the group.

Implementation connections: cantata_edit_popup_ended, cantata_edit_popup_settings.

Source location: includes/popups.php:586.

cantata_edit_popup_frame#

function cantata_edit_popup_frame( array $l ): array

The classes and custom properties of a popup's frame, from its layout (validated values only). Each screen size's values are their own properties (-t tablet, -p phone); elements.css picks them by the frame's data-kp-size.

Source location: includes/popups.php:602.

cantata_edit_popup_html#

function cantata_edit_popup_html( WP_Post $p, array $s, bool $auto ): string

A popup as visitors get it: its published box as the dialog, with what the browser needs to open it.

Implementation connections: cantata_edit_element_js_owner_for_post, cantata_edit_missing_alts, cantata_edit_popup_frame, cantata_edit_popup_run, cantata_edit_public_forms, cantata_edit_public_links, cantata_edit_render.

Source location: includes/popups.php:628.

cantata_edit_popup_seen#

function cantata_edit_popup_seen( ?string $html = null ): array

Popups that content rendered on this page links to (a theme template, a global element, a widget): seen as it renders.

Implementation connections: cantata_edit_is_editing, cantata_edit_popup_ended, cantata_edit_popup_excluded, cantata_edit_popup_html, cantata_edit_popup_people, cantata_edit_popup_refs, cantata_edit_popup_settings, cantata_edit_popups_here.

Source location: includes/popups.php:656.

cantata_edit_site_has_popups#

function cantata_edit_site_has_popups(): bool

Whether any popup is published (its rules count page views and sessions across the site).

Source location: includes/popups.php:688.

cantata_edit_popup_kinds#

function cantata_edit_popup_kinds(): array

Starting kinds for a new popup (Elementor's and the popup plugins' common shapes). Each only sets layout values a person can change afterwards: there is no stored kind.

Source location: includes/popups.php:697.

cantata_edit_popup_new_html#

function cantata_edit_popup_new_html( string $inner = '', string $kind = 'modal' ): string

A new popup's box: the defaults with its kind's layout, and its first words (or a saved template's HTML) inside.

Implementation connections: cantata_edit_config, cantata_edit_popup_defaults, cantata_edit_popup_kinds.

Source location: includes/popups.php:710.

cantata_edit_popup_stats#

function cantata_edit_popup_stats( int $id, int $days = 30 ): array

Counts for the Popups list (behavior.stats): per popup and day, how many times it opened (by itself or by hand), how many visitors converted (sent a form inside it or followed a link or button inside it that is not a close link) and how many closed it. Only numbers are kept, for 120 days; nothing about the visitor is stored or sent.

Source location: includes/popups.php:726.

cantata_edit_popup_out#

function cantata_edit_popup_out( WP_Post $p ): array

A popup in lists: its name, state, where it loads in words, and where to edit it.

Implementation connections: cantata_edit_can_popups, cantata_edit_popup_defaults, cantata_edit_popup_element_attrs, cantata_edit_popup_kinds, cantata_edit_popup_link_actions, cantata_edit_popup_new_html, cantata_edit_popup_rule_kinds, cantata_edit_popup_schema, cantata_edit_popup_settings, cantata_edit_popup_stats, cantata_edit_template_clean, cantata_edit_url, cantata_edit_without_kses.

Source location: includes/popups.php:742.

function cantata_edit_popup_link_actions(): array

What a link's address does with a popup (any link or button, menus included), for the link field and agents.

Source location: includes/popups.php:865.

cantata_edit_popup_element_attrs#

function cantata_edit_popup_element_attrs(): array

The element setting Advanced > Popup: any element opens, toggles or closes a popup on click or hover.

Source location: includes/popups.php:876.

cantata_edit_popup_element_problem#

function cantata_edit_popup_element_problem( ?string $id, ?string $on, ?string $act ): string

The element setting's attributes, checked (the build contract and the save use it): '' when fine, else why not.

Source location: includes/popups.php:885.

About this page

Documents Kindly Edit 0.9.16. Source: includes/popups.php. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.