Blocks: Upgrade to apiVersion 3

.env.example

@@ -5,8 +5,13 @@ WORDPRESS_ROOT_DIR="/Users/tim/Local Sites/convertkit-github/app/public"
 WORDPRESS_URL=http://kit.local
 
 # Local site DB SQL dump file
+# Set to `tests/Support/Data/dump-6.2.8.sql` when testing in WordPress 6.2.8 or older i.e. to test apiVersion 2 blocks
 WORDPRESS_DB_SQL_DUMP_FILE="tests/Support/Data/dump.sql"
 
+# Use apiVersion 3 of the block editor
+# Set to `false` when testing in WordPress 6.2.8 or older i.e. to test apiVersion 2 blocks
+WORDPRESS_V3_BLOCK_EDITOR_ENABLED=true
+
 # Kit credentials
 CONVERTKIT_OAUTH_ACCESS_TOKEN=
 CONVERTKIT_OAUTH_REFRESH_TOKEN=

.github/workflows/tests-backward-compat.yml

@@ -29,6 +29,7 @@ jobs:
       DB_USER: root
       DB_PASS: root
       DB_HOST: localhost
+      WORDPRESS_V3_BLOCK_EDITOR_ENABLED: false # Test apiVersion 2 blocks against WordPress 6.2.8
       WORDPRESS_DB_SQL_DUMP_FILE: tests/Support/Data/dump-6.2.8.sql # Used to populate the test site database for WordPress 6.2.8
       INSTALL_PLUGINS: "autoptimize debloat litespeed-cache rocket-lazy-load sg-cachepress" # Don't include this repository's Plugin here.
       INSTALL_PLUGINS_URLS: "http://cktestplugins.wpengine.com/wp-content/uploads/2024/11/disable-doing-it-wrong-notices.zip https://downloads.wordpress.org/plugin/block-visibility.3.3.0.zip https://downloads.wordpress.org/plugin/jetpack-boost.3.5.0.zip" # URLs to specific third party Plugins or versions that support WordPress 6.2.8
@@ -134,7 +135,7 @@ jobs:
       - name: Install Paid Third Party WordPress Plugins
         working-directory: ${{ env.ROOT_DIR }}
         run: wp-cli plugin install ${{ secrets.CONVERTKIT_PAID_PLUGIN_URLS }}
-        
+
       # Move Plugin
       - name: Move Plugin
         run: mv /home/runner/work/convertkit-wordpress/convertkit-wordpress/convertkit ${{ env.PLUGIN_DIR }}
@@ -244,6 +245,7 @@ jobs:
         with:
           path: ${{ env.PLUGIN_DIR }}/.env.testing
           contents: |
+            WORDPRESS_V3_BLOCK_EDITOR_ENABLED=${{ env.WORDPRESS_V3_BLOCK_EDITOR_ENABLED }}
             WORDPRESS_DB_SQL_DUMP_FILE=${{ env.WORDPRESS_DB_SQL_DUMP_FILE }}
             CONVERTKIT_API_KEY=${{ env.CONVERTKIT_API_KEY }}
             CONVERTKIT_API_SECRET=${{ env.CONVERTKIT_API_SECRET }}

.github/workflows/tests.yml

@@ -30,7 +30,8 @@ jobs:
       DB_USER: root
       DB_PASS: root
       DB_HOST: localhost
-      WORDPRESS_DB_SQL_DUMP_FILE: tests/Support/Data/dump.sql # Used to populate the test site database for WordPress 6.2.8
+      WORDPRESS_V3_BLOCK_EDITOR_ENABLED: true
+      WORDPRESS_DB_SQL_DUMP_FILE: tests/Support/Data/dump.sql
       INSTALL_PLUGINS: "admin-menu-editor autoptimize beaver-builder-lite-version block-visibility contact-form-7 classic-editor custom-post-type-ui debloat elementor forminator jetpack-boost mailchimp-for-wp rocket-lazy-load woocommerce wordpress-seo wpforms-lite litespeed-cache wp-crontrol wp-super-cache w3-total-cache wp-fastest-cache wp-optimize sg-cachepress" # Don't include this repository's Plugin here.
       INSTALL_PLUGINS_URLS: "https://downloads.wordpress.org/plugin/convertkit-for-woocommerce.1.6.4.zip http://cktestplugins.wpengine.com/wp-content/uploads/2024/01/convertkit-action-filter-tests.zip http://cktestplugins.wpengine.com/wp-content/uploads/2024/11/disable-doing-it-wrong-notices.zip http://cktestplugins.wpengine.com/wp-content/uploads/2025/03/uncode-js_composer.7.8.zip http://cktestplugins.wpengine.com/wp-content/uploads/2025/03/uncode-core.zip" # URLs to specific third party Plugins
       INSTALL_THEMES_URLS: "http://cktestplugins.wpengine.com/wp-content/uploads/2025/03/uncode.zip http://cktestplugins.wpengine.com/wp-content/uploads/2025/04/Divi.zip"
@@ -266,6 +267,7 @@ jobs:
         with:
           path: ${{ env.PLUGIN_DIR }}/.env.testing
           contents: |
+            WORDPRESS_V3_BLOCK_EDITOR_ENABLED=${{ env.WORDPRESS_V3_BLOCK_EDITOR_ENABLED }}
             WORDPRESS_DB_SQL_DUMP_FILE=${{ env.WORDPRESS_DB_SQL_DUMP_FILE }}
             CONVERTKIT_API_KEY=${{ env.CONVERTKIT_API_KEY }}
             CONVERTKIT_API_SECRET=${{ env.CONVERTKIT_API_SECRET }}

TESTING.md

@@ -339,6 +339,29 @@ the Helper's namespace and class under the `enabled` section.
 
 Need to change how Codeception runs?  Edit the [codeception.dist.xml](codeception.dist.xml) file.
 
+## Block Testing
+
+To locally test that Kit Blocks are compatible with apiVersion 2, use the following configuration in `.env.testing`:
+
+| Environment Variable | Value |
+|----------------------|-------|
+| `WORDPRESS_DB_SQL_DUMP_FILE` | `tests/Support/Data/dump-6.2.8.sql` |
+| `WORDPRESS_V3_BLOCK_EDITOR_ENABLED` | `false` |
+
+To locally test that Kit Blocks are compatible with apiVersion 3, use the following configuration in `.env.testing`:
+
+| Environment Variable | Value |
+|----------------------|-------|
+| `WORDPRESS_DB_SQL_DUMP_FILE` | `tests/Support/Data/dump.sql` |
+| `WORDPRESS_V3_BLOCK_EDITOR_ENABLED` | `true` |
+
+GitHub Actions are configured to automatically configure the hosted runner with the applicable SQL dump file and block editor version:
+
+| Workflow File | Description |
+|---------------|-------------|
+| `tests-backward-compat.yml` | Runs tests against WordPress 6.2.8, with apiVersion `2` for blocks |
+| `tests.yml` | Runs tests against the latest WordPress version, with apiVersion `3` for blocks |
+
 ## Writing a WordPress Unit Test
 
 WordPress Unit tests provide testing of Plugin specific functions and/or classes, typically to assert that they perform as expected

includes/blocks/v3/broadcasts/block.json

@@ -0,0 +1,75 @@
+{
+    "$schema": "https://schemas.wp.org/trunk/block.json",
+    "apiVersion": 3,
+    "name": "convertkit/broadcasts",
+    "title": "Kit Broadcasts",
+    "category": "kit",
+    "description": "Displays a list of your Kit broadcasts.",
+    "keywords": [ "convertkit", "kit", "broadcasts", "posts" ],
+    "textdomain": "convertkit",
+    "attributes": {
+        "display_grid": {
+            "type": "boolean"
+        },
+        "date_format": {
+            "type": "string"
+        },
+        "display_image": {
+            "type": "boolean"
+        },
+        "display_description": {
+            "type": "boolean"
+        },
+        "display_read_more": {
+            "type": "boolean"
+        },
+        "read_more_label": {
+            "type": "string"
+        },
+        "limit": {
+            "type": "number"
+        },
+        "page": {
+            "type": "number"
+        },
+        "paginate": {
+            "type": "boolean"
+        },
+        "paginate_label_prev": {
+            "type": "string"
+        },
+        "paginate_label_next": {
+            "type": "string"
+        },
+        "style": {
+            "type": "object"
+        },
+        "backgroundColor": {
+            "type": "string"
+        },
+        "textColor": {
+            "type": "string"
+        },
+        "is_gutenberg_example": {
+            "type": "boolean",
+            "default": false
+        }
+    },
+    "supports": {
+        "className": true,
+        "color": {
+            "link": true,
+            "background": true,
+            "text": true
+        },
+        "typography": {
+            "fontSize": true,
+            "lineHeight": true
+        },
+        "spacing": {
+            "margin": true,
+            "padding": true
+        }
+    },
+    "editorScript": "convertkit-gutenberg"
+}

includes/blocks/v3/form-builder-field-custom/block.json

@@ -0,0 +1,57 @@
+{
+    "$schema": "https://schemas.wp.org/trunk/block.json",
+    "apiVersion": 3,
+    "name": "convertkit/form-builder-field-custom",
+    "title": "Kit Form Builder: Custom Field",
+    "category": "kit",
+    "description": "Adds a text field to the Kit Form Builder, whose value is stored in a Kit custom field.",
+    "keywords": [
+        "convertkit",
+        "kit",
+        "custom",
+        "field"
+    ],
+    "textdomain": "convertkit",
+    "parent": [ "convertkit/form-builder" ],
+    "attributes": {
+        "label": {
+            "type": "string"
+        },
+        "custom_field": {
+            "type": "string"
+        },
+        "fontSize": {
+            "type": "string"
+        },
+        "style": {
+            "type": "object"
+        },
+        "backgroundColor": {
+            "type": "string"
+        },
+        "textColor": {
+            "type": "string"
+        },
+        "is_gutenberg_example": {
+            "type": "boolean",
+            "default": false
+        }
+    },
+    "supports": {
+        "align": true,
+        "className": true,
+        "color": {
+            "background": true,
+            "text": true
+        },
+        "typography": {
+            "fontSize": true,
+            "lineHeight": true
+        },
+        "spacing": {
+            "margin": true,
+            "padding": true
+        }
+    },
+    "editorScript": "convertkit-gutenberg"
+}

includes/blocks/v3/form-builder-field-email/block.json

@@ -0,0 +1,54 @@
+{
+    "$schema": "https://schemas.wp.org/trunk/block.json",
+    "apiVersion": 3,
+    "name": "convertkit/form-builder-field-email",
+    "title": "Kit Form Builder: Email Field",
+    "category": "kit",
+    "description": "Adds an email field to the Kit Form Builder.",
+    "keywords": [
+        "convertkit",
+        "kit",
+        "email",
+        "field"
+    ],
+    "textdomain": "convertkit",
+    "parent": [ "convertkit/form-builder" ],
+    "attributes": {
+        "label": {
+            "type": "string"
+        },
+        "fontSize": {
+            "type": "string"
+        },
+        "style": {
+            "type": "object"
+        },
+        "backgroundColor": {
+            "type": "string"
+        },
+        "textColor": {
+            "type": "string"
+        },
+        "is_gutenberg_example": {
+            "type": "boolean",
+            "default": false
+        }
+    },
+    "supports": {
+        "align": true,
+        "className": true,
+        "color": {
+            "background": true,
+            "text": true
+        },
+        "typography": {
+            "fontSize": true,
+            "lineHeight": true
+        },
+        "spacing": {
+            "margin": true,
+            "padding": true
+        }
+    },
+    "editorScript": "convertkit-gutenberg"
+}

includes/blocks/v3/form-builder-field-name/block.json

@@ -0,0 +1,54 @@
+{
+    "$schema": "https://schemas.wp.org/trunk/block.json",
+    "apiVersion": 3,
+    "name": "convertkit/form-builder-field-name",
+    "title": "Kit Form Builder: Name Field",
+    "category": "kit",
+    "description": "Adds a name field to the Kit Form Builder.",
+    "keywords": [
+        "convertkit",
+        "kit",
+        "name",
+        "field"
+    ],
+    "textdomain": "convertkit",
+    "parent": [ "convertkit/form-builder" ],
+    "attributes": {
+        "label": {
+            "type": "string"
+        },
+        "fontSize": {
+            "type": "string"
+        },
+        "style": {
+            "type": "object"
+        },
+        "backgroundColor": {
+            "type": "string"
+        },
+        "textColor": {
+            "type": "string"
+        },
+        "is_gutenberg_example": {
+            "type": "boolean",
+            "default": false
+        }
+    },
+    "supports": {
+        "align": true,
+        "className": true,
+        "color": {
+            "background": true,
+            "text": true
+        },
+        "typography": {
+            "fontSize": true,
+            "lineHeight": true
+        },
+        "spacing": {
+            "margin": true,
+            "padding": true
+        }
+    },
+    "editorScript": "convertkit-gutenberg"
+}