Skip to main content

Block Studio & Widget Elements

Block Studio is a powerful visual editor that allows you to create reusable email components called "Widget Elements". It provides a no-code solution for building complex email templates while maintaining brand consistency and ease of use.

What is a Widget Element?​

A Widget Element is a specialized component created through Block Studio that:

  • Combines multiple basic elements into a cohesive unit
  • Provides a simplified configuration interface
  • Controls which properties users can modify
  • Maintains design consistency across templates

The key advantage is that everything can be done through drag-and-drop editing in Block Studio - no coding required.

Block Studio Features​

  • Visual Editor: Drag-and-drop interface for creating Widget Elements
  • Configuration Panel: Define which options users can customize
  • Preview Mode: See exactly how your Widget Element will look
  • JSON Export: Widget Elements can be exported as JSON for direct editing or programmatic manipulation

Live Demo​

Experience Block Studio in action:

Use Cases​

  • Configure a complex template, but only need the user to fill in a few configuration items, such as a unified color and font size.
  • Configure some immutable blocks, such as the unsubscribe link cannot be modified, but allow modification of certain parts.
  • Configure some fixed blocks, such as setting a heading element, but the font-size can only choose a few options like large, medium, and small.
  • Different templates typically feature product components with varying styles. Although the styles differ, users can select products to change the necessary information.
  • Enable design teams to create base templates while allowing end-users to only fill in specific content, maintaining brand consistency while simplifying content creation.
  • All of the above functionality can be achieved through custom blocks, but Widget blocks allow you to implement these features without writing any code, making it accessible to non-technical users.

Understanding Widget Blocks​

Widget blocks allow you to:

  • Create complex components with a simple configuration interface
  • Hide the complexity of multiple nested elements
  • Provide users with only the options they need to customize
  • Maintain design consistency while allowing flexibility

Widget Block Structure​

Here is a simple example of a widget element:

{
  "type": "section_widget",
  "title": "New widget",
  "data": {
    "name": "New widget",
    "description": "Your custom widget",
    "contentEditable": true,
    "config": [
      {
        "label": "Primary color",
        "name": "primary-color",
        "helpText": "",
        "type": "color",
        "description": "Primary color"
      },
      {
        "label": "Font Size",
        "name": "font-size",
        "helpText": "",
        "type": "pixel"
      }
    ],
    "input": {
      "background-color": "red",
      "primary-color": "#d3943c",
      "font-size": "18px"
    }
  },
  "attributes": {},
  "children": [
    {
      "type": "standard-section",
      "data": {},
      "attributes": {},
      "children": [
        {
          "type": "standard-column",
          "data": {},
          "attributes": {},
          "children": [
            {
              "type": "standard-image",
              "data": {},
              "attributes": {
                "src": "https://res.cloudinary.com/djnkpbshx/image/upload/v1696845725/easy-email-pro-test/bjnjpwmqdunbwhgs6jdf.jpg",
                "border-radius": "50px",
                "border-enabled": true,
                "border-style": "solid",
                "border-width": "5px",
                "border-color": "$var(primary-color)"
              },
              "children": [
                {
                  "text": ""
                }
              ]
            },
            {
              "type": "standard-button",
              "data": {
                "content": "Button"
              },
              "attributes": {
                "width": "100%",
                "background-color": "$var(primary-color)",
                "font-size": "$var(font-size)"
              },
              "children": [
                {
                  "text": "Click"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "name": "Image with text"
}

Static Logic Feature​

Widget blocks support a "Static Logic" feature through the staticLogicEnabled property. This feature provides the following capabilities:

  • Can only be enabled when contentEditable is set to false
  • When enabled, display logic (Iteration and Condition) will render based on the input values during block editing, rather than dynamic data
  • Supports direct use of template engine syntax
  • Particularly useful for creating product lists and other repeatable content with static preview

Here's an example of a product list widget with static logic enabled:

{
  "type": "section_widget",
  "title": "Product",
  "data": {
    "description": "",
    "staticLogicEnabled": true,
    "config": [
      {
        "label": "Product List",
        "name": "products",
        "type": "product_list_picker"
      }
      // ... other config fields ...
    ],
    "input": {
      "products": [
        {
          "id": "10",
          "title": "Product #10",
          "price": "$510"
          // ... other product properties ...
        }
      ]
      // ... other input values ...
    }
  },
  "children": [
    // ... template structure ...
  ]
}

In this example:

  • The staticLogicEnabled: true enables static logic rendering
  • Product information is rendered using template syntax (e.g., {{product.title}})
  • The iteration logic is defined in the column's logic property and will use the static input data for preview
  • Users can see exactly how their product list will look during editing

Key Components:​

  • data:

    • contentEditable: Indicates whether the user can edit the text content within the widget
    • staticLogicEnabled: When set to true (and contentEditable is false), enables static preview of dynamic content using template syntax and input values
    • config: Defines the user's configuration items (what they can edit), including:
      • Field type (color, pixel, product_picker, etc.)
      • Field label and name
      • Help text and descriptions
      • Validation rules and requirements
    • input: Contains the values of the user's configuration options, used for:
      • Storing user-selected values
      • Providing default values
      • Static preview data when staticLogicEnabled is true
    • name: Widget identifier for reference
    • description: Helpful text explaining the widget's purpose

  • children:

    • Contains the UI rendering structure
    • Supports nested elements and components
    • Can reference variables from input using:
      • $var(variableName) for config values
      • {{variableName}} for template syntax when staticLogicEnabled is true
    • Supports logic properties for iteration and conditional rendering

  • attributes:

    • Stores element-specific attributes
    • Can reference configuration variables
    • Controls element styling and behavior

This structure enables:

  • Clear separation of configuration and presentation
  • Flexible template customization
  • Dynamic content preview
  • Maintainable and reusable widget definitions

Custom Fields​

We have built-in several commonly used fields, but they certainly cannot meet the needs of all users. So we allow users to customize the fields they need.

Register Custom Field​

import { WidgetTypeOptions, AttributeField } from "easy-email-pro-theme";
WidgetTypeOptions.push({
  value: "product_picker",
  label: "Product Picker",
});

const OldFieldItem = AttributeField.FieldItem;
AttributeField.FieldItem = (props) => {
  if (props.type === "product_picker") {
    return <ProductPicker {...props} />;
  }
  return <OldFieldItem {...props} />;
};

For full code examples and implementation details, check out our live demo.