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.

Top ↑

Return

string|false Script handle provided directly or created through script's registration, or false on failure.


Top ↑

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 ) );
	}

	$theme_path_norm  = wp_normalize_path( get_theme_file_path() );
	$script_path_norm = wp_normalize_path( realpath( dirname( $metadata['file'] ) . '/' . $script_path ) );

	$is_core_block  = isset( $metadata['file'] ) && 0 === strpos( $metadata['file'], $wpinc_path_norm );
	$is_theme_block = 0 === strpos( $script_path_norm, $theme_path_norm );

	$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 ) {
		$script_uri = get_theme_file_uri( str_replace( $theme_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;
}


Top ↑

Changelog

Changelog
Version Description
6.1.0 Added $index parameter.
5.5.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    Contributed by Cory Hughart

    Note that, because this function uses `plugins_url` internally, registering a script via the block.json metadata file only works for plugins, not themes.

You must log in before being able to contribute a note or feedback.