Upstream
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
WordPress/wp-includes/script-modules.php

117 lines
7.3 KiB
PHP
Raw Normal View History

JavaScript: Add new Modules API. This changeset adds a new API for WordPress, designed to work with native ES Modules and Import Maps. It introduces functions such as `wp_register_module`, and `wp_enqueue_module`. The API aims to provide a familiar experience to the existing `WP_Scripts` class, offering similar functionality. However, **it's not intended to duplicate the exact functionality of `WP_Scripts`**; rather, it is carefully tailored to address the specific needs and capabilities of ES modules. For this initial version, **the current proposal is intentionally simplistic**, covering only the essential features needed to work with ES modules. Other enhancements and optimizations can be added later as the community identifies additional requirements and use cases. == Differences Between WP_Script_Modules and WP_Scripts === Dependency Specification With `WP_Script_Modules`, the array of dependencies supports not only strings but also arrays that include the dependency import type (`static` or `dynamic`). This design choice allows for future extensions of dependency properties, such as adding a `version` property to support "scopes" within import maps. === Module Identifier Instead of a handle, `WP_Script_Modules` utilizes the module identifier, aligning with the module identifiers used in JavaScript files and import maps. === Deregistration There is no equivalent of `wp_deregister_script` at this stage. == API === `wp_register_module( $module_identifier, $src, $deps, $version )` Registers a module. {{{ // Registers a module with dependencies and versioning. wp_register_module( 'my-module', '/path/to/my-module.js', array( 'static-dependency-1', 'static-dependency-2' ), '1.2.3' ); }}} {{{ // my-module.js import { ... } from 'static-dependency-1'; import { ... } from 'static-dependency-2'; // ... }}} {{{ // Registers a module with a dynamic dependency. wp_register_module( 'my-module', '/path/to/my-module.js', array( 'static-dependency', array( 'id' => 'dynamic-dependency', 'import' => 'dynamic' ), ) ); }}} {{{ // my-module.js import { ... } from 'static-dependency'; // ... const dynamicModule = await import('dynamic-dependency'); }}} === `wp_enqueue_module( $module_identifier, $src, $deps, $version )` Enqueues a module. If a source is provided, it will also register the module. {{{ wp_enqueue_module( 'my-module' ); }}} === `wp_dequeue_module( $module_identifier )` Dequeues a module. {{{ wp_dequeue_module( 'my-module' ); }}} == Output - When modules are enqueued, they are printed within script tags containing `type="module"` attributes. - Additionally, static dependencies of enqueued modules utilize `link` tags with `rel="modulepreload"` attributes. - Lastly, an import map is generated and inserted using a `<script type="importmap">` tag. {{{ <script type="module" src="/path/to/my-module.js" id="my-module"></script> <link rel="modulepreload" href="/path/to/static-dependency.js" id="static-dependency" /> <script type="importmap"> { "imports": { "static-dependency": "/path/to/static-dependency.js", "dynamic-dependency": "/path/to/dynamic-dependency.js" } } </script> }}} == Import Map Polyfill Requirement Even though all major browsers already support import maps, an import map polyfill is required until the percentage of users using old browser versions without import map support drops significantly. This work is ongoing and will be added once it's ready. Progress is tracked in #60232. Props luisherranz, idad5, costdev, neffff, joemcgill, jorbin, swissspidy, jonsurrell, flixos90, gziolo, westonruter. Fixes #56313. Built from https://develop.svn.wordpress.org/trunk@57269 git-svn-id: http://core.svn.wordpress.org/trunk@56775 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2024-01-11 15:47:14 +01:00
<?php
/**
* Script Modules API: Module functions
*
* @since 6.5.0
*
* @package WordPress
* @subpackage Script Modules
*/
/**
* Retrieves the main WP_Script_Modules instance.
*
* This function provides access to the WP_Script_Modules instance, creating one
* if it doesn't exist yet.
*
* @since 6.5.0
*
* @return WP_Script_Modules The main WP_Script_Modules instance.
*/
function wp_modules() {
static $instance = null;
if ( is_null( $instance ) ) {
$instance = new WP_Script_Modules();
$instance->add_hooks();
}
return $instance;
}
/**
* Registers the module if no module with that module identifier has already
* been registered.
*
* @since 6.5.0
*
* @param string $module_id The identifier of the module.
* Should be unique. It will be used
* in the final import map.
* @param string $src Full URL of the module, or path of
* the module relative to the
* WordPress root directory.
* @param array<string|array{id: string, import?: 'static'|'dynamic' }> $deps 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` key are considered static.
* @param string|false|null $version Optional. String specifying the
* 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.
*/
function wp_register_module( $module_id, $src, $deps = array(), $version = false ) {
wp_modules()->register( $module_id, $src, $deps, $version );
}
/**
* Marks the module to be enqueued in the page.
*
* If a src is provided and the module has not been registered yet, it will be
* registered.
*
* @since 6.5.0
*
* @param string $module_id The identifier of the module.
* Should be unique. It will be used
* in the final import map.
* @param string $src Optional. Full URL of the module,
* or path of the module relative to
* the WordPress root directory. If
* it is provided and the module has
* not been registered yet, it will be
* registered.
* @param array<string|array{id: string, import?: 'static'|'dynamic' }> $deps 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` key are considered static.
* @param string|false|null $version Optional. String specifying the
* 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.
*/
function wp_enqueue_module( $module_id, $src = '', $deps = array(), $version = false ) {
wp_modules()->enqueue( $module_id, $src, $deps, $version );
}
/**
* Unmarks the module so it is no longer enqueued in the page.
*
* @since 6.5.0
*
* @param string $module_id The identifier of the module.
*/
function wp_dequeue_module( $module_id ) {
wp_modules()->dequeue( $module_id );
}