Better Message Templates - Visual Tour

Better Message Templates ties into the existing message template administration UI and is accessed as typical; e.g. Mailings > Message Templates or Administer > CiviMail > Message Templates.

Make this the default tab - make Better Message Templates the first, default tab. Not available when using the Message Administration extension.

The template select control lists all the User-driven and System Workflow message templates available. Selecting a User-driven message will open in the OG CiviCRM WYSIWYG editor. Selecting a System Workflow message will open in the Better Message Templates editor.

The search field here lets you filter on template title.

The important templates are listed in green and indicate their modified status, number of samples available, and translation/drafts available.

Only list important templates - hide System Workflow templates that aren't important.

The search field above the template select control allows you to search all message template content. The template select control updates to include only those templates that match the search.

Global Settings apply to all users across all browsers on all devices. Changes are saved immediately.

  • Automatically Inject Header - Replaces the contents between the <!-- BEGIN HEADER --> and <!-- END HEADER --> comments with the {header} token for the selected header component, for HTML content. For plain-text, the {header} token is placed before all other content.
  • Automatically Inject Footer - Places the {footer} token for the selected footer component before </body>, for HTML content. For plain-text, the {footer} token is placed after all other content.

Better Message Templates defines {header} and {footer} tokens for all active header/footer mailing components (Administer > CiviMail > Headers, Footers, and Automated Messages). These tokens can be used wherever tokens are available, and should appear on Tokens dropdowns found in the various user interfaces. Headers and footers can contain other tokens, and these will be processed as well, in the context of the containing document being rendered/sent. As a result, some tokens may not be rendered properly; e.g. an {action.whatever} token requires a mailingId, which would not be applicable for a system workflow message.

Personal Preferences are stored in browser local storage immediately. They will not persist to another browser on the same device, or any broswer on any other device.

  • Make this the default tab - make Better Message Templates the first, default tab. Not available when using the Message Administration extension.
  • Only list important templates - hide System Workflow templates that aren't important.
  • Open editor maximized - automatically puts the Better Message Templates editor into maximized mode when opened, explained in more detail to follow.
  • Restore theme - when the mouse cursor leaves the browser viewport, automatically restores the Better Message Templates editor to standard size for the theme.
  • Goto error - if Preview results in an error with a well defined line number, scroll it into view in the Message pane. Well defined means it contains the text [in evaluated template line #], where # is the line number containing the error.
  • Wordwrap - determines the wordwrap mode used in the Message pane.

The Better Message Templates editor is comprised of a title bar, the Sample pane, the Message pane, and the Tool pane.


The editor is shown here in it's maximized state. Click the Maximize () icon to ignore the theme and resize to fit the entire browser viewport, obscuring all other site content including things like fixed headers/footers and site navigation. The border around the browser viewport will be green if the current message template has not been modified, and will turn red once a change has been made.

Click the Restore Theme icon () to restore the editor to standard size for the theme.

Click the Close icon () to close the Bette Message Templates editor and return to the template listing.

Each system workflow starts with a single, Standard, variant. A language variant may be added...

The variant selector is depicted open for demonstration purposes only. You do not need to do that in order to use these actions.

...

A draft can be created for each Standard and language variant.

Activating a draft copies it's current contents into it's counterpart, and switches to it. e.g. French (Canada) (Draft) gets copied into French (Canada). French (Canada) (Draft) will not be deleted, and French (Canada) will not be saved; you must take those actions seperately.

A modified variant is listed in red.

The red border around the editor (maximized mode only) and the Save Template action will revert to their normal state once all modified variants have been saved.

Select the message format to edit.

The editor context (right-click) menu has a few commonly used actions, including three added by Better Message Templates, and provides access to the Command Palette.

  • Refresh Current Tool - as edits are made to the content, the border around the currently selected tool will turn red to indicate that it is out of sync with the editor. The tool will update automatically when focus leaves the editor...or use this action.
  • Reveal In Outline - scrolls the cursor position into view in the Outline.
  • Reveal In Outline & Select - scrolls the cursor position into view in the Outline, and then selects that block in the editor.

Alternatively, if the editor has focus you may access the Command Palette using F1.

Choose your tool.

Expand or collapse all the Smarty blocks in the Outline in one fell swoop.

The structure of a template can get confusing at times. The location of the mouse pointer within that structure is shown below the Outline.

Clicking a variable or token in the Outline will select it and all other references to it. Click X of Y to scroll the next reference into view.

The variable or token is also selected in the Sample pane, depicted in more detail later in this tour.

Clicking a section of content in the Outline selects it in the editor and scrolls it into view.

Shift click a section of content in the Outline to expand that selection to include sibling content.

Ctrl click a section of content in the Outline to expand the selection even further to include the opening and closing Smarty tags for the parent block.

The Outline can identify some issues...

...

...



Text that has been removed since the selected revision is shown in red; click to restore. Text that has been added since the selected revision is shown in green; click to remove.

Use the X of Y to scroll through the differences.

No changes since last save.

Copies the selected revision into the current variant.

Check for revisions made by others.

When a sample is not selected, the Variables list simply helps with navigation, by selecting all references to it in the Outline.

The sample dropdown lists your 25 most Recent Captures and as many Reference Samples as you choose to create (more below).

After selecting a sample, the Variables list is updated to include any variables and tokens that were included in the sample but not referenced by the current template.

Click a name in the Variables list to view/edit it's value.

Select a Type to choose how the value is specified.

It's all really just a matter of preference, in most cases.

Setting/changing a value for a variable is not required, but can be helpful to see how it affects the output of the template, or for anonymizing data for reference samples.

You won't see this type set for a variable unless you choose to use it. It's provided mainly to help document the meaning/source of certain variables in reference samples. Again, totally optional.

For more complex data.

Rename a variable or token across HTML, Plain-text, and Subject formats in one go. Can be quite helpful when a variable gets deprectated/removed.

Deselects the variable in the Variables list, hides the editor if a sample is selected, and clears the variable selection in the Outline.

When the last reference to a variable is removed from the template text, it will still appear on the Variables list. Use this to rescan the template text and remove unreferenced variables.

The new sample will be a copy of the currently selected sample. While you can create a new sample without one already selected, doing so will create an empty sample with no values assigned to any variables; you're not likely to find this too useful.

Saving a sample updates the currently selected sample. If the currently selected sample is a Recent Capture, those changes will be lost along with the sample when it is no longer 25 most recent.

Saving a sample with a different name will change a Recent Capture into a Reference Sample, which will remain available until you choose to delete it.

Check for new samples without reloading the page.

Curating Quality Reference Samples (Optional)

Having recent captures is a good way to keep up with message templates, as they will include changes that may be made in core CiviCRM code; e.g. when getting converted to use tokens in place of template variables. However, your recent captures might not include all the scenarios that the template might need to cover. Creating reference samples solves for this.

Before creating reference samples, you should first create a perfect sample contact. This contact should have an obviously not real name, and provide values for every bit of data you ask from your constituents; imagine someone with zero privacy concerns giving you every bit of information you ask for. Make that contact. When it comes to addresses, provide real city/state/province/postal values but maybe make up a street name. Make sure phone numbers aren't connected to a real person, (999)555-1212 as a U.S. example. Etc.

To create a reference sample for a template execute that workflow as your sample contact, which will result in a recent capture. Then use Save Sample As... to give it a meaningful name. Rinse and repeat as necessary for the template; e.g. a contribution page that accepts credit card, PayPal, and pay later, would ideally have a reference sample for each of those options.

Rinse and repeat for each message template used by your organization.

CiviCRM occasionally makes changes to message templates, so it's possible that your reference samples may become unusable. In the rare instance that this happens, you should delete and recreate your reference samples.