Custom Content Block

This feature is available with the Plugin for Business plan and higher.

If you're on the Plugin for Startup or Plugin Expansion plan, consider upgrading to access this feature. For more details, visit our pricing page or contact support.

The Custom Block feature in the Topol Plugin empowers developers to extend and personalize the drag-and-drop email editor. Having a custom block feature in an email builder can be beneficial for a few reasons:

• Embed custom HTML or functionality
  Add unique design elements or interactivity that are not available via standard blocks.

• Align with your brand
  Create consistent components that match your company's design language and marketing standards.

• Improve productivity
  Reuse common layouts or design sections without repetitive setup—perfect for newsletters, headers, CTAs, and more.

Creating a Basic Custom Block

You can define a custom block based on existing core types (text, button, image, video, or custom-raw). In this basic example, we define our own custom block within the customBlocks array inside TOPOL_OPTIONS. We specify the type of the custom block, which in this case is text.

customBlocks: [
{
  key: "custom-text-key", // unique ID
  name: "My Customised Text", // visible name in sidebar
  icon: `<svg style="width: 40px; height: 40px;" fill="currentColor" viewBox="0 0 20 20">...</svg>`, // SVG icon
  disabled: false,
  type: "text", // must match a valid Topol block type
  attributes: { // for more details, see INFO section below
    align: "right",
    padding: "10px 10px",
    "line-height": 1.3,
    "css-class": "hide_on_mobile"
  },
  content: "Custom Text block?"
}
]

INFO

You can define all attributes for each block type that exists in the template; you can find all of them here.

Composing Multiple Blocks

Want to combine several blocks into a single drag-and-drop unit? Use the mix type and define the blocks array. In the example above, we combined text and button into a single custom block. Now, when users drag this custom block, it adds both elements simultaneously.

customBlocks: [
{
  key: "custom-mix",
  name: "Custom mixed block",
  icon: "box",
  disabled: false,
  type: "mix",
  blocks: [
    {
      type: "text",
      attributes: {
        align: "left",
      },
      content: "My custom content",
    },
    {
      type: "button",
      attributes: { 
        align: "center",
        "background-color": "#417505",
        color: "#F8E71C",
      },
      content: "Click me!",
    },
  ],
},
]

Modifying and Restricting Attributes

Control and limit which settings can be changed by the user. In the example below, we disabled background color changing and set a default value for the block.

customBlocks: [
{
  key: "custom-text-with-modifier",
  name: "My Customised Text",
  icon: "box",
  type: "button",
  attributes: {
    "font-size": "20px",
    "background-color": {
      value: "#417505",
      disabled: true,
    },
    href: {
      value: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    },
  },
  content: "Watch the video",
},
]

Using Custom HTML with a Custom Dialog

For situations when you need complete control over the block’s structure and interactivity, we offer the ability to insert a custom block featuring an entirely customized HTML structure in the provided custom dialog.

WARNING

We want to clarify that we cannot assume responsibility for the content, security, or performance of custom HTML code that originates outside our official codebase. Users are advised to exercise caution and follow coding best practices when incorporating custom HTML, ensuring compliance with relevant standards and security measures.

customBlocks: [
  {
    key: "custom-block-key",
    name: "My Custom Block", //displayed in menu
    dialog: true, //edit content in dialog (currently only custom dialog)
    icon: "box", // box add rss are baked in, but you can use custom svg as well
    content: "<p>initial content</p>", // custom HTML code
    dialogButtonText: "Open Custom Dialog",
    disabled: false, //disabled button for certian users
  },
];

In the example above, we provided the text "Open Custom Dialog" for the button. When a user clicks the button, the onOpenCustomBlockDialog() callback is fired:

callbacks: {
  onOpenCustomBlockDialog(customBlock) {
    // Open your custom dialog
    // Retreive edited data
    // Access current content via customBlock.content
    const editedContent = prompt("Edit HTML content:", customBlock.content);

    // Once the dialog is closed, we can update the current block using following function
    TopolPlugin.updateCustomBlockContent(editedContent);
  }
}