Template reference

This article lists everything EmailShepherd adds to Liquid for component templates. To learn how templates work, see Component templates. For the standard Liquid tags and filters, see the Liquid documentation.

Syntax	What it does
{{field_variable}}	Outputs a field’s value. See Field values.
{{global_fields.field_variable}}	Outputs a global field’s value. See Global fields.
{{children}}	Marks where components go in the container. See Children.
data-es-field-focus	Opens a field when part of the preview is clicked. See Field focus.
track_link	Adds link tracking to a link. See Link tracking.
{% raw %}	Outputs code without processing it. See Raw output.
render_context	Details about the email being rendered. See Render context.

Field values

{{field_variable}} outputs the value of a field on the same component, where field_variable is the field’s Liquid variable. What the value looks like depends on the field type. See the field type reference.

<h1>{{headline}}</h1>

Global fields

{{global_fields.field_variable}} outputs the value of a field on the container component. Global fields can be used in any template.

<td style="background-color: {{global_fields.email_background_color}}">

Children

{{children}} marks where an email’s components are output. It’s required in the container component’s template, and can only be used there.

<body>
  {{children}}
</body>

Field focus

Add data-es-field-focus to an element to open a field when someone clicks that element in the email editor’s preview. The value is the field’s Liquid variable. The sidebar opens the component, scrolls to the field and selects it, ready to type.

<h1 data-es-field-focus="headline">{{headline}}</h1>
<div data-es-field-focus="body_text">{{body_text}}</div>

The value must be the Liquid variable of a field on the same component, or you’ll see an error when you apply your changes.

In the container component’s template, use it with a global field’s Liquid variable, without the global_fields. prefix. Clicking the element opens the Global fields section.

<div data-es-field-focus="email_background_color">

Link tracking

The track_link filter adds the tracking parameters from your link tracking profile to a link written in the template, such as a fixed link in a footer. Put the link in quotes and the whole thing in double curly brackets. Use single quotes around the href attribute:

<a href='{{ "https://example.com" | track_link }}'>Visit our website</a>

If your link tracking profile has Editor Field Value parameters, pass their values to the filter, because the link has no field in the editor to enter them in:

<a href='{{ "https://example.com" | track_link: utm_content: "footer" }}'>Visit our website</a>

Caution

Don’t use track_link on a URL field or on links in a rich text field. They’re tracked already, so the parameters would be added twice.

Raw output

Everything between {% raw %} and {% endraw %} is output exactly as it is, without being processed. Use it for ESP code that uses Liquid or a similar syntax, so EmailShepherd doesn’t try to process it:

<p>{% raw %}Hello, {{ first_name }}{% endraw %}</p>

is exported as:

<p>Hello, {{ first_name }}</p>

Nothing inside a raw tag is processed, including field values. Close the tag before any Liquid you want EmailShepherd to process.

Where you can, add ESP code with personalization tags and conditionals instead. They output the right syntax for each ESP, and people can use them in the email editor.

Rich text HTML

Rich text fields output these tags and classes, so you can style them from your CSS:

Formatting	Tag	Class
Bold	<strong>	es-bold
Italic	<em>	es-italic
Bulleted list	<ul>	es-bullet-list
Numbered list	<ol>	es-ordered-list
List item	<li>	es-list-item
Link	<a>	es-link

A custom style added as a formatting option is output as a <span> with its CSS inline:

<span class="es-custom-style es-custom-style-brand_highlight" data-custom-style="brand_highlight" style="color: #1F6F5C; font-weight: bold;">styled text</span>

For a style with multiple options, the chosen option’s CSS is used. Several styles on the same text share one <span>, with their CSS combined in the order they were applied:

<span class="es-custom-style es-custom-style-text_color es-custom-style-font_size" data-custom-style="text_color:clay font_size:large" style="color: #B5543B; font-size: 24px;">styled text</span>

A custom style used to change a built-in option is applied to that option’s tag instead, such as <strong class="es-bold">.

In the editor preview only, personalization tags are output as a <span> with the class es-personalization-tag.

Render context

Every template can use the render_context object, with details about the email being rendered.

Property	Description
render_mode	editor_preview in the email editor, or export when the email is exported.
output_format	html for normal renders, or plaintext when the plain-text version of an export is being made.
email.id	The email’s ID.
email.name	The email’s name.
email.locale	The locale being rendered, such as en-US.
email.content.subject	The email’s subject line.
email.content.preheader	The email’s preheader.
project.id, project.name	The project the email is in.
email_design_system.id, email_design_system.name	The Email Design System the email uses.
brand_profile.id, brand_profile.name	The email’s brand profile, if it has one.
design_tokens	Your design tokens, including any brand profile overrides.
component_instance	The component being rendered. See Component instances.
previous_component_instance	The component before this one in the email, or empty if this is the first.
next_component_instance	The component after this one in the email, or empty if this is the last.
connector.id, connector.name, connector.type	The connector the email is being exported with, if any.

For example, {{render_context.email.content.subject}} outputs the subject line. See template examples for ways to use the render context.

Component instances

component_instance, previous_component_instance and next_component_instance each have:

Property	Description
id	The ID of this use of the component in the email.
name	The name given to the component in the email.
component_name	The component’s name in the Email Design System, such as hero.
conditional_id	The ID of the saved conditional on the component, or null if there isn’t one.
inline_conditional	true if the component has an inline conditional.

Example render context

{
  "render_context": {
    "render_mode": "export", // "editor_preview" | "export"
    "output_format": "html", // "html" | "plaintext"
    "email": {
      "id": 1,
      "name": "My email",
      "locale": "en-US",
      "content": {
        "subject": "Hello, world!",
        "preheader": "This is a test email"
      }
    },
    "project": { "id": 1, "name": "My project" },
    "email_design_system": { "id": 1, "name": "My email design system" },
    "brand_profile": { "id": 1, "name": "My brand profile" },
    "design_tokens": {
      "primary_color": "#ff0000",
      "font_family": "Arial, sans-serif"
    },
    "component_instance": {
      "id": "abcd-1234-5678-9012",
      "name": "Header",
      "component_name": "header",
      "conditional_id": 42,
      "inline_conditional": false
    },
    "previous_component_instance": {
      "id": "prev-1234-5678-9012",
      "name": "Hero Banner",
      "component_name": "hero",
      "conditional_id": null,
      "inline_conditional": true
    },
    "next_component_instance": {
      "id": "next-1234-5678-9012",
      "name": "Body Content",
      "component_name": "body",
      "conditional_id": null,
      "inline_conditional": false
    },
    "connector": {
      "id": 1,
      "name": "My connector",
      "type": "salesforce_marketing_cloud"
    }
  }
}

Deprecated features

You may come across these in existing templates. They still work, but you don’t need them in new templates.

Fragments

<es-fragment> groups content without adding a wrapper element:

<es-fragment>
  <p>{{headline}}</p>
  <p>{{body_text}}</p>
</es-fragment>

Templates used to need a single root element, so a component that output several elements side by side, or only text, had to be wrapped in <es-fragment>. Templates can now have more than one root element, or only text, so you no longer need it.

Templates that use <es-fragment> keep working. The tag is still removed when the email is exported, leaving only its contents. You don’t need to remove it from existing templates.