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:

KeyTypeDefaultDescription
idstringrequiredSanitised with method_sanitize_modal_id(); an id that sanitises to nothing is rejected. The first registration of an id wins.
titlestring''Plain text. Printed as the heading, and labels the dialog through aria-labelledby even when hidden.
contentstring''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, …).
scopestring'post'post or site; the current push_context() supplies it when unset.
sourcestring''Free-form origin, e.g. block; from the context when unset.
classstring''Extra classes for the modal element.
cssstring''CSS for this modal, collected with method_collect_css() under #<id>.method-modal.
assetsarrayarray()Handles the content enqueued while it rendered, as styles, scripts and modules, kept enqueued (see Method_Modals::snapshot_assets()).
optionsarrayarray()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

PHP
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; return false to skip), method/modal_content, then method/modal_registered after, or method/modal_duplicate when 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, which functions.php loads, 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

VersionDescription
2.0.0-beta26Introduced, with the modal registry (e12c9c0).