Hey there! Let's fix that Page Builder compatibility issue for your custom widget. The problem here is that the basic widget template from the tutorial doesn't include the JSON Schema metadata that Page Builder needs to recognize and render the widget properly. Here's how to update your setup step by step:

1. Update Your Widget Template with a Page Builder-Compatible Schema #

Page Builder requires a schema field in your widget template definition. This schema tells Page Builder what configuration options your widget has, what data types they are, and how to render the visual editing interface for them.

Modified POST/PUT Request Body for Widget Template #

Use this updated payload (you can either send a PUT request to your existing template's endpoint, or delete the old one and re-POST it):

{
  "name": "Header Images",
  "template": "<div class=\"header-images-widget\">{{#each images}}<a href='{{image_url}}'><img src='{{image_source}}' style='width:33.3%' alt='Header image'/></a>{{/each}}</div>",
  "schema": {
    "type": "object",
    "properties": {
      "images": {
        "type": "array",
        "title": "Header Image Gallery",
        "items": {
          "type": "object",
          "title": "Image Item",
          "properties": {
            "image_url": {
              "type": "string",
              "title": "Link Target URL",
              "format": "uri",
              "description": "URL the image will link to"
            },
            "image_source": {
              "type": "string",
              "title": "Image File",
              "format": "image-url",
              "description": "Select or upload an image for the header"
            }
          },
          "required": ["image_url", "image_source"]
        }
      }
    },
    "required": ["images"]
  }
}

Key changes here:

• Added a wrapping <div> to the template for consistent structure (Page Builder prefers widgets to have a single root element)
• Fixed the src attribute in the <img> tag to include quotes (valid HTML is critical for Page Builder compatibility)
• Added a comprehensive schema that defines:
  • The images array as a repeatable list of image items
  • Each item's image_url as a URI/URL field
  • Each item's image_source as an image picker field (Page Builder will render a visual image selector for this)

2. Refresh Your Widget (Optional but Recommended) #

If you already created a widget using the old template, you can either:

• Update the existing widget via a PUT request to /v3/content/widgets/{widget-uuid} (ensure it uses the updated template's UUID)
• Delete the old widget and create a new one with the same configuration, pointing to your updated template

3. Test in Page Builder #

After updating the template and widget, clear your store's cache (if applicable), then reopen Page Builder. You should now be able to add your widget without the compatibility error, and you'll see a visual configuration panel to edit the images and links directly in Page Builder.

Why This Works #

The official widget tutorial focuses on basic widget functionality, but Page Builder relies on the schema metadata to understand how to integrate the widget into its drag-and-drop interface. Without the schema, Page Builder can't validate the widget's configuration or render the editing controls, hence the error message you saw.

内容的提问来源于stack exchange，提问作者Amy