Premade Blocks

Premade blocks enable users to swiftly insert predefined sections, such as headers or footers, into their emails.

You can define premade blocks by using the premadeBlocks array in the TOPOL_OPTIONS object. There, you define one or more collections of premade blocks as individual objects. Each collection object includes a name of this collection and a blocks array, where the individual blocks of this collection are defined as objects.

In this example, the premadeBlocks array contains two collections, each with a single premade block.

premadeBlocks: [
      {
        name: "Premade Blocks Collection 1", // First collection of premade blocks
        blocks: [ // Premade block(s) within this collection
          {
            img: "https://placehold.co/600x400?text=Premade+Block", // Image URL, recommended width > 330px
            name: "Premade Block 1", // Used if no Image URL is provided
            definition: [
              {
                tagName: "mj-section",
                attributes: {
                  "full-width": "600px",
                  padding: "10px 10px",
                  "mj-class": "section",
                },
                children: [
                  {
                    tagName: "mj-column",
                    attributes: { width: "100%", "vertical-align": "top" },
                    children: [
                      {
                        tagName: "mj-image",
                        attributes: {
                          src: "https://placehold.co/600x400?text=Image",
                          href: "https://yourwebsite.com",
                          alt: "Logo",
                          padding: "0px 0px 0px 0px",
                          "fluid-on-mobile": "false",
                          containerWidth: 600,
                        },
                      },
                      {
                        tagName: "mj-text",
                        attributes: {
                          align: "left",
                          padding: "15px 15px 15px 15px",
                          "line-height": 1.5,
                          containerWidth: 600,
                        },
                        content: "This is your premade block from the first collection",
                      },
                    ],
                  },
                ],
              },
            ],
          },
        ],
      },
      {
        name: "Premade Blocks Collection 2", // Second collection of premade blocks
        blocks: [ // Premade block(s) within this collection
          {
            img: "https://placehold.co/600x400?text=Premade+Block",
            name: "Premade Block 2",
            definition: [
              {
                tagName: "mj-section",
                attributes: {
                  "full-width": "600px",
                  padding: "10px 10px",
                  "mj-class": "section",
                },
                children: [
                  {
                    tagName: "mj-column",
                    attributes: { width: "100%", "vertical-align": "top" },
                    children: [
                      {
                        tagName: "mj-image",
                        attributes: {
                          src: "https://placehold.co/600x400?text=Image",
                          href: "https://yourwebsite.com",
                          alt: "Logo",
                          padding: "0px 0px 0px 0px",
                          "fluid-on-mobile": "false",
                          containerWidth: 600,
                        },
                      },
                      {
                        tagName: "mj-text",
                        attributes: {
                          align: "left",
                          padding: "15px 15px 15px 15px",
                          "line-height": 1.5,
                          containerWidth: 600,
                        },
                        content: "This is your premade block from the second collection",
                      },
                    ],
                  },
                ],
              },
            ],
          },
        ],
      },
    ],

Advanced Options

By default, our Plugin includes a selection of premade block examples. You can either replace these examples with your own premade blocks or add your blocks alongside the existing examples. This behavior is controlled using the override option, which is a boolean:

• If true, the editor will remove the default examples and display only your custom premade blocks.

• If false, the editor will retain the default examples and append your custom blocks to the list.

To configure this option, update the basic premadeBlocks structure to the following advanced structure:

premadeBlocks: {
  blocks: PremadeBlocks[], // array of your premade blocks as objects
  override: boolean // false if omitted
}

Transforming Basic Structure to Advanced Structure

Basic structure without the override option:

premadeBlocks: [
  {
    name: "Premade Blocks Collection 1",
    blocks: [
      {
        img: "https://placehold.co/600x400?text=Premade+Block",
        name: "Premade Block 1",
        definition: [
          {
            // tagName, attributes, children...
          },
        ],
      },
    ],
  },
],

Advanced structure with the override option:

premadeBlocks: {
  blocks: [
    {
      name: "Premade Blocks Collection 1",
      blocks: [
        {
          img: "https://placehold.co/600x400?text=Premade+Block",
          name: "Premade Block 1",
          definition: [
            {
              // tagName, attributes, children...
            },
          ],
        },
      ],
    },
  ],
  override: false,
},

If you use this structure but do not specify the override option, it will automatically default to false.

If you prefer not to use premade blocks at all, you can disable the feature entirely by setting premadeBlocks to false:

premadeBlocks: false,

Loading Specific Premade Block Examples

By default, the Topol Plugin initializes with a full set of premade block examples. The override option determines whether all or none of these examples are loaded — currently, there is no built-in support to load only selected examples automatically.

If you'd like to load only specific premade block examples, follow these steps:

1. Use the advanced configuration structure and set the override option to true.
2. Visit this GitHub Gist page, which contains the full definitions of all available premade block examples.
3. Identify the blocks you'd like to use, then copy and paste their definitions into your premadeBlocks configuration.