You may know them as substitution strings, personalization tokens, or maybe as a mail merge. They look like this: {{Your.Name}} or maybe {{Customer.First.Name}}. What are these things?
They’re merge tags, and they’re useful because you can add them to any text you’re creating that needs to go out to a customer. In production, the merge tags line up with database content that's connected to the merge tags. The merge tags then change to a name or email through an automation process.
The merge tags functionality forms the basis of personalization, at scale.
Merge tags create a personalized experience without you needing to look up and input each individuals’ name and address.. This functionality is very popular in email use cases, but it’s also applicable to any instance where content needs to be personalized on a large scale, and not just name and addresses – for example in document builders, content management systems or even learning management systems.
TinyMCE is a rich text editor that provides a reliable set of functions to help you personalize your messages and content, so that the recipient and/or reader potentially connects more deeply with what you’re staying..
TinyMCE also provides a merge tag plug-in to help make it easier to personalize your content. That’s what you’ll find in this article – a guide on how to set up TinyMCE, with merge tags, including a detailed explanation and specific steps needed to get merge tags working in TinyMCE.
Merge tags demo
If you'd like to try merge tags directly, the following demo shows the TinyMCE Merge Tags plugin alongside other features. Note that the merge tags themselves are non-editable:
What are merge tags?
Merge tags are the little predefined snippets of text that's usually separated from the main text around them, by some form of bracketing. Content writers know the difference between a merge tag and other modified text by their different colors, prefix and suffix characters, and their a read-only lock that prevents editing.
Merge tags stand in for other content. When added to text, they’re a marker that tells the document, email, or other software to replace the merge tag text value with a matching, marked value from the database. After replacing the text with a matching value (like a customer name) the content becomes personalized. A merge tag saves time that would have otherwise been spent inputting individual names from the customer database.
What are personalization tokens?
Personalization tokens are another name for merge tags. Wordstar, back in the 1980s, is one of the first word processors to feature ‘personalization’ in the form of mail merge. The personalization aspect grew from the repeated request to ‘personalize’ mail sent out to customers. The tokens indicate a place where content is checked against a Customer Relationship Management (CRM) database. Each letter is checked against the database, and the CRM app creates a new letter for each customer entry in the database.
How do merge tags work in docs and email apps?
It’s easier to break down how merge tags can help documentation systems and applications, by looking at some examples:
1. A document management system
A good document management system should make it easy to keep track of repetitive content, like the day’s date. For example, writing something like a { today } merge tag could automatically mark the place to insert the day’s date in the document. Here’s another example: a more academic merge tag system could adapt something like { reference_all } to automatically add a complete reference list for students.
2. A customer relationship management app
Apart from contact information, personalization of your customer communication can make all the difference. Having merge tags installed can help prevent costly errors like typos in customer names, as well as the names of their business.
3. Email applications
This is where the term mail merge originates from.
When writing emails, rather than including individual addresses and names for each customer, you can include a merge tag, and the software’s automation can identify the tag, and replace it, or merge it, with information from the database.
Like anything, once you see an example of how merge tags work, their usefulness becomes more clear. The following sections show you how to build an example of TinyMCE’s Merge Tags, so you can get a clear grasp of how they utilize automations for specific content.
How to create merge tags for docs or mail merge
Prerequisites for creating merge tags are:
-
Some experience in JavaScript and HTML
-
A plan for how you want your merge tags to look
For the second prerequisite, merge tags in TinyMCE have a prefix and a suffix. These are important to choose, because when you type them into the text area, the specific characters trigger an autocomplete dialog box. Then you can scroll through the box to choose the correct merge tag. Entering characters on the keyboard after typing in the prefix, will further filter the list of merge tag items set up in your app's configuration.
The TinyMCE Merge Tag plugin is also backwards compatible. If you’ve already decided on what your merge tags look like (because you're already using personalization tokens of some kind), you can add the existing tokens into the Merge Tag plugin configuration and continue using them without having to migrate to a new process.
Setting up a demo app for Merge Tags plugin
For the purpose of instruction, the following procedure shows how to create a basic email app, and then how to implement the Merge Tag plugin into that demo.
-
Create a new index.html file
-
Save the file to your developer workstation
-
In the index.html file, get your content started by including HTML content,
and script tags:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
<script></script>
<script></script>
</head>
<body>
</body>
</html>-
If you haven’t already, sign up for a FREE TinyMCE API key – you can sign up using a Google or GitHub account. When you sign up for a TinyMCE account, your API key comes with 14 days free access to TinyMCE Premium plugins. Merge Tags are a Premium Plugin, and require a paid subscription to include in your app.
Adding your API key to your app also prevents error messages related to domain names from appearing in the TinyMCE text area.
-
Update the script tags to include a TinyMCE basic configuration, including
the Merge Tags plugin.
<title>Document</title>
<script src="https://cdn.tiny.cloud/1/your-api-key/tinymce/6/tinymce.min.js" referrerpolicy="origin"></script>
<script>
tinymce.init({
selector: "#editor",
plugins: "mergetags powerpaste searchreplace directionality visualblocks image link insertdatetime lists wordcount tinymcespellchecker formatpainter linkchecker emoticons autosave",
toolbar: "undo redo | mergetags"
</script>
</head>
<body>
</body>
</html>-
The TinyMCE init script contains a CSS selector – in this case it's an id tag called 'editor'. Reference this id in a textarea element inside the HTML body:
<body>
<textarea id="editor">Welcome to TinyMCE with merge tags</textarea>
</body>-
Save the changes and then open the index html file in a browser. You can use a Python command or a PHP command to serve the index.html file instead to get something closer to a production experience.
If everything has worked your editor should load with TinyMCE, ready to test out some plugins. It's not ready for Merge Tags just yet. For that, the next step is configuring the Merge Tags prefix and suffix.
Configuring prefixes and suffixes
The prefix characters trigger the merge tag, which makes it an important part of the process of setting up a commenting system.
-
Add the merge tag option to the TinyMCE init script:
...
toolbar: "undo redo | mergetags"
mergetags_prefix: ' '
</script>-
Select your prefix – here you can include your existing merge tag prefix characters if you're already using merge tags anywhere in your system. For example, if you are using a double bracket to mark merge tags:
...
toolbar: "undo redo | mergetags"
mergetags_prefix: '{{'
</script>-
With that done, configure the suffix option. For the suffix, while you can choose any characters that make sense for you, the suffix usually mirrors the prefix:
...
toolbar: "undo redo | mergetags"
mergetags_prefix: '{{',
mergetags_sufix: '}}'
</script>-
Save the changes, and test the prefix in the browser. It needs one further configuration to complete the merge tags, and that’s a list of values.
Configure a list of merge tags
The mergetags_list option is the third and final option to configure. Setting up this object array gives your app the actual non-editable values. These could be "current.date", "current.time", and "person". The objects are given a name and value. Then sub-menus are added to objects to give them more specific values.
Here's how it works:
-
Add the mergetag_list value to your TinyMCE init script:
...
...
toolbar: "undo redo | mergetags"
mergetags_prefix: '{{',
mergetags_sufix: '}}'
mergetag_list: [
]
</script>-
Set up a new object with curly bracers and give it a title. This one is called 'customer.Signup.date':
...
...
toolbar: "undo redo | mergetags"
mergetags_prefix: '{{',
mergetags_sufix: '}}'
mergetag_list: [
{
value: 'customer.Signup.date',
title: ''
}
]
</script>-
Create a title for the object:
mergetag_list: [
{
value: "customer.Signup.date",
title: "join date in DD/MM/YYYY format",
},
];
-
To test out how sub-menus work, add another title to the merge tag list called "customer":
mergetag_list: [
{
value: "customer.Signup.date",
title: "join date in DD/MM/YYYY format",
},
{
title: "customer",
},
];
-
Add the menu option:
mergetag_list: [
{
value: "customer.Signup.date",
title: "join date in DD/MM/YYYY format",
},
{
title: "customer",
menu: [],
},
];
-
Add an array of information to the menu option that includes values and titles:
mergetag_list: [
{
value: "customer.Signup.date",
title: "join date in DD/MM/YYYY format",
},
{
title: "customer",
menu: [
{
value: "customer.full.name",
title: "customer name",
},
],
},
];
-
You can add another sub-menu, and more information into the new sub menu array to give the object more specific values:
mergetag_list: [
{
value: "customer.Signup.date",
title: "join date in DD/MM/YYYY format",
},
{
title: "customer",
menu: [
{
value: "customer.full.name",
title: "customer name",
},
{
title: "Email",
menu: [
{
value: "customer.primary.email",
},
{
value: "customer.secondary.email",
},
],
},
],
},
];
-
Save the changes and try out the new prefix in the browser. The merge tag autocomplete menu should now appear:
Merge tags support and Merge tags in production
The previous example is a demo only. However, you can take the three main elements of merge tags (the prefix, suffix, and merge tag list), and include these in an existing app. They’re designed to integrate seamlessly into a system that already makes use of merge tags, personalization tokens, or mail merge automation.
If you need support, it's available – reach out to our Customer Success team, and receive the assistance you need when you sign up for a Free API key (with 14 days Premium plugin access) or through one of the TinyMCE paid plans (for maximum support and guidance).
In production, there are more elements of merge tags to configure. It's the ability to configure it natively, inside the text area that resides inside your application, that can save adding any more configuration time to the process than necessary.
