method_register_modal()
method_register_modal( array $args )
Registers a modal to be printed in the footer. Any link to #<id> on the page opens it.
Description
The PHP entry point to the Modals registry — what the Modal block’s render callback calls, and what a plugin or child theme calls to add a modal of its own. The content is rendered by the caller and handed over as HTML; the registry prints the modal’s markup once, directly under <body>, on wp_footer (priority 5, with a second pass at 19), and enqueues the trigger script on pages that have at least one modal.
Call it while the page is rendering and no later than wp_footer priority 18. Render content before calling, not from a footer callback, so that asset enqueues made by the content happen in time. A wrapper around Method_Modals::instance()->register( $args ).
Parameters
$args (array) :
Modal arguments:
| Key | Type | Default | Description |
|---|---|---|---|
id | string | required | Sanitised with method_sanitize_modal_id(); an id that sanitises to nothing is rejected. The first registration of an id wins. |
title | string | '' | Plain text. Printed as the heading, and labels the dialog through aria-labelledby even when hidden. |
content | string | '' | Rendered HTML for the modal body. Passed through the method/modal_content filter, which carries the usual content filters (wptexturize, do_shortcode, wp_filter_content_tags, …). |
scope | string | 'post' | post or site; the current push_context() supplies it when unset. |
source | string | '' | Free-form origin, e.g. block; from the context when unset. |
class | string | '' | Extra classes for the modal element. |
css | string | '' | CSS for this modal, collected with method_collect_css() under #<id>.method-modal. |
assets | array | array() | Handles the content enqueued while it rendered, as styles, scripts and modules, kept enqueued (see Method_Modals::snapshot_assets()). |
options | array | array() | Merged over Method_Modals::default_options(): size (default), fullscreen_below ('', mobile or tablet), centered, scrollable, static_backdrop, hide_title, title_tag (h2), close_icon (a theme icon slug), close_label (“Close”). |
Return
(string|false) The id the modal can be opened with — also when that id was already registered, since the first registration wins — or false if the modal was not registered: method/modal_args returned false, the id sanitised to nothing, or the registry had already closed (after wp_footer priority 19, which also raises _doing_it_wrong()).
Source
File: lib/class-method-modals.php
Usage
add_action( 'method/register_modals', function ( Method_Modals $registry ) {
$registry->push_context( array( 'scope' => 'site', 'source' => 'newsletter' ) );
method_register_modal( array(
'id' => 'newsletter',
'title' => __( 'Join the newsletter', 'child' ),
'content' => do_blocks( get_option( 'child_newsletter_modal' ) ),
'options' => array( 'size' => 'lg', 'centered' => true ),
) );
$registry->pop_context();
} );
Any <a href="#newsletter"> on the page then opens it. The method/register_modals action fires on wp_enqueue_scripts at priority 5, after the block template has rendered, so modals declared in content win an id collision with anything added here.
Notes
- Hooks that run during registration:
method/modal_args(before; returnfalseto skip),method/modal_content, thenmethod/modal_registeredafter, ormethod/modal_duplicatewhen the id is already taken. All are documented on the Modals page. - The function is defined after the class in
lib/class-method-modals.php, whichfunctions.phploads, so it exists from the start of the request. - A full-screen-below-a-tier option adds one shared CSS rule per tier (
Method_Modals::get_fullscreen_css()), however many modals use it.
Changelog
| Version | Description |
|---|---|
| 2.0.0-beta26 | Introduced, with the modal registry (e12c9c0). |