both editor and front-end.
*
* Call `add_action` on any hook before 'wp_enqueue_scripts'.
*
* In the function call you supply, simply use `wp_enqueue_script` and
* `wp_enqueue_style` to add your functionality to the Gutenberg editor.
*
* @since 5.0.0
*/
do_action( 'enqueue_block_assets' );
}
/**
* Applies a filter to the list of style nodes that comes from WP_Theme_JSON::get_style_nodes().
*
* This particular filter removes all of the blocks from the array.
*
* We want WP_Theme_JSON to be ignorant of the implementation details of how the CSS is being used.
* This filter allows us to modify the output of WP_Theme_JSON depending on whether or not we are
* loading separate assets, without making the class aware of that detail.
*
* @since 6.1.0
*
* @param array $nodes The nodes to filter.
* @return array A filtered array of style nodes.
*/
function wp_filter_out_block_nodes( $nodes ) {
return array_filter(
$nodes,
static function ( $node ) {
return ! in_array( 'blocks', $node['path'], true );
},
ARRAY_FILTER_USE_BOTH
);
}
/**
* Enqueues the global styles defined via theme.json.
*
* @since 5.8.0
*/
function wp_enqueue_global_styles() {
$separate_assets = wp_should_load_separate_core_block_assets();
$is_block_theme = wp_is_block_theme();
$is_classic_theme = ! $is_block_theme;
/*
* Global styles should be printed in the head when loading all styles combined.
* The footer should only be used to print global styles for classic themes with separate core assets enabled.
*
* See https://core.trac.wordpress.org/ticket/53494.
*/
if (
( $is_block_theme && doing_action( 'wp_footer' ) ) ||
( $is_classic_theme && doing_action( 'wp_footer' ) && ! $separate_assets ) ||
( $is_classic_theme && doing_action( 'wp_enqueue_scripts' ) && $separate_assets )
) {
return;
}
/*
* If loading the CSS for each block separately, then load the theme.json CSS conditionally.
* This removes the CSS from the global-styles stylesheet and adds it to the inline CSS for each block.
* This filter must be registered before calling wp_get_global_stylesheet();
*/
add_filter( 'wp_theme_json_get_style_nodes', 'wp_filter_out_block_nodes' );
$stylesheet = wp_get_global_stylesheet();
if ( empty( $stylesheet ) ) {
return;
}
wp_register_style( 'global-styles', false );
wp_add_inline_style( 'global-styles', $stylesheet );
wp_enqueue_style( 'global-styles' );
// Add each block as an inline css.
wp_add_global_styles_for_blocks();
}
/**
* Enqueues the global styles custom css defined via theme.json.
*
* @since 6.2.0
*/
function wp_enqueue_global_styles_custom_css() {
if ( ! wp_is_block_theme() ) {
return;
}
// Don't enqueue Customizer's custom CSS separately.
remove_action( 'wp_head', 'wp_custom_css_cb', 101 );
$custom_css = wp_get_custom_css();
$custom_css .= wp_get_global_styles_custom_css();
if ( ! empty( $custom_css ) ) {
wp_add_inline_style( 'global-styles', $custom_css );
}
}
/**
* Checks if the editor scripts and styles for all registered block types
* should be enqueued on the current screen.
*
* @since 5.6.0
*
* @global WP_Screen $current_screen WordPress current screen object.
*
* @return bool Whether scripts and styles should be enqueued.
*/
function wp_should_load_block_editor_scripts_and_styles() {
global $current_screen;
$is_block_editor_screen = ( $current_screen instanceof WP_Screen ) && $current_screen->is_block_editor();
/**
* Filters the flag that decides whether or not block editor scripts and styles
* are going to be enqueued on the current screen.
*
* @since 5.6.0
*
* @param bool $is_block_editor_screen Current value of the flag.
*/
return apply_filters( 'should_load_block_editor_scripts_and_styles', $is_block_editor_screen );
}
/**
* Checks whether separate styles should be loaded for core blocks on-render.
*
* When this function returns true, other functions ensure that core blocks
* only load their assets on-render, and each block loads its own, individual
* assets. Third-party blocks only load their assets when rendered.
*
* When this function returns false, all core block assets are loaded regardless
* of whether they are rendered in a page or not, because they are all part of
* the `block-library/style.css` file. Assets for third-party blocks are always
* enqueued regardless of whether they are rendered or not.
*
* This only affects front end and not the block editor screens.
*
* @see wp_enqueue_registered_block_scripts_and_styles()
* @see register_block_style_handle()
*
* @since 5.8.0
*
* @return bool Whether separate assets will be loaded.
*/
function wp_should_load_separate_core_block_assets() {
if ( is_admin() || is_feed() || wp_is_rest_endpoint() ) {
return false;
}
/**
* Filters whether block styles should be loaded separately.
*
* Returning false loads all core block assets, regardless of whether they are rendered
* in a page or not. Returning true loads core block assets only when they are rendered.
*
* @since 5.8.0
*
* @param bool $load_separate_assets Whether separate assets will be loaded.
* Default false (all block assets are loaded, even when not used).
*/
return apply_filters( 'should_load_separate_core_block_assets', false );
}
/**
* Enqueues registered block scripts and styles, depending on current rendered
* context (only enqueuing editor scripts while in context of the editor).
*
* @since 5.0.0
*
* @global WP_Screen $current_screen WordPress current screen object.
*/
function wp_enqueue_registered_block_scripts_and_styles() {
global $current_screen;
if ( wp_should_load_separate_core_block_assets() ) {
return;
}
$load_editor_scripts_and_styles = is_admin() && wp_should_load_block_editor_scripts_and_styles();
$block_registry = WP_Block_Type_Registry::get_instance();
foreach ( $block_registry->get_all_registered() as $block_name => $block_type ) {
// Front-end and editor styles.
foreach ( $block_type->style_handles as $style_handle ) {
wp_enqueue_style( $style_handle );
}
// Front-end and editor scripts.
foreach ( $block_type->script_handles as $script_handle ) {
wp_enqueue_script( $script_handle );
}
if ( $load_editor_scripts_and_styles ) {
// Editor styles.
foreach ( $block_type->editor_style_handles as $editor_style_handle ) {
wp_enqueue_style( $editor_style_handle );
}
// Editor scripts.
foreach ( $block_type->editor_script_handles as $editor_script_handle ) {
wp_enqueue_script( $editor_script_handle );
}
}
}
}
/**
* Function responsible for enqueuing the styles required for block styles functionality on the editor and on the frontend.
*
* @since 5.3.0
*
* @global WP_Styles $wp_styles
*/
function enqueue_block_styles_assets() {
global $wp_styles;
$block_styles = WP_Block_Styles_Registry::get_instance()->get_all_registered();
foreach ( $block_styles as $block_name => $styles ) {
foreach ( $styles as $style_properties ) {
if ( isset( $style_properties['style_handle'] ) ) {
// If the site loads separate styles per-block, enqueue the stylesheet on render.
if ( wp_should_load_separate_core_block_assets() ) {
add_filter(
'render_block',
static function ( $html, $block ) use ( $block_name, $style_properties ) {
if ( $block['blockName'] === $block_name ) {
wp_enqueue_style( $style_properties['style_handle'] );
}
return $html;
},
10,
2
);
} else {
wp_enqueue_style( $style_properties['style_handle'] );
}
}
if ( isset( $style_properties['inline_style'] ) ) {
// Default to "wp-block-library".
$handle = 'wp-block-library';
// If the site loads separate styles per-block, check if the block has a stylesheet registered.
if ( wp_should_load_separate_core_block_assets() ) {
$block_stylesheet_handle = generate_block_asset_handle( $block_name, 'style' );
if ( isset( $wp_styles->registered[ $block_stylesheet_handle ] ) ) {
$handle = $block_stylesheet_handle;
}
}
// Add inline styles to the calculated handle.
wp_add_inline_style( $handle, $style_properties['inline_style'] );
}
}
}
}
/**
* Function responsible for enqueuing the assets required for block styles functionality on the editor.
*
* @since 5.3.0
*/
function enqueue_editor_block_styles_assets() {
$block_styles = WP_Block_Styles_Registry::get_instance()->get_all_registered();
$register_script_lines = array( '( function() {' );
foreach ( $block_styles as $block_name => $styles ) {
foreach ( $styles as $style_properties ) {
$block_style = array(
'name' => $style_properties['name'],
'label' => $style_properties['label'],
);
if ( isset( $style_properties['is_default'] ) ) {
$block_style['isDefault'] = $style_properties['is_default'];
}
$register_script_lines[] = sprintf(
' wp.blocks.registerBlockStyle( \'%s\', %s );',
$block_name,
wp_json_encode( $block_style )
);
}
}
$register_script_lines[] = '} )();';
$inline_script = implode( "\n", $register_script_lines );
wp_register_script( 'wp-block-styles', false, array( 'wp-blocks' ), true, array( 'in_footer' => true ) );
wp_add_inline_script( 'wp-block-styles', $inline_script );
wp_enqueue_script( 'wp-block-styles' );
}
/**
* Enqueues the assets required for the block directory within the block editor.
*
* @since 5.5.0
*/
function wp_enqueue_editor_block_directory_assets() {
wp_enqueue_script( 'wp-block-directory' );
wp_enqueue_style( 'wp-block-directory' );
}
/**
* Enqueues the assets required for the format library within the block editor.
*
* @since 5.8.0
*/
function wp_enqueue_editor_format_library_assets() {
wp_enqueue_script( 'wp-format-library' );
wp_enqueue_style( 'wp-format-library' );
}
/**
* Sanitizes an attributes array into an attributes string to be placed inside a `\n", wp_sanitize_script_attributes( $attributes ) );
}
/**
* Prints formatted `
*
* In an HTML document this would print "…" to the console,
* but in an XHTML document it would print "…" to the console.
*
*
*
* In an HTML document this would print "An image is
in HTML",
* but it's an invalid XHTML document because it interprets the `
`
* as an empty tag missing its closing `/`.
*
* @see https://www.w3.org/TR/xhtml1/#h-4.8
*/
if (
! $is_html5 &&
(
! isset( $attributes['type'] ) ||
'module' === $attributes['type'] ||
str_contains( $attributes['type'], 'javascript' ) ||
str_contains( $attributes['type'], 'ecmascript' ) ||
str_contains( $attributes['type'], 'jscript' ) ||
str_contains( $attributes['type'], 'livescript' )
)
) {
/*
* If the string `]]>` exists within the JavaScript it would break
* out of any wrapping CDATA section added here, so to start, it's
* necessary to escape that sequence which requires splitting the
* content into two CDATA sections wherever it's found.
*
* Note: it's only necessary to escape the closing `]]>` because
* an additional `', ']]]]>', $data );
// Wrap the entire escaped script inside a CDATA section.
$data = sprintf( "/* */", $data );
}
$data = "\n" . trim( $data, "\n\r " ) . "\n";
/**
* Filters attributes to be added to a script tag.
*
* @since 5.7.0
*
* @param array $attributes Key-value pairs representing `\n", wp_sanitize_script_attributes( $attributes ), $data );
}
/**
* Prints an inline script tag.
*
* It is possible to inject attributes in the `" from
* around an inline script after trimming whitespace. Typically this
* is used in conjunction with output buffering, where `ob_get_clean()`
* is passed as the `$contents` argument.
*
* Example:
*
* // Strips exact literal empty SCRIPT tags.
* $js = ';
* 'sayHello();' === wp_remove_surrounding_empty_script_tags( $js );
*
* // Otherwise if anything is different it warns in the JS console.
* $js = '';
* 'console.error( ... )' === wp_remove_surrounding_empty_script_tags( $js );
*
* @since 6.4.0
* @access private
*
* @see wp_print_inline_script_tag()
* @see wp_get_inline_script_tag()
*
* @param string $contents Script body with manually created SCRIPT tag literals.
* @return string Script body without surrounding script tag literals, or
* original contents if both exact literals aren't present.
*/
function wp_remove_surrounding_empty_script_tags( $contents ) {
$contents = trim( $contents );
$opener = '';
if (
strlen( $contents ) > strlen( $opener ) + strlen( $closer ) &&
strtoupper( substr( $contents, 0, strlen( $opener ) ) ) === $opener &&
strtoupper( substr( $contents, -strlen( $closer ) ) ) === $closer
) {
return substr( $contents, strlen( $opener ), -strlen( $closer ) );
} else {
$error_message = __( 'Expected string to start with script tag (without attributes) and end with script tag, with optional whitespace.' );
_doing_it_wrong( __FUNCTION__, $error_message, '6.4' );
return sprintf(
'console.error(%s)',
wp_json_encode(
sprintf(
/* translators: %s: wp_remove_surrounding_empty_script_tags() */
__( 'Function %s used incorrectly in PHP.' ),
'wp_remove_surrounding_empty_script_tags()'
) . ' ' . $error_message
)
);
}
}