gutenberg / lib / experimental / script-modules.php

script-modules.php in Gutenberg 18.7.1, at lib/experimental/script-modules.php

293 lines 11.9 KB

Raw Download Zip

1	<?php
2	/**
3	* Add module fields from block metadata to WP_Block_Type settings.
4	*
5	* This filter allows us to register modules from block metadata and attach additional fields to
6	* WP_Block_Type instances.
7	*
8	* @param array $settings Array of determined settings for registering a block type.
9	* @param array $metadata Metadata provided for registering a block type.
10	*/
11	function gutenberg_filter_block_type_metadata_settings_register_view_module( $settings, $metadata = null ) {
12	$module_fields = array(
13	// @todo remove viewModule support in Gutenberg >= 17.8 (replaced by viewScriptModule).
14	'viewModule' => 'view_script_module_ids',
15	);
16	foreach ( $module_fields as $metadata_field_name => $settings_field_name ) {
17	if ( ! empty( $settings[ $metadata_field_name ] ) ) {
18	$metadata[ $metadata_field_name ] = $settings[ $metadata_field_name ];
19	}
20	if ( ! empty( $metadata[ $metadata_field_name ] ) ) {
21	$modules = $metadata[ $metadata_field_name ];
22	$processed_modules = array();
23	if ( is_array( $modules ) ) {
24	for ( $index = 0; $index < count( $modules ); $index++ ) {
25	$processed_modules[] = gutenberg_register_block_module_id(
26	$metadata,
27	$metadata_field_name,
28	$index
29	);
30	}
31	} else {
32	$processed_modules[] = gutenberg_register_block_module_id(
33	$metadata,
34	$metadata_field_name
35	);
36	}
37	$settings[ $settings_field_name ] = $processed_modules;
38	}
39	}
40
41	return $settings;
42	}
43
44	add_filter( 'block_type_metadata_settings', 'gutenberg_filter_block_type_metadata_settings_register_view_module', 20, 2 );
45
46	/**
47	* Finds a module ID for the selected block metadata field. It detects
48	* when a path to file was provided and finds a corresponding asset file
49	* with details necessary to register the module under an automatically
50	* generated module ID.
51	*
52	* This is analogous to the `register_block_script_handle` in WordPress Core.
53	*
54	* @param array $metadata Block metadata.
55	* @param string $field_name Field name to pick from metadata.
56	* @param int $index Optional. Index of the script to register when multiple items passed.
57	* Default 0.
58	* @return string Module ID.
59	*/
60	function gutenberg_register_block_module_id( $metadata, $field_name, $index = 0 ) {
61	if ( empty( $metadata[ $field_name ] ) ) {
62	return false;
63	}
64
65	$module_id = $metadata[ $field_name ];
66	if ( is_array( $module_id ) ) {
67	if ( empty( $module_id[ $index ] ) ) {
68	return false;
69	}
70	$module_id = $module_id[ $index ];
71	}
72
73	$module_path = remove_block_asset_path_prefix( $module_id );
74	if ( $module_id === $module_path ) {
75	return $module_id;
76	}
77
78	$path = dirname( $metadata['file'] );
79	$module_asset_raw_path = $path . '/' . substr_replace( $module_path, '.asset.php', - strlen( '.js' ) );
80	$module_id = gutenberg_generate_block_asset_module_id( $metadata['name'], $field_name, $index );
81	$module_asset_path = wp_normalize_path( realpath( $module_asset_raw_path ) );
82
83	$module_path_norm = wp_normalize_path( realpath( $path . '/' . $module_path ) );
84	$module_uri = get_block_asset_url( $module_path_norm );
85	$module_asset = ! empty( $module_asset_path ) ? require $module_asset_path : array();
86	$module_dependencies = isset( $module_asset['dependencies'] ) ? $module_asset['dependencies'] : array();
87
88	wp_register_script_module(
89	$module_id,
90	$module_uri,
91	$module_dependencies,
92	isset( $module_asset['version'] ) ? $module_asset['version'] : false
93	);
94
95	return $module_id;
96	}
97
98	/**
99	* Generates the module ID for an asset based on the name of the block
100	* and the field name provided.
101	*
102	* This is analogous to the `generate_block_asset_handle` in WordPress Core.
103	*
104	* @param string $block_name Name of the block.
105	* @param string $field_name Name of the metadata field.
106	* @param int $index Optional. Index of the asset when multiple items passed.
107	* Default 0.
108	* @return string Generated module ID for the block's field.
109	*/
110	function gutenberg_generate_block_asset_module_id( $block_name, $field_name, $index = 0 ) {
111	if ( str_starts_with( $block_name, 'core/' ) ) {
112	$asset_handle = str_replace( 'core/', 'wp-block-', $block_name );
113	if ( str_starts_with( $field_name, 'editor' ) ) {
114	$asset_handle .= '-editor';
115	}
116	if ( str_starts_with( $field_name, 'view' ) ) {
117	$asset_handle .= '-view';
118	}
119	if ( $index > 0 ) {
120	$asset_handle .= '-' . ( $index + 1 );
121	}
122	return $asset_handle;
123	}
124
125	$field_mappings = array(
126	// @todo remove viewModule support in Gutenberg >= 17.8 (replaced by viewScriptModule).
127	'viewModule' => 'view-script-module',
128	'viewScriptModule' => 'view-script-module',
129	);
130	$asset_handle = str_replace( '/', '-', $block_name ) .
131	'-' . $field_mappings[ $field_name ];
132	if ( $index > 0 ) {
133	$asset_handle .= '-' . ( $index + 1 );
134	}
135	return $asset_handle;
136	}
137
138	/**
139	* Registers a REST field for block types to provide view module IDs.
140	*
141	* Adds the `view_script_module_ids` and `view_module_ids` (deprecated) field to block type objects in the REST API, which
142	* lists the script module IDs for any script modules associated with the
143	* block's viewScriptModule key.
144	*/
145	function gutenberg_register_view_module_ids_rest_field() {
146	// @todo remove view_module_ids support in Gutenberg >= 17.8 (replaced by view_script_module_ids).
147	register_rest_field(
148	'block-type',
149	'view_module_ids',
150	array(
151	'get_callback' => function ( $item ) {
152	$block_type = WP_Block_Type_Registry::get_instance()->get_registered( $item['name'] );
153	if ( isset( $block_type->view_script_module_ids ) ) {
154	return $block_type->view_script_module_ids;
155	}
156	return array();
157	},
158	)
159	);
160	}
161
162	add_action( 'rest_api_init', 'gutenberg_register_view_module_ids_rest_field' );
163
164	/**
165	* Registers the module if no module with that module identifier has already
166	* been registered.
167	*
168	* @param string $module_identifier The identifier of the module. Should be unique. It will be used in the final import map.
169	* @param string $src Full URL of the module, or path of the script relative to the WordPress root directory.
170	* @param array $dependencies Optional. An array of module identifiers of the dependencies of this module. The dependencies can be strings or arrays. If they are arrays, they need an `id` key with the module identifier, and can contain an `import` key with either `static` or `dynamic`. By default, dependencies that don't contain an import are considered static.
171	* @param string\|false\|null $version Optional. String specifying module version number. Defaults to false. It is added to the URL as a query string for cache busting purposes. If $version is set to false, the version number is the currently installed WordPress version. If $version is set to null, no version is added.
172	* @deprecated 17.6.0 gutenberg_register_module is deprecated. Please use wp_register_script_module instead.
173	*/
174	function gutenberg_register_module( $module_identifier, $src = '', $dependencies = array(), $version = false ) {
175	_deprecated_function( __FUNCTION__, 'Gutenberg 17.6.0', 'wp_register_script_module' );
176	wp_script_modules()->register( $module_identifier, $src, $dependencies, $version );
177	}
178
179	/**
180	* Marks the module to be enqueued in the page.
181	*
182	* @param string $module_identifier The identifier of the module.
183	* @deprecated 17.6.0 gutenberg_enqueue_module is deprecated. Please use wp_enqueue_script_module instead.
184	*/
185	function gutenberg_enqueue_module( $module_identifier ) {
186	_deprecated_function( __FUNCTION__, 'Gutenberg 17.6.0', 'wp_enqueue_script_module' );
187	wp_script_modules()->enqueue( $module_identifier );
188	}
189
190	/**
191	* Unmarks the module so it is not longer enqueued in the page.
192	*
193	* @param string $module_identifier The identifier of the module.
194	* @deprecated 17.6.0 gutenberg_dequeue_module is deprecated. Please use wp_dequeue_script_module instead.
195	*/
196	function gutenberg_dequeue_module( $module_identifier ) {
197	_deprecated_function( __FUNCTION__, 'Gutenberg 17.6.0', 'wp_dequeue_script_module' );
198	wp_script_modules()->dequeue( $module_identifier );
199	}
200
201
202	/**
203	* Print data associated with Script Modules in Script tags.
204	*
205	* This embeds data in the page HTML so that it is available on page load.
206	*
207	* Data can be associated with a given Script Module by using the
208	* `script_module_data_{$module_id}` filter.
209	*
210	* The data for a given Script Module will be JSON serialized in a script tag with an ID
211	* like `wp-script-module-data-{$module_id}`.
212	*/
213	function gutenberg_print_script_module_data(): void {
214	$get_marked_for_enqueue = new ReflectionMethod( 'WP_Script_Modules', 'get_marked_for_enqueue' );
215	$get_marked_for_enqueue->setAccessible( true );
216	$get_import_map = new ReflectionMethod( 'WP_Script_Modules', 'get_import_map' );
217	$get_import_map->setAccessible( true );
218
219	$modules = array();
220	foreach ( array_keys( $get_marked_for_enqueue->invoke( wp_script_modules() ) ) as $id ) {
221	$modules[ $id ] = true;
222	}
223	foreach ( array_keys( $get_import_map->invoke( wp_script_modules() )['imports'] ) as $id ) {
224	$modules[ $id ] = true;
225	}
226
227	foreach ( array_keys( $modules ) as $module_id ) {
228	/**
229	* Filters data associated with a given Script Module.
230	*
231	* Script Modules may require data that is required for initialization or is essential to
232	* have immediately available on page load. These are suitable use cases for this data.
233	*
234	* This is best suited to a minimal set of data and is not intended to replace the REST API.
235	*
236	* If the filter returns no data (an empty array), nothing will be embedded in the page.
237	*
238	* The data for a given Script Module, if provided, will be JSON serialized in a script tag
239	* with an ID like `wp-script-module-data-{$module_id}`.
240	*
241	* The dynamic portion of the hook name, `$module_id`, refers to the Script Module ID that
242	* the data is associated with.
243	*
244	* @param array $data The data that should be associated with the array.
245	*/
246	$data = apply_filters( "script_module_data_{$module_id}", array() );
247
248	if ( is_array( $data ) && ! empty( $data ) ) {
249	/*
250	* This data will be printed as JSON inside a script tag like this:
251	* <script type="application/json"></script>
252	*
253	* A script tag must be closed by a sequence beginning with `</`. It's impossible to
254	* close a script tag without using `<`. We ensure that `<` is escaped and `/` can
255	* remain unescaped, so `</script>` will be printed as `\u003C/script\u00E3`.
256	*
257	* - JSON_HEX_TAG: All < and > are converted to \u003C and \u003E.
258	* - JSON_UNESCAPED_SLASHES: Don't escape /.
259	*
260	* If the page will use UTF-8 encoding, it's safe to print unescaped unicode:
261	*
262	* - JSON_UNESCAPED_UNICODE: Encode multibyte Unicode characters literally (instead of as `\uXXXX`).
263	* - JSON_UNESCAPED_LINE_TERMINATORS: The line terminators are kept unescaped when
264	* JSON_UNESCAPED_UNICODE is supplied. It uses the same behaviour as it was
265	* before PHP 7.1 without this constant. Available as of PHP 7.1.0.
266	*
267	* The JSON specification requires encoding in UTF-8, so if the generated HTML page
268	* is not encoded in UTF-8 then it's not safe to include those literals. They must
269	* be escaped to avoid encoding issues.
270	*
271	* @see https://www.rfc-editor.org/rfc/rfc8259.html for details on encoding requirements.
272	* @see https://www.php.net/manual/en/json.constants.php for details on these constants.
273	* @see https://html.spec.whatwg.org/#script-data-state for details on script tag parsing.
274	*/
275	$json_encode_flags = JSON_HEX_TAG \| JSON_UNESCAPED_SLASHES \| JSON_UNESCAPED_UNICODE \| JSON_UNESCAPED_LINE_TERMINATORS;
276	if ( 'UTF-8' !== get_option( 'blog_charset' ) ) {
277	$json_encode_flags = JSON_HEX_TAG \| JSON_UNESCAPED_SLASHES;
278	}
279
280	wp_print_inline_script_tag(
281	wp_json_encode( $data, $json_encode_flags ),
282	array(
283	'type' => 'application/json',
284	'id' => "wp-script-module-data-{$module_id}",
285	)
286	);
287	}
288	}
289	}
290
291	add_action( 'wp_footer', 'gutenberg_print_script_module_data' );
292	add_action( 'admin_print_footer_scripts', 'gutenberg_print_script_module_data' );
293