Add new How-to Guide for enqueueing assets in the Editor.

[ndiego]

What?

This PR adds a new How-to Guide in the Block Editor Handbook that details the best practices for enqueueing assets in the Editor.

Why?

Numerous dev notes, GitHub issues, and scattered articles discuss enqueueing assets in the Editor. This PR aims to house all that knowledge in one place so it can be easily referenced.

Note that this PR should be considered an initial iteration. There are many nuances and edge cases regarding enqueueing assets in the Editor. There are also a handful of open issues related to this topic (ex. #53590). Future updates will undoubtedly be needed.

[fabiankaegy]

Thanks for compiling all this! :)

[github-actions]

Flaky tests detected in 77eef3f.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/5913306149
📝 Reported issues:

• [Flaky Test] should partially select with shift + click (@webkit) #53524 in /test/e2e/specs/editor/various/multi-block-selection.spec.js

[justintadlock]

Great job simplifying and clarifying this, @ndiego!

[juanmaguitar]

Great job @ndiego! I think this page is a much-needed reference for this topic.

As a suggestion, I would group the sections describing each scenario, under a parent group called "Scenarios for enqueuing " (or similar), resulting in a structure as follows:

• The Editor versus Editor content
• Scenarios for enqueing
  • Editor scripts and styles
  • Editor content scripts and styles
  • Block scripts and styles
  • Theme scripts and styles
• Backward compatibility and known issues

Some practical examples could also be added to https://github.com/WordPress/gutenberg-examples and referenced from this page but that would be out of the scope of this PR

[ndiego]

As a suggestion, I would group the sections describing each scenario, under a parent group called "Scenarios for enqueuing " (or similar), resulting in a structure as follows:

Thanks @juanmaguitar, I have updated the heading structure accordingly.

Some practical examples could also be added to https://github.com/WordPress/gutenberg-examples and referenced from this page but that would be out of the scope of this PR

This is a great idea. Definitely, something to add in the next iteration.

[ellatrix]

Worth noting that enqueuing assets to work for iframing should also work if the editor is not iframed, just not vice versa (things working without iframe will not necessarily work with the iframe).

[ndiego]

Thanks @ellatrix. I will add this note to the doc later this week. I have a few more minor tweaks to make.

[ellatrix]

I added a link to your page in https://make.wordpress.org/core/2023/07/18/miscellaneous-editor-changes-in-wordpress-6-3/#post-editor-iframed.

[chimok]

I did always load SVG sprites with AJAX, this doesn't work anymore with iframed editor and i'm wondering if there's a better way to use SVG fragments inside Gutenberg? Sure, I could use some conditions and use the tricks mention in the new howto.

Another problem is any script loaded with enqueue_block_assets get loaded twice, inside admin page and inside iframe. For now I will use wp_enqueue_scripts for that purpose, so it will only get loaded on frontend. But then no icons inside Gutenberg.
I believe it takes years until all plugins are compatible with this behavior.

This was the code:

function loadIcons() {
    fetch( '/app/themes/custom/static/icons.svg' )
        .then( ( response ) => response.text() )
        .then( ( result ) =>
            document.body.insertAdjacentHTML( 'afterbegin', result )
        );
}