Merge Tags

Merge tags allow end-users to dynamically add content to their email. Merge tags can be inserted into a block of text by clicking on the "Merge Tags" button in the text editor toolbar. The button is not shown if no merge tags were passed when initializing Unlayer.

We support all types of merge tags. All templating engines are fully supported, whether it uses curly brackets {{ ... }} or square brackets [ ... ] or any other.

This is how it looks if you have merge tags.

Basic Merge Tags

There are 2 ways host application can pass merge tags to Unlayer.

Option 1) You can pass merge tags during initialization like this:

unlayer.init({
  mergeTags: {
    first_name: {
      name: "First Name",
      value: "{{first_name}}",
      sample: "John"
    },
    last_name: {
      name: "Last Name",
      value: "{{last_name}}",
      sample: "Doe"
    }
  }
});

Option 2) You can pass merge tags after initialization like this:

unlayer.setMergeTags({
  first_name: {
    name: "First Name",
    value: "{{first_name}}",
    sample: "John"
  },
  last_name: {
    name: "Last Name",
    value: "{{last_name}}",
    sample: "Doe"
  }
});

Grouped Merge Tags

You can group a set of merge tags inside a sub-menu by passing another mergeTags object inside one.

unlayer.init({
  mergeTags: {
    shipping_address: {
      name: "Shipping Address",
      mergeTags: {
        street_1: {
          name: "Street 1",
          value: "{{shipping_address.address_1}}"
        },
        street_2: {
          name: "Street 2",
          value: "{{shipping_address.address_2}}"
        },
        city: {
          name: "City",
          value: "{{shipping_address.city}}"
        },
        state: {
          name: "State",
          value: "{{shipping_address.state}}"
        },
        zip: {
          name: "Zip",
          value: "{{shipping_address.zip}}"
        }
      }
    }
  }
});

Smart Merge Tags

Smart merge tags are more human-friendly. With this, users will be able to:

• easily identify merge tags within highlighted field
• see human-friendly names instead of code – e.g., Customer Name instead of {{customer.name}}
• select, replace, and style merge tags with one click

It's enabled by default, but you can turn this off.

unlayer.init({
  features: {
    smartMergeTags: false
  }
});

Loops and Conditions

You can use the merge tags to add conditions and looping for dynamic content.

For example, if you want your users to create an order confirmation email template and show all products in that order, you would pass the "Products" merge tags along with some rules. The before and after of the selected rule will be added before and after the block in the exported HTML.

This before and after can be used to create loops or if-then-else conditions. The syntax will depend on which templating engine the host application uses. In this example, we are using Mustache templating engine.

If you want to add conditions to display content to different segments of audience, check Display Conditions.

unlayer.init({
  mergeTags: {
    products: {
      name: "Products",
      rules: {
        repeat: {
          name: "Repeat for Each Product",
          before: "{{#products}}",
          after: "{{/products}}",
        }
      },
      mergeTags: {
        name: {
          name: "Product Name",
          value: "{{name}}"
        },
        image: {
          name: "Product Image",
          value: "{{image}}"
        }
      }
    }
  }
});

Specifying the rules will add an additional icon to the blocks in the editor. This icon will be used to select the merge tag group and rules.

Once you click that icon, it will let users pick a merge tag group and a merge rule, and will show the available merge tags after selection. You can then use those tags any where inside that block.

Sample Preview

You can provide sample values for each merge tag so users can see what the actual email would look like when the values are filled. These sample values are only visible in preview mode.

Simply add a sample attribute to the merge tag. In the example below, {{first_name}} will be replaced with John and {{last_name}} will be replaced with Doe in preview mode.

unlayer.init({
  mergeTags: {
    first_name: {
      name: "First Name",
      value: "{{first_name}}",
      sample: "John"
    },
    last_name: {
      name: "Last Name",
      value: "{{last_name}}",
      sample: "Doe"
    }
  }
});

Autocomplete Menu Trigger

By default, the merge tag autocomplete menu is triggered by the first character of your merge tags. For example, if your merge tags look like {{first_name}}, the trigger will automatically be {.

If you want to change the trigger character, you can do that like this.

unlayer.init({
  mergeTagsConfig: {
    autocompleteTriggerChar: "@"
  }
});

Sorting Merge Tags

By default, merge tags are sorted alphabetically in the menu. You can disable sorting.

unlayer.init({
  mergeTagsConfig: {
    sort: false
  },
})

Replacing with Real Values

📘

When are Merge Tags replaced?

Replacing merge tags with actual values is done at the time of sending the email by the host application. Usually, the HTML should be parsed by your templating engine (Mustache, Nunjucks, etc) and the tags are replaced with real values.

In case you want to replace merge tags with real values at the time of exporting HTML, you can use the following examples.

Values

Replace {{first_name}} with John and {{last_name}} with Doe.

unlayer.exportHtml(function(data) {
  var json = data.design;
  var html = data.html;
}, {
  mergeTags: {
    first_name: 'John',
    last_name: 'Doe'
  }
})

Conditions

The following example can be used to show or hide a block based on a true | false condition.

unlayer.exportHtml(function(data) {
  var json = data.design;
  var html = data.html;
}, {
  mergeTags: {
    products: {
      empty: true
    }
  }
})

Loops

The following example can be used to provide data to a loop.

unlayer.exportHtml(function(data) {
  var json = data.design;
  var html = data.html;
}, {
  mergeTags: {
    products: {
      repeat: [
        { name: 'Item 01' },
        { name: 'Item 02' }
      ]
    }
  }
})

Custom UI

You can extend this feature and allow users of the editor to build or choose merge tags using a UI that you control. For example, you can open a custom modal and show any interface to pick or build merge tags or rules.

Merge Tags

You can use this callback function to show custom UI to pick merge tags.

unlayer.registerCallback('mergeTag', function (data, done) {
  // data - contains current mergeTagGroup, current mergeTagRule and a list of mergeTags
  // done - callback function
  
  // Open custom UI for merge tags here
  // Once your user is done choosing a merge tag, call the "done"
  // callback function with the new merge tag.
  
  done({
    name: 'First Name',
    value: '{{first_name}}',
  });
});

Merge Tag Groups

You can use this callback function to show custom UI to pick merge tag groups and rules.

unlayer.registerCallback('mergeTagRule', function (data, done) {
  // data - contains current mergeTagGroup, current mergeTagRule and a list of mergeTags
  // done - callback function
  
  // Open custom UI for merge tag groups here
  // Once your user is done choosing a merge tag group and rules,
  // call the "done" callback function with the new merge tag group.
  
  // Reset the merge tag group and rules
  // done({
  //   mergeTagGroup: null,
  //   mergeTagRule: null,
  // });
  
  done({
    mergeTagGroup: 'products',
    mergeTagRule: 'repeat',
  });
});