gutenberg / lib / client-assets.php

client-assets.php in Gutenberg 15.2.3, at lib/client-assets.php

568 lines 19.6 KB

Raw Download Zip

1	<?php
2	/**
3	* Functions to register client-side assets (scripts and stylesheets) specific
4	* for the Gutenberg editor plugin.
5	*
6	* @package gutenberg
7	*/
8
9	if ( ! defined( 'ABSPATH' ) ) {
10	die( 'Silence is golden.' );
11	}
12
13	/**
14	* Retrieves the root plugin path.
15	*
16	* @return string Root path to the gutenberg plugin.
17	*
18	* @since 0.1.0
19	*/
20	function gutenberg_dir_path() {
21	return plugin_dir_path( __DIR__ );
22	}
23
24	/**
25	* Retrieves a URL to a file in the gutenberg plugin.
26	*
27	* @param string $path Relative path of the desired file.
28	*
29	* @return string Fully qualified URL pointing to the desired file.
30	*
31	* @since 0.1.0
32	*/
33	function gutenberg_url( $path ) {
34	return plugins_url( $path, __DIR__ );
35	}
36
37	/**
38	* Registers a script according to `wp_register_script`. Honors this request by
39	* reassigning internal dependency properties of any script handle already
40	* registered by that name. It does not deregister the original script, to
41	* avoid losing inline scripts which may have been attached.
42	*
43	* @since 4.1.0
44	*
45	* @param WP_Scripts $scripts WP_Scripts instance.
46	* @param string $handle Name of the script. Should be unique.
47	* @param string $src Full URL of the script, or path of the script relative to the WordPress root directory.
48	* @param array $deps Optional. An array of registered script handles this script depends on. Default empty array.
49	* @param string\|bool\|null $ver Optional. String specifying script version number, if it has one, which is added to the URL
50	* as a query string for cache busting purposes. If version is set to false, a version
51	* number is automatically added equal to current installed WordPress version.
52	* If set to null, no version is added.
53	* @param bool $in_footer Optional. Whether to enqueue the script before </body> instead of in the <head>.
54	* Default 'false'.
55	*/
56	function gutenberg_override_script( $scripts, $handle, $src, $deps = array(), $ver = false, $in_footer = false ) {
57	/*
58	* Force `wp-i18n` script to be registered in the <head> as a
59	* temporary workaround for https://meta.trac.wordpress.org/ticket/6195.
60	*/
61	$in_footer = 'wp-i18n' === $handle ? false : $in_footer;
62
63	$script = $scripts->query( $handle, 'registered' );
64	if ( $script ) {
65	/*
66	* In many ways, this is a reimplementation of `wp_register_script` but
67	* bypassing consideration of whether a script by the given handle had
68	* already been registered.
69	*/
70
71	// See: `_WP_Dependency::__construct` .
72	$script->src = $src;
73	$script->deps = $deps;
74	$script->ver = $ver;
75	$script->args = $in_footer ? 1 : null;
76	} else {
77	$scripts->add( $handle, $src, $deps, $ver, ( $in_footer ? 1 : null ) );
78	}
79
80	/*
81	* `WP_Dependencies::set_translations` will fall over on itself if setting
82	* translations on the `wp-i18n` handle, since it internally adds `wp-i18n`
83	* as a dependency of itself, exhausting memory. The same applies for the
84	* polyfill and hooks scripts, which are dependencies _of_ `wp-i18n`.
85	*
86	* See: https://core.trac.wordpress.org/ticket/46089
87	*/
88	if ( ! in_array( $handle, array( 'wp-i18n', 'wp-polyfill', 'wp-hooks' ), true ) ) {
89	$scripts->set_translations( $handle, 'default' );
90	}
91
92	/*
93	* Wp-editor module is exposed as window.wp.editor.
94	* Problem: there is quite some code expecting window.wp.oldEditor object available under window.wp.editor.
95	* Solution: fuse the two objects together to maintain backward compatibility.
96	* For more context, see https://github.com/WordPress/gutenberg/issues/33203
97	*/
98	if ( 'wp-editor' === $handle ) {
99	$scripts->add_inline_script(
100	'wp-editor',
101	'Object.assign( window.wp.editor, window.wp.oldEditor );',
102	'after'
103	);
104	}
105	}
106
107	/**
108	* Filters the default translation file load behavior to load the Gutenberg
109	* plugin translation file, if available.
110	*
111	* @param string\|false $file Path to the translation file to load. False if
112	* there isn't one.
113	* @param string $handle Name of the script to register a translation
114	* domain to.
115	*
116	* @return string\|false Filtered path to the Gutenberg translation file, if
117	* available.
118	*/
119	function gutenberg_override_translation_file( $file, $handle ) {
120	if ( ! $file ) {
121	return $file;
122	}
123
124	// Ignore scripts whose handle does not have the "wp-" prefix.
125	if ( ! str_starts_with( $handle, 'wp-' ) ) {
126	return $file;
127	}
128
129	// Ignore scripts that are not found in the expected `build/` location.
130	$script_path = gutenberg_dir_path() . 'build/' . substr( $handle, 3 ) . '/index.min.js';
131	if ( ! file_exists( $script_path ) ) {
132	return $file;
133	}
134
135	/*
136	* The default file will be in the plugins language directory, omitting the
137	* domain since Gutenberg assigns the script translations as the default.
138	*
139	* Example: /www/wp-content/languages/plugins/de_DE-07d88e6a803e01276b9bfcc1203e862e.json
140	*
141	* The logic of `load_script_textdomain` is such that it will assume to
142	* search in the plugins language directory, since the assigned source of
143	* the overridden Gutenberg script originates in the plugins directory.
144	*
145	* The plugin translation files each begin with the slug of the plugin, so
146	* it's a simple matter of prepending the Gutenberg plugin slug.
147	*/
148	$path_parts = pathinfo( $file );
149	$plugin_translation_file = (
150	$path_parts['dirname'] .
151	'/gutenberg-' .
152	$path_parts['basename']
153	);
154
155	return $plugin_translation_file;
156	}
157	add_filter( 'load_script_translation_file', 'gutenberg_override_translation_file', 10, 2 );
158
159	/**
160	* Registers a style according to `wp_register_style`. Honors this request by
161	* deregistering any style by the same handler before registration.
162	*
163	* @since 4.1.0
164	*
165	* @param WP_Styles $styles WP_Styles instance.
166	* @param string $handle Name of the stylesheet. Should be unique.
167	* @param string $src Full URL of the stylesheet, or path of the stylesheet relative to the WordPress root directory.
168	* @param array $deps Optional. An array of registered stylesheet handles this stylesheet depends on. Default empty array.
169	* @param string\|bool\|null $ver Optional. String specifying stylesheet version number, if it has one, which is added to the URL
170	* as a query string for cache busting purposes. If version is set to false, a version
171	* number is automatically added equal to current installed WordPress version.
172	* If set to null, no version is added.
173	* @param string $media Optional. The media for which this stylesheet has been defined.
174	* Default 'all'. Accepts media types like 'all', 'print' and 'screen', or media queries like
175	* '(orientation: portrait)' and '(max-width: 640px)'.
176	*/
177	function gutenberg_override_style( $styles, $handle, $src, $deps = array(), $ver = false, $media = 'all' ) {
178	$style = $styles->query( $handle, 'registered' );
179	if ( $style ) {
180	$styles->remove( $handle );
181	}
182	$styles->add( $handle, $src, $deps, $ver, $media );
183	}
184
185	/**
186	* Registers all the WordPress packages scripts that are in the standardized
187	* `build/` location.
188	*
189	* @since 4.5.0
190	*
191	* @param WP_Scripts $scripts WP_Scripts instance.
192	*/
193	function gutenberg_register_packages_scripts( $scripts ) {
194	// When in production, use the plugin's version as the default asset version;
195	// else (for development or test) default to use the current time.
196	$default_version = defined( 'GUTENBERG_VERSION' ) && ! SCRIPT_DEBUG ? GUTENBERG_VERSION : time();
197
198	foreach ( glob( gutenberg_dir_path() . 'build/*/index.min.js' ) as $path ) {
199	// Prefix `wp-` to package directory to get script handle.
200	// For example, `…/build/a11y/index.min.js` becomes `wp-a11y`.
201	$handle = 'wp-' . basename( dirname( $path ) );
202
203	// Replace extension with `.asset.php` to find the generated dependencies file.
204	$asset_file = substr( $path, 0, -( strlen( '.js' ) ) ) . '.asset.php';
205	$asset = file_exists( $asset_file )
206	? require $asset_file
207	: null;
208	$dependencies = isset( $asset['dependencies'] ) ? $asset['dependencies'] : array();
209	$version = isset( $asset['version'] ) ? $asset['version'] : $default_version;
210
211	// Add dependencies that cannot be detected and generated by build tools.
212	switch ( $handle ) {
213	case 'wp-block-library':
214	array_push( $dependencies, 'editor' );
215	break;
216
217	case 'wp-edit-post':
218	array_push( $dependencies, 'media-models', 'media-views', 'postbox' );
219	break;
220
221	case 'wp-edit-site':
222	array_push( $dependencies, 'wp-dom-ready' );
223	break;
224	}
225
226	// Get the path from Gutenberg directory as expected by `gutenberg_url`.
227	$gutenberg_path = substr( $path, strlen( gutenberg_dir_path() ) );
228
229	gutenberg_override_script(
230	$scripts,
231	$handle,
232	gutenberg_url( $gutenberg_path ),
233	$dependencies,
234	$version,
235	true
236	);
237	}
238	}
239	add_action( 'wp_default_scripts', 'gutenberg_register_packages_scripts' );
240
241	/**
242	* Registers all the WordPress packages styles that are in the standardized
243	* `build/` location.
244	*
245	* @since 6.7.0
246
247	* @param WP_Styles $styles WP_Styles instance.
248	*/
249	function gutenberg_register_packages_styles( $styles ) {
250	// When in production, use the plugin's version as the asset version;
251	// else (for development or test) default to use the current time.
252	$version = defined( 'GUTENBERG_VERSION' ) && ! SCRIPT_DEBUG ? GUTENBERG_VERSION : time();
253
254	gutenberg_override_style(
255	$styles,
256	'wp-block-editor-content',
257	gutenberg_url( 'build/block-editor/content.css' ),
258	array(),
259	$version
260	);
261	$styles->add_data( 'wp-block-editor-content', 'rtl', 'replace' );
262
263	// Editor Styles.
264	gutenberg_override_style(
265	$styles,
266	'wp-block-editor',
267	gutenberg_url( 'build/block-editor/style.css' ),
268	array( 'wp-components' ),
269	$version
270	);
271	$styles->add_data( 'wp-block-editor', 'rtl', 'replace' );
272
273	gutenberg_override_style(
274	$styles,
275	'wp-editor',
276	gutenberg_url( 'build/editor/style.css' ),
277	array( 'wp-components', 'wp-block-editor', 'wp-reusable-blocks' ),
278	$version
279	);
280	$styles->add_data( 'wp-editor', 'rtl', 'replace' );
281
282	gutenberg_override_style(
283	$styles,
284	'wp-edit-post',
285	gutenberg_url( 'build/edit-post/style.css' ),
286	array( 'wp-components', 'wp-block-editor', 'wp-editor', 'wp-edit-blocks', 'wp-block-library' ),
287	$version
288	);
289	$styles->add_data( 'wp-edit-post', 'rtl', 'replace' );
290
291	gutenberg_override_style(
292	$styles,
293	'wp-components',
294	gutenberg_url( 'build/components/style.css' ),
295	array( 'dashicons' ),
296	$version
297	);
298	$styles->add_data( 'wp-components', 'rtl', 'replace' );
299
300	$block_library_filename = wp_should_load_separate_core_block_assets() ? 'common' : 'style';
301	gutenberg_override_style(
302	$styles,
303	'wp-block-library',
304	gutenberg_url( 'build/block-library/' . $block_library_filename . '.css' ),
305	array(),
306	$version
307	);
308	$styles->add_data( 'wp-block-library', 'rtl', 'replace' );
309	$styles->add_data( 'wp-block-library', 'path', gutenberg_dir_path() . 'build/block-library/' . $block_library_filename . '.css' );
310
311	gutenberg_override_style(
312	$styles,
313	'wp-format-library',
314	gutenberg_url( 'build/format-library/style.css' ),
315	array( 'wp-block-editor', 'wp-components' ),
316	$version
317	);
318	$styles->add_data( 'wp-format-library', 'rtl', 'replace' );
319
320	$wp_edit_blocks_dependencies = array(
321	'wp-components',
322	// This need to be added before the block library styles,
323	// The block library styles override the "reset" styles.
324	'wp-reset-editor-styles',
325	'wp-block-library',
326	'wp-reusable-blocks',
327	// Until #37466, we can't specifically add them as editor styles yet,
328	// so we must hard-code it here as a dependency.
329	'wp-block-editor-content',
330	);
331
332	// Only load the default layout and margin styles for themes without theme.json file.
333	if ( ! wp_theme_has_theme_json() ) {
334	$wp_edit_blocks_dependencies[] = 'wp-editor-classic-layout-styles';
335	}
336
337	global $editor_styles;
338	if ( current_theme_supports( 'wp-block-styles' ) && ( ! is_array( $editor_styles ) \|\| count( $editor_styles ) === 0 ) ) {
339	// Include opinionated block styles if the theme supports block styles and no $editor_styles are declared, so the editor never appears broken.
340	$wp_edit_blocks_dependencies[] = 'wp-block-library-theme';
341	}
342
343	gutenberg_override_style(
344	$styles,
345	'wp-reset-editor-styles',
346	gutenberg_url( 'build/block-library/reset.css' ),
347	array( 'common', 'forms' ), // Make sure the reset is loaded after the default WP Admin styles.
348	$version
349	);
350	$styles->add_data( 'wp-reset-editor-styles', 'rtl', 'replace' );
351
352	gutenberg_override_style(
353	$styles,
354	'wp-editor-classic-layout-styles',
355	gutenberg_url( 'build/edit-post/classic.css' ),
356	array(),
357	$version
358	);
359	$styles->add_data( 'wp-editor-classic-layout-styles', 'rtl', 'replace' );
360
361	gutenberg_override_style(
362	$styles,
363	'wp-edit-blocks',
364	gutenberg_url( 'build/block-library/editor.css' ),
365	$wp_edit_blocks_dependencies,
366	$version
367	);
368	$styles->add_data( 'wp-edit-blocks', 'rtl', 'replace' );
369
370	gutenberg_override_style(
371	$styles,
372	'wp-block-library-theme',
373	gutenberg_url( 'build/block-library/theme.css' ),
374	array(),
375	$version
376	);
377	$styles->add_data( 'wp-block-library-theme', 'rtl', 'replace' );
378
379	gutenberg_override_style(
380	$styles,
381	'wp-list-reusable-blocks',
382	gutenberg_url( 'build/list-reusable-blocks/style.css' ),
383	array( 'wp-components' ),
384	$version
385	);
386	$styles->add_data( 'wp-list-reusable-block', 'rtl', 'replace' );
387
388	gutenberg_override_style(
389	$styles,
390	'wp-edit-site',
391	gutenberg_url( 'build/edit-site/style.css' ),
392	array( 'wp-components', 'wp-block-editor', 'wp-editor', 'wp-edit-blocks' ),
393	$version
394	);
395	$styles->add_data( 'wp-edit-site', 'rtl', 'replace' );
396
397	gutenberg_override_style(
398	$styles,
399	'wp-edit-widgets',
400	gutenberg_url( 'build/edit-widgets/style.css' ),
401	array( 'wp-components', 'wp-block-editor', 'wp-editor', 'wp-edit-blocks', 'wp-reusable-blocks', 'wp-widgets' ),
402	$version
403	);
404	$styles->add_data( 'wp-edit-widgets', 'rtl', 'replace' );
405
406	gutenberg_override_style(
407	$styles,
408	'wp-block-directory',
409	gutenberg_url( 'build/block-directory/style.css' ),
410	array( 'wp-block-editor', 'wp-components' ),
411	$version
412	);
413	$styles->add_data( 'wp-block-directory', 'rtl', 'replace' );
414
415	gutenberg_override_style(
416	$styles,
417	'wp-customize-widgets',
418	gutenberg_url( 'build/customize-widgets/style.css' ),
419	array( 'wp-components', 'wp-block-editor', 'wp-editor', 'wp-edit-blocks', 'wp-widgets' ),
420	$version
421	);
422	$styles->add_data( 'wp-customize-widgets', 'rtl', 'replace' );
423
424	gutenberg_override_style(
425	$styles,
426	'wp-reusable-blocks',
427	gutenberg_url( 'build/reusable-blocks/style.css' ),
428	array( 'wp-components' ),
429	$version
430	);
431	$styles->add_data( 'wp-reusable-block', 'rtl', 'replace' );
432
433	gutenberg_override_style(
434	$styles,
435	'wp-widgets',
436	gutenberg_url( 'build/widgets/style.css' ),
437	array( 'wp-components' )
438	);
439	$styles->add_data( 'wp-widgets', 'rtl', 'replace' );
440	}
441	add_action( 'wp_default_styles', 'gutenberg_register_packages_styles' );
442
443	/**
444	* Fetches, processes and compiles stored core styles, then combines and renders them to the page.
445	* Styles are stored via the Style Engine API.
446	*
447	* This hook also exists, and should be backported to Core in future versions.
448	* However, it is envisaged that Gutenberg will continue to use the Style Engine's `gutenberg_*` functions and `_Gutenberg` classes to aid continuous development.
449	*
450	* See: https://developer.wordpress.org/block-editor/reference-guides/packages/packages-style-engine/
451	*
452	* @param array $options {
453	* Optional. An array of options to pass to gutenberg_style_engine_get_stylesheet_from_context(). Default empty array.
454	*
455	* @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
456	* @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined.
457	* }
458	*
459	* @since 6.1
460	*
461	* @return void
462	*/
463	function gutenberg_enqueue_stored_styles( $options = array() ) {
464	$is_block_theme = wp_is_block_theme();
465	$is_classic_theme = ! $is_block_theme;
466
467	/*
468	* For block themes, print stored styles in the header.
469	* For classic themes, in the footer.
470	*/
471	if (
472	( $is_block_theme && doing_action( 'wp_footer' ) ) \|\|
473	( $is_classic_theme && doing_action( 'wp_enqueue_scripts' ) )
474	) {
475	return;
476	}
477
478	$core_styles_keys = array( 'block-supports' );
479	$compiled_core_stylesheet = '';
480	$style_tag_id = 'core';
481	foreach ( $core_styles_keys as $style_key ) {
482	// Adds comment if code is prettified to identify core styles sections in debugging.
483	$should_prettify = isset( $options['prettify'] ) ? true === $options['prettify'] : SCRIPT_DEBUG;
484	if ( $should_prettify ) {
485	$compiled_core_stylesheet .= "/*\n Core styles: $style_key\n */\n";
486	}
487	// Chains core store ids to signify what the styles contain.
488	$style_tag_id .= '-' . $style_key;
489	$compiled_core_stylesheet .= gutenberg_style_engine_get_stylesheet_from_context( $style_key, $options );
490	}
491
492	// Combines Core styles.
493	if ( ! empty( $compiled_core_stylesheet ) ) {
494	wp_register_style( $style_tag_id, false, array(), true, true );
495	wp_add_inline_style( $style_tag_id, $compiled_core_stylesheet );
496	wp_enqueue_style( $style_tag_id );
497	}
498
499	// If there are any other stores registered by themes etc., print them out.
500	$additional_stores = WP_Style_Engine_CSS_Rules_Store_Gutenberg::get_stores();
501
502	/*
503	* Since the corresponding action hook in Core is removed below,
504	* this function should still honour any styles stored using the Core Style Engine store.
505	*/
506	if ( class_exists( 'WP_Style_Engine_CSS_Rules_Store' ) ) {
507	$additional_stores = array_merge( $additional_stores, WP_Style_Engine_CSS_Rules_Store::get_stores() );
508	}
509
510	foreach ( array_keys( $additional_stores ) as $store_name ) {
511	if ( in_array( $store_name, $core_styles_keys, true ) ) {
512	continue;
513	}
514	$styles = gutenberg_style_engine_get_stylesheet_from_context( $store_name, $options );
515	if ( ! empty( $styles ) ) {
516	$key = "wp-style-engine-$store_name";
517	wp_register_style( $key, false, array(), true, true );
518	wp_add_inline_style( $key, $styles );
519	wp_enqueue_style( $key );
520	}
521	}
522	}
523
524	/**
525	* Registers vendor JavaScript files to be used as dependencies of the editor
526	* and plugins.
527	*
528	* This function is called from a script during the plugin build process, so it
529	* should not call any WordPress PHP functions.
530	*
531	* @since 13.0
532	*
533	* @param WP_Scripts $scripts WP_Scripts instance.
534	*/
535	function gutenberg_register_vendor_scripts( $scripts ) {
536	$extension = SCRIPT_DEBUG ? '.js' : '.min.js';
537
538	gutenberg_override_script(
539	$scripts,
540	'react',
541	gutenberg_url( 'build/vendors/react' . $extension ),
542	// See https://github.com/pmmmwh/react-refresh-webpack-plugin/blob/main/docs/TROUBLESHOOTING.md#externalising-react.
543	SCRIPT_DEBUG ? array( 'wp-react-refresh-entry', 'wp-polyfill' ) : array( 'wp-polyfill' ),
544	'18'
545	);
546	gutenberg_override_script(
547	$scripts,
548	'react-dom',
549	gutenberg_url( 'build/vendors/react-dom' . $extension ),
550	array( 'react' ),
551	'18'
552	);
553	}
554	add_action( 'wp_default_scripts', 'gutenberg_register_vendor_scripts' );
555
556
557	/*
558	* Always remove the Core action hook while gutenberg_enqueue_stored_styles() exists to avoid styles being printed twice.
559	* This is also because gutenberg_enqueue_stored_styles uses the Style Engine's `gutenberg_*` functions and `_Gutenberg` classes,
560	* which are in continuous development and generally ahead of Core.
561	*/
562	remove_action( 'wp_enqueue_scripts', 'wp_enqueue_stored_styles' );
563	remove_action( 'wp_footer', 'wp_enqueue_stored_styles', 1 );
564
565	// Enqueue stored styles.
566	add_action( 'wp_enqueue_scripts', 'gutenberg_enqueue_stored_styles' );
567	add_action( 'wp_footer', 'gutenberg_enqueue_stored_styles', 1 );
568