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. Custom blocks can either replace those examples or sit alongside them, controlled by the boolean override option:

• If true, the editor removes the default examples and displays only your custom premade blocks.

• If false, the editor keeps the default examples and places your custom collections before them in 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 // 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.

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

The Topol Plugin initializes with a full set of premade block examples. The override option decides whether all or none of those examples load, and there is no built-in way to load only a selected few.

To use only specific examples:

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.