Docs for recommended mail-merge tokens

[totten]

There are two distinct levels of variable-substitution when composing a message with Mosaico.

• First, at design-time, there are various model-properties exposed in the GUI (such as the Facebook URL or Twitter URL). These variables are interpolated by the browser-based JS renderer.
• Second, at delivery-time, there are mail-merge tokens which are unique to each recipient (such as the unsubscribe URL). These variables are interpolated by some server-side delivery system.

There's some formalization/documentation for the design-time variables, but I haven't found any documentation about mail-merge tokens. This is both a strength and a weakness:

• Strength: Keeping the JS agnostic to mail-merge tokens makes it possible to adapt different backends and/or templates without changing the browser/JS logic. There is generally no singular standard for mail-merge tokens in the industry, so it's good for the main JS app to be unopinionated.
• Weakness: The lack of a standard makes it harder to share/swap among different templates and backends. For example, to provide compatibility between versafix-1 and the CiviCRM-Mosaico integration, there's a token mapping. To maintain the mapping, one must grep carefully through the versafix code.

To mitigate the weakness, we could add documentation for recommended mail-merge tokens based on the current list of tokens found in versafix-1:

• [unsubscribe_link]
• [show_link]
• [profile_link]
• [mail]

Since these would be presented as mere recommendations, it should be fine and expected that different templates and backends support different functionality. However, for template and backend developers that want interoperability, they could aim for mutual support of the recommended tokens.

[bago]

Well, mosaico doesn't care at all about those "tokens". It is something defined in the default master template (versafix-template) that is an external project. We never documented it because we thought that users of Mosaico will simply customize the master template using their tokens and Mosaico won't care at all about it.

The tokens you see are the tokens used by VOXmail, the ESP that opensourced Mosaico, so we simply left our tokens there.

If in future Mosaico will understand something about tokens, THEN, we'll have to take care documenting them in mosaico. In the mean time we could add some README to versafix-template project about the tokens used by that master template and the fact that you probably have to replace them with your own.

Of course documentation contributions are more than welcome!

[bago]

Please note versafix has its own repository https://github.com/voidlabs/versafix-template and since 1.1.x it is generated and maintained using a templating language (HTMML).
Maybe we could do something on the HTMML side, in order to make it simpler to define tokes and "merge" them in the final "master template".

[bago]

About your "2 levels" of variable substitution I think the second one is part of much more things a backend will do. Most backends will add open tracking and click tracking, for example, and this cannot be done on the client side as they are different "per recipient": most backend will have to implement their parsing in order to find links to "track" (replace) or to find where to put the unsubscribe link or the open tracking image. Maybe we could add something to mosaico to make this parsing easier, but I don't know how (e.g. in our own private backend we also parse CSS and replace every url referred in styles).

For the record, some backend also search for "images source urls" (img src attr, td background attr, css background: url() property, etc ) in order to replace "dinamically" generated images with images uploaded to a CDN.