Add docs for HtmlHelper::importmap()

cakephp · Jan 21, 2025 · c7f4ba2 · c7f4ba2
1 parent d3eec80
commit c7f4ba2
Show file tree

Hide file tree

Showing 2 changed files with 64 additions and 3 deletions.
diff --git a/en/appendices/5-2-migration-guide.rst b/en/appendices/5-2-migration-guide.rst
@@ -18,7 +18,6 @@ Behavior Changes
   being filterable from logging.
 - ``NumericPaginator::paginate()`` now uses the ``finder`` option even when a ``SelectQuery`` instance is passed to it.
 
-
 Deprecations
 ============
 
@@ -86,8 +85,10 @@ ORM
 View
 ----
 
- - ``FormHelper::deleteLink()`` has been added as convenience wrapper for delete links in
-   templates using `DELETE` method.
+- ``FormHelper::deleteLink()`` has been added as convenience wrapper for delete links in
+   templates using ``DELETE`` method.
+- ``HtmlHelper::importmap()`` was added. This method allows you to define
+  import maps for your JavaScript files.
 
 Error
 -----

diff --git a/en/views/helpers/html.rst b/en/views/helpers/html.rst
@@ -561,6 +561,66 @@ Once you have buffered javascript, you can output it as you would any other
     // In your layout
     echo $this->fetch('script');
 
+Creating Javascript Importmap
+-----------------------------
+
+.. php:method:: importmap(array $map, array $options = []): string
+
+Creates an `importmap` script tag for your JavaScript files::
+
+    // In the head tag of your layout
+    echo $this->Html->importmap([
+        'jquery' => 'jquery.js',
+        'wysiwyg' => '/editor/wysiwyg.js'
+    ]);
+
+Will output:
+
+.. code-block:: html
+
+    <script type="importmap">{
+        "imports": {
+            "jquery": "/js/jquery.js",
+            "wysiwyg": "/editor/wysiwyg.js"
+        }
+    }</script>
+
+Generating maps with imports, scopes and integrity::
+
+    echo $this->Html->importmap([
+        'imports' => [
+            'jquery' => 'jquery-3.7.1.min.js',
+            'wysiwyg' => '/editor/wysiwyg.js'
+        ],
+        'scopes' => [
+            'scoped/' => [
+                'foo' => 'inner/foo',
+            ],
+        ],
+        'integrity' => [
+            'jquery' => 'sha256-/JqT3SQfawRcv/BIHPThkBvs0OEvtFFmqPF/lYI/Cxo=',
+        ],
+    ]);
+
+Will output:
+
+.. code-block:: html
+
+    <script type="importmap">{
+        "imports": {
+            "jquery": "/js/jquery-3.7.1.min.js",
+            "wysiwyg": "/editor/wysiwyg.js"
+        },
+        "scopes": {
+            "scoped/": {
+                "foo": "/js/inner/foo.js"
+            }
+        },
+        "integrity": {
+            "/js/jquery-3.7.1.min.js": "sha256-/JqT3SQfawRcv/BIHPThkBvs0OEvtFFmqPF/lYI/Cxo="
+        }
+    }</script>
+
 Creating Nested Lists
 ---------------------