Modals

Method’s modals are Bootstrap modals that the page collects while it renders and prints under <body> at the end, so a modal is never trapped in the stacking context of the Section it was authored in. Three parts cooperate: the Modal block (method/modal) that authors write in, the registry (Method_Modals, lib/class-method-modals.php) that collects, de-duplicates and prints them, and a view script (lib/blocks/utils/modals.js) that opens the right modal when any link pointing at its ID is clicked. The registry does not depend on the block, which is what lets a plugin or a child theme register sitewide modals through the same path.

How a modal reaches the page

• Render. The block renders its inner blocks during the normal block render, so anything they enqueue (a form plugin’s script, an embed) is enqueued in time. The render callback then returns an empty string — nothing is printed in place — and hands the rendered content to the registry.
• Register. Method_Modals::register() normalises the arguments against default_options(), runs the method/modal_args filter, sanitises the ID, and keeps the first registration for an ID (a synced pattern used twice registers the same modal twice; the second fires method/modal_duplicate and is dropped). The content goes through method/modal_content, where the usual the_content filters — wptexturize, do_shortcode, wp_filter_content_tags and the rest — are attached at core’s priorities, because hoisted content never reaches them otherwise.
• Print. On wp_footer at priority 5 the registry prints every modal with get_markup(), and again at priority 19 for anything registered by other footer callbacks; after that it is closed and a late method_register_modal() raises _doing_it_wrong(). The view script is enqueued only when at least one modal registered.
• Assets. Since WordPress 6.9, assets enqueued by a block that prints nothing are dequeued again. The block opts out through enqueue_empty_block_content_assets, and the registry also snapshots the script, style and script-module queues around each modal’s render (snapshot_assets() / assets_since_snapshot()) and re-enqueues the difference once the page has rendered. On WordPress 6.5–6.8 the script-module queue is read through a bound closure instead of get_queue(), which only exists from 6.9.
• Open. One delegated click handler opens the .method-modal a link points at — #id or a full URL to the current page, compared by host and path. Links are marked on load with data-method-modal-trigger, aria-haspopup="dialog", aria-controls and role="button"; a URL whose hash is a modal’s ID opens it on load; a link inside one modal closes it before opening the next; media is paused on close and Swipers updated on open. window.methodModals.open( idOrElement, trigger ) and .decorate( root ) cover content added after load.

Registering a modal from PHP

Any source can register a modal while the page renders, no later than wp_footer priority 18. Render the content first — in the callback, not in a footer hook — so its asset enqueues happen in time. The return value is the ID the modal can be opened with (also when that ID was already taken), or false.

add_action( 'method/register_modals', function ( Method_Modals $registry ) {
    $registry->push_context( array( 'scope' => 'site', 'source' => 'child-theme' ) );

    method_register_modal( array(
        'id'      => 'newsletter',
        'title'   => __( 'Join the newsletter', 'cortlandt' ),
        'content' => do_blocks( get_option( 'cortlandt_newsletter_blocks' ) ),
        'options' => array(
            'size'             => 'lg',          // sm | default | lg | xl | fullscreen
            'fullscreen_below' => 'mobile',      // '' | mobile | tablet
            'centered'         => true,
            'close_icon'       => 'cross',       // a slug from method_theme_icons
        ),
    ) );

    $registry->pop_context();
} );

// Anywhere in content: <a href="#newsletter">Subscribe</a>

Sizes come from method_get_modal_sizes() — sm 300px, default 500px, lg 800px, xl 1140px, fullscreen — each a label, a .modal-dialog class and a width set as --method-modal-width. default and fullscreen are expected to stay. “Full screen below” a tier adds one shared media-query rule per tier, built from method_get_block_breakpoints().

Hooks

The block and the editor

• The block is a hybrid dynamic block like the Container: save stores only the inner-blocks wrapper (.method-modal-inner-blocks); everything else is attributes — modalId, customId, title, hideTitle, titleTag, size, fullscreenBelow, centered, scrollable, staticBackdrop, closeIcon, colors, and responsiveSettings.
• modalId (modal- plus six random characters) is generated the first time the block is edited and never changes; a duplicated or pasted modal takes a fresh one, through the usePersistentId hook. customId overrides it, sanitised by sanitizeModalId() in lib/blocks/utils/modalId.js, the editor twin of the PHP function.
• The Modals panel in the document sidebar — Method’s first editor plugin, method-modal-manager, loaded as the block’s second editorScript — lists every modal in the document with title, ID and size, warns about shared IDs, selects a block for editing, copies its link, and appends a new modal. Other sources add their own lists through the method.modalManager.sections JavaScript filter.
• Not printed in feeds or REST responses; a block hidden with block visibility does not register.

Styles

Method ships Bootstrap 5.3’s structural modal rules in global.scss, every one wrapped in :where() so they carry no specificity and a child theme’s own .modal rules win regardless of load order. .method-modal adds the fade, the width (--method-modal-width, capped to the viewport), the full-screen size, the close button (button.method-modal-close, 44×44px, rather than Bootstrap’s .btn-close) and margin resets for the first and last inner block. The backdrop fades only while a Method modal is open (html.method-modal-active). Transitions respect prefers-reduced-motion.

Changelog