Merge pull request #78 from jverneaut/76-add-new-api-to-explicitly-define-attributes

jverneaut · web-flow · commit 6702681e040d · 2025-05-30T00:36:14.000+02:00
76 Add new api to explicitly define attributes
diff --git a/__tests__/fixtures/processable/explicit-block-attributes-overrides/expected.index.js b/__tests__/fixtures/processable/explicit-block-attributes-overrides/expected.index.js
@@ -0,0 +1,9 @@
+import { registerBlockType } from "@wordpress/blocks";
+
+import Edit from "./edit.js";
+import metadata from "./block.json";
+
+registerBlockType(metadata.name, {
+  edit: Edit,
+  save: () => null,
+});
diff --git a/__tests__/fixtures/processable/explicit-block-attributes-overrides/expected.js b/__tests__/fixtures/processable/explicit-block-attributes-overrides/expected.js
@@ -0,0 +1,14 @@
+import { useBlockProps, RichText } from "@wordpress/block-editor";
+
+export default ({ attributes, setAttributes }) => {
+  return (
+    <section {...useBlockProps()}>
+      <RichText
+        tagName="h2"
+        value={attributes.title}
+        onChange={(title) => setAttributes({ title })}
+        placeholder="Title"
+      ></RichText>
+    </section>
+  );
+};
diff --git a/__tests__/fixtures/processable/explicit-block-attributes-overrides/expected.json b/__tests__/fixtures/processable/explicit-block-attributes-overrides/expected.json
@@ -0,0 +1,17 @@
+{
+  "name": "custom/input",
+  "title": "Input",
+  "textdomain": "input",
+  "$schema": "https://schemas.wp.org/trunk/block.json",
+  "apiVersion": 3,
+  "version": "0.1.0",
+  "category": "theme",
+  "example": {},
+  "attributes": {
+    "align": { "type": "string", "default": "full" },
+    "title": { "default": "Default title", "type": "string" }
+  },
+  "supports": { "html": false, "align": ["full"] },
+  "editorScript": "file:./index.js",
+  "render": "file:./render.php"
+}
diff --git a/__tests__/fixtures/processable/explicit-block-attributes-overrides/expected.php b/__tests__/fixtures/processable/explicit-block-attributes-overrides/expected.php
@@ -0,0 +1,5 @@
+<section <?php echo get_block_wrapper_attributes(); ?>>
+  
+
+  <h2><?php echo wp_kses_post($attributes['title'] ?? ''); ?></h2>
+</section>
diff --git a/__tests__/fixtures/processable/explicit-block-attributes-overrides/input.html b/__tests__/fixtures/processable/explicit-block-attributes-overrides/input.html
@@ -0,0 +1,6 @@
+<section>
+  <!-- This has precedence over the data-attribute attribute -->
+  <block-attribute name="title" default="Default title"></block-attribute>
+
+  <h2 data-attribute="title"></h2>
+</section>
diff --git a/__tests__/fixtures/processable/explicit-block-attributes/expected.index.js b/__tests__/fixtures/processable/explicit-block-attributes/expected.index.js
@@ -0,0 +1,9 @@
+import { registerBlockType } from "@wordpress/blocks";
+
+import Edit from "./edit.js";
+import metadata from "./block.json";
+
+registerBlockType(metadata.name, {
+  edit: Edit,
+  save: () => null,
+});
diff --git a/__tests__/fixtures/processable/explicit-block-attributes/expected.js b/__tests__/fixtures/processable/explicit-block-attributes/expected.js
@@ -0,0 +1,5 @@
+import { useBlockProps, RichText } from "@wordpress/block-editor";
+
+export default ({ attributes, setAttributes }) => {
+  return <section {...useBlockProps()}></section>;
+};
diff --git a/__tests__/fixtures/processable/explicit-block-attributes/expected.json b/__tests__/fixtures/processable/explicit-block-attributes/expected.json
@@ -0,0 +1,34 @@
+{
+  "name": "custom/input",
+  "title": "Input",
+  "textdomain": "input",
+  "$schema": "https://schemas.wp.org/trunk/block.json",
+  "apiVersion": 3,
+  "version": "0.1.0",
+  "category": "theme",
+  "example": {},
+  "attributes": {
+    "align": { "type": "string", "default": "full" },
+    "stringAttrWithoutType": { "type": "string" },
+    "stringAttrWithType": { "type": "string" },
+    "stringAttrWithDefault": { "default": "value", "type": "string" },
+    "stringAttrWithTypeAndDefault": { "default": "value", "type": "string" },
+    "integerAttrWithType": { "type": "integer" },
+    "integerAttrWithDefault": { "default": 5, "type": "integer" },
+    "integerAttrWithTypeAndDefault": { "default": 5, "type": "integer" },
+    "numberAttrWithType": { "type": "number" },
+    "numberAttrWithDefault": { "default": 0.1, "type": "number" },
+    "numberAttrWithTypeAndDefault": { "default": 0.1, "type": "number" },
+    "booleanAttrWithType": { "type": "boolean" },
+    "booleanAttrWithDefaultTrue": { "default": true, "type": "boolean" },
+    "booleanAttrWithDefaultFalse": { "default": false, "type": "boolean" },
+    "booleanAttrWithTypeAndDefaultTrue": { "default": true, "type": "boolean" },
+    "booleanAttrWithTypeAndDefaultFalse": {
+      "default": false,
+      "type": "boolean"
+    }
+  },
+  "supports": { "html": false, "align": ["full"] },
+  "editorScript": "file:./index.js",
+  "render": "file:./render.php"
+}
diff --git a/__tests__/fixtures/processable/explicit-block-attributes/expected.php b/__tests__/fixtures/processable/explicit-block-attributes/expected.php
@@ -0,0 +1,20 @@
+<section <?php echo get_block_wrapper_attributes(); ?>>
+  
+  
+  
+  
+
+  
+  
+  
+
+  
+  
+  
+
+  
+  
+  
+  
+  
+</section>
diff --git a/__tests__/fixtures/processable/explicit-block-attributes/input.html b/__tests__/fixtures/processable/explicit-block-attributes/input.html
@@ -0,0 +1,49 @@
+<section>
+  <block-attribute name="stringAttrWithoutType"></block-attribute>
+  <block-attribute name="stringAttrWithType" type="string"></block-attribute>
+  <block-attribute
+    name="stringAttrWithDefault"
+    default="value"
+  ></block-attribute>
+  <block-attribute
+    name="stringAttrWithTypeAndDefault"
+    type="string"
+    default="value"
+  ></block-attribute>
+
+  <block-attribute name="integerAttrWithType" type="integer"></block-attribute>
+  <block-attribute name="integerAttrWithDefault" default="5"></block-attribute>
+  <block-attribute
+    name="integerAttrWithTypeAndDefault"
+    type="integer"
+    default="5"
+  ></block-attribute>
+
+  <block-attribute name="numberAttrWithType" type="number"></block-attribute>
+  <block-attribute name="numberAttrWithDefault" default="0.1"></block-attribute>
+  <block-attribute
+    name="numberAttrWithTypeAndDefault"
+    type="number"
+    default="0.1"
+  ></block-attribute>
+
+  <block-attribute name="booleanAttrWithType" type="boolean"></block-attribute>
+  <block-attribute
+    name="booleanAttrWithDefaultTrue"
+    default="true"
+  ></block-attribute>
+  <block-attribute
+    name="booleanAttrWithDefaultFalse"
+    default="false"
+  ></block-attribute>
+  <block-attribute
+    name="booleanAttrWithTypeAndDefaultTrue"
+    type="boolean"
+    default="true"
+  ></block-attribute>
+  <block-attribute
+    name="booleanAttrWithTypeAndDefaultFalse"
+    type="boolean"
+    default="false"
+  ></block-attribute>
+</section>
diff --git a/docs/docs/experimental/explicit-attributes-declaration.mdx b/docs/docs/experimental/explicit-attributes-declaration.mdx
@@ -0,0 +1,31 @@
+import Experimental from "@site/docs/common/_experimental.md";
+import CodeExample from "@site/src/components/CodeExample";
+
+# Explicit attributes declaration
+
+<Experimental />
+
+While attributes are automatically extracted from your markup based on `data-attribute` attributes, you also have the ability to define them using the `<block-attribute>` element.
+
+| Options              | Description                                                            |
+| -------------------- | ---------------------------------------------------------------------- |
+| `name`               | The name of the attribute that will be added to `block.json`           |
+| `type` (optional)    | The type of the attribute (`string`, `boolean`, `number` or `integer`) |
+| `default` (optional) | The default value of the attribute                                     |
+
+If no `type` is set, HTML To Gutenberg will set it to a best guest based on the `default` value. If no default is set, the `type` defaults to `string`.
+
+<CodeExample>
+  ```
+  <section>
+    <block-attribute name="title"></block-attribute>
+    <block-attribute
+      name="isOpen"
+      type="boolean"
+      default="false"
+    ></block-attribute>
+    <block-attribute name="numberOfPosts" default="12"></block-attribute>
+    <block-attribute name="rating" default="4.5"></block-attribute>
+  </section>
+  ```
+</CodeExample>
diff --git a/docs/docs/experimental/raw-javascript-expressions.mdx b/docs/docs/experimental/raw-javascript-expressions.mdx
@@ -5,12 +5,13 @@ import CodeExample from "@site/src/components/CodeExample";
 
 <Experimental />
 
-Using the special `$$...$$` escape sequence, it is possible to use raw javascript expressions inside the editor.
+Using the special `$$...$$` escape sequence, it is possible to use raw javascript expressions inside the editor for every elements attributes.
+
+To use a raw JSX expression anywhere else, you can use the `$$$...$$$` escape sequence as a last resort. Please keep in mind that this is still an experimental API and is subject to changes.
 
 <CodeExample>
   ```
   <section>
-    <!-- This is yet another experimental API not yet implemented, stay tuned... -->
     <block-attribute name="title" type="string"></block-attribute>
     <block-attribute name="postType" default="pages"></block-attribute>
 
@@ -30,6 +31,8 @@ Using the special `$$...$$` escape sequence, it is possible to use raw javascrip
         <option value="posts">Posts</option>
         <option value="pages">Pages</option>
       </select>
+
+      <p>The selected post type is $$${attributes.postType}$$$.</p>
     </div>
 
   </section>
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,13 +1,13 @@
 {
   "name": "@jverneaut/html-to-gutenberg",
-  "version": "1.7.4",
+  "version": "1.7.5",
   "main": "index.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/jverneaut/html-to-gutenberg.git"
   },
   "scripts": {
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "test": "NODE_OPTIONS=\"--experimental-vm-modules --disable-warning=ExperimentalWarning\" jest",
     "start": "node index.js"
   },
   "keywords": [
diff --git a/src/lib/common/getBlockData.js b/src/lib/common/getBlockData.js
@@ -185,7 +185,7 @@ const getBlockData = async (
     }
   });
 
-  // Extract attributes
+  // Extract attributes from data-attributes
   visit(ast, "element", (node) => {
     if (node.properties.dataAttribute) {
       if (node.tagName === "img") {
@@ -215,6 +215,73 @@ const getBlockData = async (
     }
   });
 
+  // Extract attributes from <block-attribute> elements
+  visit(ast, "element", (node) => {
+    if (node.tagName === "block-attribute") {
+      if (node.properties.name) {
+        blockData.attributes[node.properties.name] = {};
+
+        const defaultValue =
+          node.properties.default !== undefined
+            ? utils.parseRawValue(node.properties.default)
+            : undefined;
+
+        if (defaultValue !== undefined) {
+          blockData.attributes[node.properties.name].default = defaultValue;
+        }
+
+        if (node.properties.type !== undefined) {
+          Object.assign(blockData.attributes[node.properties.name], {
+            type: node.properties.type,
+            _internalType: "text",
+          });
+        } else {
+          if (node.properties.default !== undefined) {
+            switch (typeof defaultValue) {
+              case "number":
+                if (Number.isInteger(defaultValue)) {
+                  Object.assign(blockData.attributes[node.properties.name], {
+                    type: "integer",
+                    _internalType: "text",
+                  });
+                } else {
+                  Object.assign(blockData.attributes[node.properties.name], {
+                    type: "number",
+                    _internalType: "text",
+                  });
+                }
+
+                break;
+
+              case "boolean":
+                Object.assign(blockData.attributes[node.properties.name], {
+                  type: "boolean",
+                });
+
+                delete blockData.attributes[node.properties.name]._internalType;
+
+                break;
+
+              default:
+              case "string":
+                Object.assign(blockData.attributes[node.properties.name], {
+                  type: "string",
+                  _internalType: "text",
+                });
+
+                break;
+            }
+          } else {
+            Object.assign(blockData.attributes[node.properties.name], {
+              type: "string",
+              _internalType: "text",
+            });
+          }
+        }
+      }
+    }
+  });
+
   // Extract InnerBlocks data
   visit(ast, "element", (node) => {
     if (node.tagName === "blocks") {
diff --git a/src/lib/common/removeBlockAttributeElements.js b/src/lib/common/removeBlockAttributeElements.js
@@ -0,0 +1,10 @@
+import { remove } from "unist-util-remove";
+
+const removeBlockAttributeElements = (ast) => {
+  // Remove <block-attribute> elements
+  remove(ast, (node) => {
+    return node.tagName === "block-attribute";
+  });
+};
+
+export default removeBlockAttributeElements;
diff --git a/src/lib/printEditJS.js b/src/lib/printEditJS.js
@@ -15,6 +15,7 @@ import addInnerBlocksComponent from "./jsx/addInnerBlocksComponent.js";
 import convertStyleToObject from "./jsx/convertStyleToObject.js";
 import handleDisplayModes from "./jsx/handleDisplayModes.js";
 import addServerSideRenderComponent from "./jsx/addServerSideRenderComponent.js";
+import removeBlockAttributeElements from "./common/removeBlockAttributeElements.js";
 
 const template = `{{#hasContent}}
 import {
@@ -82,7 +83,7 @@ const replaceIsSelectedPlaceholders = (html) =>
     .replaceAll("[/IS_NOT_SELECTED]", "\n)}");
 
 const replaceExpressionsAsStrings = (html) =>
-  html.replaceAll('"$$', "").replaceAll('$$"', "");
+  html.replaceAll('"$$', "").replaceAll('$$"', "").replaceAll("$$$", "");
 
 // Generates the root element props
 const generateRootProps = (blockData) => {
@@ -129,6 +130,7 @@ const printEditJS = async (blockData) => {
     addServerSideRenderComponent,
     convertStyleToObject,
     handleDisplayModes,
+    removeBlockAttributeElements,
   ];
   jsxProcessors.forEach((processor) => processor.call({}, ast, innerBlocks));
 
diff --git a/src/lib/printRenderPHP.js b/src/lib/printRenderPHP.js

-Original file line number
+Diff line change
@@ @@ -0,0 +1,20 @@ @@
 +<section <?php echo get_block_wrapper_attributes(); ?>>
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
++
 +</section>