register_block_script_handle( array $metadata, string $field_name, int $index ): string|false
Finds a script handle for the selected block metadata field. It detects when a path to file was provided and finds a corresponding asset file with details necessary to register the script under automatically generated handle name. It returns unprocessed script handle otherwise.
Parameters
-
$metadata
array Required -
Block metadata.
-
$field_name
string Required -
Field name to pick from metadata.
-
$index
int Optional -
Index of the script to register when multiple items passed.
Default 0.
Return
string|false Script handle provided directly or created through script's registration, or false on failure.
Source
File: wp-includes/blocks.php
.
View all references
function register_block_script_handle( $metadata, $field_name, $index = 0 ) {
if ( empty( $metadata[ $field_name ] ) ) {
return false;
}
$script_handle = $metadata[ $field_name ];
if ( is_array( $script_handle ) ) {
if ( empty( $script_handle[ $index ] ) ) {
return false;
}
$script_handle = $script_handle[ $index ];
}
$script_path = remove_block_asset_path_prefix( $script_handle );
if ( $script_handle === $script_path ) {
return $script_handle;
}
$script_asset_raw_path = dirname( $metadata['file'] ) . '/' . substr_replace( $script_path, '.asset.php', - strlen( '.js' ) );
$script_handle = generate_block_asset_handle( $metadata['name'], $field_name, $index );
$script_asset_path = wp_normalize_path(
realpath( $script_asset_raw_path )
);
if ( empty( $script_asset_path ) ) {
_doing_it_wrong(
__FUNCTION__,
sprintf(
/* translators: 1: Asset file location, 2: Field name, 3: Block name. */
__( 'The asset file (%1$s) for the "%2$s" defined in "%3$s" block definition is missing.' ),
$script_asset_raw_path,
$field_name,
$metadata['name']
),
'5.5.0'
);
return false;
}
// Path needs to be normalized to work in Windows env.
static $wpinc_path_norm = '';
if ( ! $wpinc_path_norm ) {
$wpinc_path_norm = wp_normalize_path( realpath( ABSPATH . WPINC ) );
}
// Cache $template_path_norm and $stylesheet_path_norm to avoid unnecessary additional calls.
static $template_path_norm = '';
static $stylesheet_path_norm = '';
if ( ! $template_path_norm || ! $stylesheet_path_norm ) {
$template_path_norm = wp_normalize_path( get_template_directory() );
$stylesheet_path_norm = wp_normalize_path( get_stylesheet_directory() );
}
$script_path_norm = wp_normalize_path( realpath( dirname( $metadata['file'] ) . '/' . $script_path ) );
$is_core_block = isset( $metadata['file'] ) && str_starts_with( $metadata['file'], $wpinc_path_norm );
/*
* Determine if the block script was registered in a theme, by checking if the script path starts with either
* the parent (template) or child (stylesheet) directory path.
*/
$is_parent_theme_block = str_starts_with( $script_path_norm, $template_path_norm );
$is_child_theme_block = str_starts_with( $script_path_norm, $stylesheet_path_norm );
$is_theme_block = ( $is_parent_theme_block || $is_child_theme_block );
$script_uri = plugins_url( $script_path, $metadata['file'] );
if ( $is_core_block ) {
$script_uri = includes_url( str_replace( $wpinc_path_norm, '', $script_path_norm ) );
} elseif ( $is_theme_block ) {
// Get the script path deterministically based on whether or not it was registered in a parent or child theme.
$script_uri = $is_parent_theme_block
? get_theme_file_uri( str_replace( $template_path_norm, '', $script_path_norm ) )
: get_theme_file_uri( str_replace( $stylesheet_path_norm, '', $script_path_norm ) );
}
$script_asset = require $script_asset_path;
$script_dependencies = isset( $script_asset['dependencies'] ) ? $script_asset['dependencies'] : array();
$result = wp_register_script(
$script_handle,
$script_uri,
$script_dependencies,
isset( $script_asset['version'] ) ? $script_asset['version'] : false
);
if ( ! $result ) {
return false;
}
if ( ! empty( $metadata['textdomain'] ) && in_array( 'wp-i18n', $script_dependencies, true ) ) {
wp_set_script_translations( $script_handle, $metadata['textdomain'] );
}
return $script_handle;
}
Changelog
Version | Description |
---|---|
6.1.0 | Added $index parameter. |
5.5.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
Note that, because this function uses `plugins_url` internally, registering a script via the block.json metadata file only works for plugins, not themes.
Top ↑
Feedback
Three years later my comment here is no longer accurate, but if you’re developing locally with a symlinked theme folder you still need to jump through some hoops. — By Cory Hughart —