Skip to content

Custom block

Having a custom block feature in an email builder can be beneficial for a few reasons:

  • It allows developers to insert their own custom HTML code into the email. This can be useful if they want to add specific functionality or design elements that are not available through the email builder's pre-designed blocks.

  • Custom blocks allow developers to tailor the email builder to their specific needs and requirements. They can create blocks that fit the design and branding of their company, rather than being limited to the options provided by the email builder.

Create your own composed blocks

With this option you can re-use existing core blocks, set default values for the blocks, disable certain attributes, or write custom validator for certain attributes.

You can currently extend the functionality of button, text, custom-raw, image and video

Basic example

Let's see how would Custom Text Block looks

js
{
  // provide unique id for each custom block
  key: "custom-text-key",
  name: "My Customised Text",
  // custom svg icon
  icon: `
      <svg style="width: 40px; height: 40px;" fill="currentColor" viewBox="0 0 20 20" xmlns="http://www.w3.org/200svg" aria-hidden="true">
      <path clip-rule="evenodd" fill-rule="evenodd" d="M2 3a1 1 0 00-1 1v1a1 1 0 001 1h16a1 1 0 001-1V4a1 1 00-1-1H2zm0 4.5h16l-.811 7.71a2 2 0 01-1.99 1.79H4.802a2 2 0 01-1.99-1.79L2 7.5zM10 9a.75.75 0 01.75.75v2.546943-1.048a.75.75 0 111.114 1.004l-2.25 2.5a.75.75 0 01-1.114 0l-2.25-2.5a.75.75 0 111.114-1.004l.943 1.048V75A.75.75 0 0110 9z"></path>
    </svg>
  `,
  disabled: false,
  type: "text",
  attributes: {
    align: "right",
    padding: "10px 10px",
    "line-height": 1.3,
    "css-class": "hide_on_mobile",
  },
  content: "Custom Text block?",
},

In the example above, we define our own custom block, we define type of the custom block, which in this case is text you can define all attributes that exist in the template, you can find all of them here.

Composing more blocks together

Let's say you need to create more blocks at once with a single drag and drop operation. We use a type: mix to achieve this and define all blocks in the blocks array.

js
{
  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!",
    },
  ],
},

In the example above, we composed text and button together in one custom block. Now, when users drags this custom blocks it will add both of blocks at once.

Attributes modifiers

Modifiers for attributes can disable or validate certain attributes in the custom block.

js
{
  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",
      validator: (value: string) => {
        return value.includes("youtube.com");
      },
      validatorErrorMessage: "Invalid URL, must contain youtube.com",
    },
  },
  content: "Watch the video",
},

In the example above, we disabled background color changing and set default value for the block. We also added a custom validator with custom error message.

Inserting custom HTML in custom dialog component

We provide an option insert custom block with completely custom HTML structure in the custom dialog provided

WARNING

We want to be clear that we cannot assume responsibility for the content, security, or performance of custom HTML code that originates outside our official codebase. Users are asked to be cautious and adhere to coding best practices when incorporating custom HTML, ensuring its compliance with relevant standards and security measures.

ts
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>",
    dialogButtonText: "Open Custom Dialog",
    disabled: false, //disabled button for certian users
  },
];

When user clicks on the open dialog, in the above example we gave "Open Custom Dialog" text to the button. Following callback is fired:

ts
callbacks: {
    onOpenCustomBlockDialog(customBlock) {
        // open your custom dialog here, retreive edited data
        // you can access current content with customBlock.content
        // once the dialog is closed we can update the current block using following function

        // Example:
        let editedContent = prompt(customBlock.content);
        TopolPlugin.updateCustomBlockContent(editedContent);
    }
}