Premade blocks

Premade blocks are prepared sections, such as headers or footers, that users insert into an email in one click.

Define them with the premadeBlocks array in the TOPOL_OPTIONS object. The array holds one or more collections, each an object with a name for the collection and a blocks array containing the individual blocks. A collection name is required and shows as the group heading in the sidebar.

Each block takes a definition (its MJML structure) plus either an img or a name. The editor shows the image when img is set and falls back to the block's name otherwise.

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

The Plugin includes a selection of premade block examples out of the box, grouped as Header, Content, E-commerce and Footer. Custom blocks can either replace those examples or sit alongside them, controlled by the boolean override option:

• If true, the editor removes the default groups and displays only what you list.

• If false, the editor keeps the default groups. Any default group you do not place yourself is appended after your collections, in the order Header, Content, E-commerce, Footer.

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

premadeBlocks: {
  blocks: PremadeBlocks[], // your collections and, optionally, preset markers
  override: boolean // required when using this structure
}

WARNING

override is required in the advanced structure. Omitting it fails validation, which leaves the editor with no premade blocks at all and logs a parsing error. Set it explicitly to false to keep the defaults.

Placing the default groups

To decide where Topol's default groups appear, reference them inside blocks with a preset marker. A marker is an object with a single preset key and one of these values:

preset	Default group
header	Header
content	Content
ecommerce	E-commerce
footer	Footer

The sidebar shows collections and markers in the order they appear in the array. This example puts a custom "Dynamic products" collection between Content and E-commerce:

premadeBlocks: {
  override: false,
  blocks: [
    { preset: "header" },
    { preset: "content" },
    {
      name: "Dynamic products",
      blocks: [
        // your premade blocks
      ],
    },
    { preset: "ecommerce" },
    { preset: "footer" },
  ],
},

A few rules apply:

• A marker is a bare reference. A marker with an extra name or blocks key fails validation. An object carrying all three keys is read as a custom collection, and its preset key is ignored.
• Each preset can be listed once. Listing one twice fails validation.
• Markers work only in the advanced structure. A marker in the basic array fails validation.
• With override: false, a default group you leave out is still appended at the end. With override: true, it is left out.
• The group's name and its blocks follow the editor language, so ecommerce shows as "Produkty" with the Czech block set when the editor runs in Czech.

Like every other validation error on this option, a bad marker leaves the panel empty and logs Error while parsing premade blocks to the console with the failing path.

Transforming the basic structure to the 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,
},

To turn the feature off entirely, set premadeBlocks to false:

premadeBlocks: false,

Loading specific premade block examples

To keep only some of Topol's default groups, set override to true and list the ones you want as preset markers. This keeps only the Footer group next to your own collection:

premadeBlocks: {
  override: true,
  blocks: [
    {
      name: "My collection",
      blocks: [
        // your premade blocks
      ],
    },
    { preset: "footer" },
  ],
},

There is no built-in way to pick individual blocks out of a default group. To use only specific blocks:

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 own collection in premadeBlocks.