Finds a script handle for the selected block metadata field.
Description
Detects when a path to a file was provided and optionally finds a corresponding asset file with details necessary to register the script. The handle is taken from the asset file when it provides one, and is otherwise generated automatically. It returns the unprocessed script handle when a handle rather than a path was given.
Parameters
$metadataarrayrequired- Block metadata.
$field_namestringrequired- Field name to pick from metadata.
$indexintoptional- Index of the script to register when multiple items passed.
Default 0.
Source
function register_block_script_handle( $metadata, $field_name, $index = 0 ) {
if ( empty( $metadata[ $field_name ] ) ) {
return false;
}
$script_handle_or_path = $metadata[ $field_name ];
if ( is_array( $script_handle_or_path ) ) {
if ( empty( $script_handle_or_path[ $index ] ) ) {
return false;
}
$script_handle_or_path = $script_handle_or_path[ $index ];
}
$script_path = remove_block_asset_path_prefix( $script_handle_or_path );
if ( $script_handle_or_path === $script_path ) {
return $script_handle_or_path;
}
$path = dirname( $metadata['file'] );
$script_asset_raw_path = $path . '/' . substr_replace( $script_path, '.asset.php', - strlen( '.js' ) );
$script_asset_path = wp_normalize_path(
realpath( $script_asset_raw_path )
);
// Asset file for blocks is optional. See https://core.trac.wordpress.org/ticket/60460.
/** @var array{ handle?: non-falsy-string, dependencies?: list<non-falsy-string>, version?: string|false|null, ... } $script_asset */
$script_asset = ! empty( $script_asset_path ) ? require $script_asset_path : array();
$script_handle = $script_asset['handle'] ??
generate_block_asset_handle( $metadata['name'], $field_name, $index );
if ( wp_script_is( $script_handle, 'registered' ) ) {
return $script_handle;
}
$script_path_norm = wp_normalize_path( realpath( $path . '/' . $script_path ) );
$script_uri = get_block_asset_url( $script_path_norm );
$script_dependencies = $script_asset['dependencies'] ?? array();
$block_version = $metadata['version'] ?? false;
$script_version = $script_asset['version'] ?? $block_version;
$script_args = array();
if ( 'viewScript' === $field_name && $script_uri ) {
$script_args['strategy'] = 'defer';
}
$result = wp_register_script(
$script_handle,
$script_uri,
$script_dependencies,
$script_version,
$script_args
);
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;
}
Note that, because this function uses `plugins_url` internally, registering a script via the block.json metadata file only works for plugins, not themes.