Merge Tags plugin

This plugin is only available for paid TinyMCE subscriptions.
This feature is only available for TinyMCE 6.2 and later.

The Merge Tags plugin allows the user to insert a merge tag (also known as a personalization token, or a mail merge field).

Merge Tags can be inserted by selecting from a drop-down list when a specified prefix is typed, or selected and inserted from the searchable Merge Tags toolbar menu button.

Once a merge tag is inserted, the plugin leaves a non-editable variable wrapped with a prefix and suffix, making it easily identifiable.

Interactive example

  • TinyMCE

  • HTML

  • JS

  • Edit on CodePen

<textarea id="mergetags">
  <h1>Proposal for Services — {*Client.Name*}</h1>
  <h2>Prepared on {*Proposal.SubmissionDate*}</h2>
  <p>{*Client.Name*},</p>
  <p>As per our discussions on {*Client.LastCallDate*}, please find attached our formal Services Proposal.
  <p>{*Salutation*},</p>
  <p>{*Consultant*}.</p>
</textarea>
tinymce.init({
  selector: "textarea#mergetags",
  plugins: "powerpaste a11ychecker linkchecker wordcount table advtable editimage autosave advlist anchor advcode image link lists media mediaembed searchreplace visualblocks template mergetags",
  toolbar: "mergetags | undo redo | styles | bold italic underline | link | align bullist numlist",
  mergetags_prefix: '{*',
  mergetags_suffix: '*}',
  mergetags_list: [
    {
      title: 'Client',
      menu: [
        {
          value: 'Client.LastCallDate',
          title: 'Call date'
        },
        {
          value: 'Client.Name',
          title: 'Client name'
        }
      ]
    },
    {
      title: 'Proposal',
      menu: [
        {
          value: 'Proposal.SubmissionDate',
          title: 'Submission date'
        }
      ]
    },
    {
      value: 'Consultant',
      title: 'Consultant'
    },
    {
      value: 'Salutation',
      title: 'Salutation'
    }
  ]
});

Basic setup

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'mergetags',
  toolbar: 'mergetags',
  mergetags_list: [
    {
      title: 'Example merge tags list',
      menu: [
        {
          value: 'Example.1',
          title: 'Example one'
        },
        {
          value: 'Example.2',
          title: 'Example two'
        }
      ]
    }
  ]
});

The Merge Tags plugin provides an autocompleter for adding a merge tag without using the toolbar button or menu item.

The autocompleter is triggered by typing a specified prefix, controlled by the mergetags_prefix option.

By default, this prefix is {{.

Entering characters after the prefix begins filtering the Merge Tags list.

Using Merge Tags

  1. Merge Tags contents are non-editable but can have any inline-formats applied to them.

    For example, a merge tag can be set to any available typeface, type-size, foreground or background color, or can be set to bold, or italic.

  2. Merge Tags can be changed.

    A selected merge tag can be changed to any other merge tag by using the Merge Tags toolbar menu button.

  3. Text that matches an existing merge tag will be recognised as a merge tag when it is pasted or otherwise inserted into a TinyMCE document.

    Content containing the specified prefix and suffix, and matching a specified merge tag, will be inserted as a merge tag when pasted into the editor. For example, if Sender.Firstname is a merge tag value, and the merge tag prefix and suffix have their default values, adding the string, {{Sender.FirstName}}, to a TinyMCE document will result in the string automatically being recognised as a merge tag.

  4. Merge Tags can be nested within the mergetags_list option.

    The mergetags_list option allows for the specification of a nested menu item within the Merge Tags toolbar menu button. This option allows any number of nested menus and items for merge tag categorisation.

Styling Merge Tags

It’s possible to change the visual appearance of the Merge Tags within the editor using a custom CSS file provided through the content_css option. Here is an example of how to style the Merge Tags elements.

.mce-content-body .mce-mergetag:hover {
    background-color: rgba(0, 108, 231, .1);
}

.mce-content-body .mce-mergetag-affix {
    background-color: rgba(0, 108, 231, .1);
    color: #006ce7;
}

Here is an example of the Merge Tags HTML structure.

<span class="mce-mergetag">
  <span class="mce-mergetag-affix">{{</span>
    some.mergetag
  <span class="mce-mergetag-affix">}}</span>
</span>

Merge Tags and the Advanced Templates Insertion Point Marker

This feature is only available for TinyMCE 6.7 and later.

The Advanced Templates Premium plugin can use a fixed string — {{mce-cursor}} — to set the insertion point within a template as the template is added to a TinyMCE document.

This fixed string uses the same default delimiting characters as individual merge tags use by default. It does not, however, interfere or otherwise interact with any Merge Tags configuration.

The Advanced Templates plugin removes the Insertion Point Marker string before inserting a template containing the string in to a TinyMCE instance.

Consequently, the Advanced Templates Insertion Point Marker string is never seen by the Merge Tags plugin.

It is, therefore, possible to use the Insertion Point Marker string — {{mce-cursor}} — as a merge tag. It is not recommended, however. Aside from being an unlikely merge tag string, the potential for confusion is reason enough to avoid duplication across purposes.

Options

mergetags_prefix

This option specifies the prefix to be attached to each merge tag.

Whatever this option is set to, when it is typed, it triggers the Merge Tags autocompleter within the editor.

Type: String

Default value: {{

Example: using mergetags_prefix

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'mergetags',
  toolbar: 'mergetags',
  mergetags_prefix: '{{'
});
Whatever character or characters are set as the Merge Tags prefix, it or they must be different to the characters set as the Merge Tags suffix. For example, if the Merge Tags prefix is set to %, the Merge Tags suffix cannot also be %.

mergetags_suffix

This option specifies the suffix to be attached to each merge tag.

Type: String

Default value: }}

Example: using mergetags_suffix

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'mergetags',
  toolbar: 'mergetags',
  mergetags_suffix: '}}'
});
Whatever character or characters are set as the Merge Tags suffix, it or they must be different to the characters set as the Merge Tags prefix. For example, if the Merge Tags suffix is set to %, the Merge Tags prefix cannot also be %.

mergetags_list

mergetags_list is an object array that specifies the menu content used for merge tags insertion. Every object specifies the configuration of a submenu or a menu item.

If the mergetags_list option is not set, or contains no entries, both the Merge Tags toolbar button and the Merge Tags menu item are hidden. Merge tag autosuggestions are also disabled if the mergetags_list option is not set, or contains no entries.

Type: Array

Name Type Required Description

title

string

optional

If set: the menu item label to display instead of the value.

value

string

required

The merge tag content to be inserted after the menu item is activated.
Name Type Required Description

title

string

required

The submenu label to display.

menu

Array

required

The list of nested submenus and menu items.

Example: using mergetags_list

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'mergetags',
  toolbar: 'mergetags',
  mergetags_list: [
    {
      value: 'Current.Date',
      title: 'Current date in DD/MM/YYYY format'
    },
    {
      value: 'Current.Time',
    },
    {
      title: 'Person',
      menu: [
        {
          value: 'Person.Name.First',
          title: 'first name'
        },
        {
          value: 'Person.Name.Last',
          title: 'last name'
        },
        {
          value: 'Person.Name.Full',
          title: 'full name'
        },
        {
          title: 'Email',
          menu: [
            {
              value: 'Person.Email.Work'
            },
            {
              value: 'Person.Email.Home'
            }
          ]
        }
      ]
    }
  ]
});

Toolbar buttons

The Merge Tags plugin provides the following toolbar buttons:

Toolbar button identifier Description

mergetags

Menu toolbar button containing merge tags as a drop down list of nested menus and items. This list is specified by the mergetags_list option. When a merge tag is chosen from the menu it is then inserted into the content. This button also includes a search field for finding specific merge tags.

These toolbar buttons can be added to the editor using:

The Merge Tags plugin provides the following menu items:

Menu item identifier Default Menu Location Description

mergetags

Insert

Inserts a merge tag from a nested menu. The nested menu contains the Merge Tags list, as specified in mergetags_list

These menu items can be added to the editor using: