Editor: add new parameter to hook when enqueuing block assets

[jeherve]

This trac ticket is part 1 of a larger discussion spanning multiple issues, about the potential issues plugin authors may face when developing blocks that rely on the @wordpress/editor dependency.

• This trac ticket is part 1: it suggests an option to make conditional asset enqueuing easier in the different block editors.
• In part 2, I would like to suggest an option to declare support for specific editors at block registration. Discussion about this is happening in ​this Gutenberg issue.

---

When enqueuing assets for a block registered in a plugin, one can rely on block.json, or hook into the enqueue_block_editor_assets hook to enqueue necessary scripts and styles in the block editor.

This works well, but offers some challenges with some specific blocks. For instance, your block may rely on the @wordpress/editor dependency to handle some of its functionality. That dependency is available in the post editor, but cannot be used in the widget editor or the site editor. See #53569 and ​33203-gutenberg for more information on this topic.

In this scenario, one may want to enqueue the block's scripts (and its wp-editor dependency) only in the post editor.

The enqueue_block_editor_assets hook doesn't currently offer this flexibility. As a result, folks wanting to do that must add a check before they enqueue. Something like this for someone not wanting to load in the widget editor for example.

<?php
function enqueue_block_assets() {
    global $pagenow;

    // Return early when viewing the customizer or widgets screen.
    if ( is_customize_preview() || 'widgets.php' === $pagenow ) {
        return;
    }

    wp_enqueue_script( 'here' );
}

I was consequently wondering if it were possible to extend the enqueue_block_editor_assets hook a bit, so it could be used just like the admin_enqueue_scripts hook today, so we could do something like this:

<?php
function enqueue_block_assets( $hook ) {
    // We only need our script in the post editor
    // not in the widget editor or the site editor.
    if ( ! in_array( $hook, array( 'post.php', 'post-new.php' ), true ) ) {
        return;
    }

    wp_enqueue_script( 'here' );
}

This change would allow one to use the enqueue_block_editor_assets hook just like we use the admin_enqueue_scripts hook today: we can easily add conditionals and decide in which editor (post, widget, site) we want a block asset to be enqueued.

More details in the Trac ticket: https://core.trac.wordpress.org/ticket/57421

[jeherve]

@dmsnell had some notes about this proposal in ​the related Gutenberg issue. I've pasted his comments below and tried to address them.

it's a bit dizzying following the conversation around the various PRs and tickets. I don't think this is anyone's fault, but it would be helpful to have a header on all the related tickets listing each related ticket/issue/PR, a link to it, a summary of what role it plays, and an indication for where the canonical discussion should take part (e.g. "Please discuss this change at {link} to avoid duplicating in all these places.")

Sorry about that! I do not have the option to edit the description of my Trac ticket here, but if someone does, I would recommend adding the following:

---

This trac ticket is part 1 of a larger discussion spanning multiple issues, about the potential issues plugin authors may face when developing blocks that rely on the @wordpress/editor dependency.

• This trac ticket is part 1: it suggests an option to make conditional asset enqueuing easier in the different block editors.
• In part 2, I would like to suggest an option to declare support for specific editors at block registration. Discussion about this is happening in ​this Gutenberg issue.

---

the admin_enqueue_scripts hook uses the $hook_suffix name for its parameter but it looks like we're using $hook in this proposal. Is there a reason to use two names for what I think is intended to be the same value and serve the same purpose?

My proposal also suggests using $hook_suffix (see the actual patch in ​the attached PR. I realize now my sample code snippet in the trac description above may have been a bit misleading, sorry about that.

doesn't seem like this is a very risky change, though if we're only exposing a global parameter, what is the value of the abstraction over the counter-example, where a function implementing the enqueue_block_assets hook itself pulls in the global?

It does feel a bit cleaner to me, as it relies on the data passed with the hook instead of relying on the plugin authors doing their own implementation. It also feels consistent with how plugin authors are used to enqueue assets in wp-admin today, via admin_enqueue_scripts.

if we're talking about adding parameters to the hook, do we reasonably predict any others might come in the future? if so, does this one warrant being in the first/front argument position? would an associative array or "option bag" argument better serve it?

That's a good question. I've only added this parameter because in my mind the enqueue_block_editor_assets hook is very similar to the admin_enqueue_scripts hook: it is used to enqueue assets inside wp-admin. It feels natural to have the 2 hooks taking the same parameter.

[ironprogrammer]

Thanks for the report, @jeherve! I've added the requested text to the top of the ticket description, and marked this as an enhancement for clarity.