The template editor

Learn how to use the Knock template editor to design notifications for your product.

Each channel step you add to a workflow will have its own notification template. This template is what determines what the notifications sent to your user look like for a given channel.

In this page we'll walk through the key features of the Knock template editor and how you can use them to design your notifications.

We'll cover:

Inserting variables from your trigger call into your notification template.
Using liquid syntax to add logic and control flow to your notification template.
Visual editing with drag-and-drop components.
How to preview and test your notification template.
Why we recommend storing all of your notification templates in Knock.

💡

All templates in Knock use the Liquid templating language. You can learn more in the Liquid documentation.

Personalize notifications with template variables

To inject a variable into your notification template, enclose it with double curly braces: {{ a_variable }}.

You can use curly braces to reference a number of different variable types in your templates. We've included a few common types below.

You can find the full list of supported variables here.

Data payload variables

All variables sent in the data payload of your workflow trigger call. If you send through { "a_variable": "something" } in your data payload you can reference this as {{ data.a_variable }} in your template.

💡

Note: if you want to reference all of the data passed to the workflow, you can use the data variable.

User properties

To reference a user property (such as name), use the actor and recipient namespaces. This looks up the actor or the recipient of a given notification, and then finds the specified property for that user. Here's a code example where a recipient's name and plan are injected into a notification template:

Full list of Knock variables available →

Adding control flow and iteration to your template

The Knock template editor uses Liquid tags to create the logic and control flow for notification templates. To learn more about Liquid, you can check out its documentation.

Here are a few Liquid tag types that are commonly used in Knock notification templates.

If and else-if statements. For when you want to show different copy depending on a user property or a data variable from your trigger call. In the example below, we show different copy depending on whether a batch of comments includes one or many comments.

For loops. You can use Liquid's for...in... tag to iterate over a list of items. We can add this to our example from above to iterate over the comments in a batch and add each one to our notification.

There are also a number of Liquid filters you can use to mutate the variables you pass into a notification template. Here's an example that uses the split and first filters to pull the first name for a given user.

To learn more about the variables, Liquid keywords, and other helper functions available to you in the Knock template editor, check out our liquid helper reference.

Visual editing with drag-and-drop components

The Knock template editor includes a visual editor you can use to compose your template with drag-and-drop components.

🛣

Note: The visual template editor is currently only available for email templates.

When you're in the visual template editor you'll see a Components panel on the right with a number of components for use in your template.

Once you add a new component to the document, the Components pane will automatically switch to Inspect mode, where you can edit various attributes of the newly added component. While in inspect mode, you can remove the component by clicking the x icon in the top-right corner of the component or access additional menu items from the Inspect pane header.

As a reminder, you still have full access to the variables data as well as liquid tags when editing any of the text content fields of any components. The visual template editor makes it easier to introduce elements into your notification template while still giving you the full flexibility and power of code.

A few other component features to note:

Markdown (and Blockquote) components support liquid and basic Markdown syntax. You can learn more about Markdown in its documentation.
Button components can be configured to use your brand colors by default, so you can ensure your brand elements are consistent across all of your product messaging. To configure your brand colors, head over to the branding settings page in your dashboard. ("Settings" page → "Branding" tab)
HTML components can contain any valid HTML markup and provide an "escape hatch" for advanced use cases where more complex markups are needed.

If you ever want to take complete control of the notification template and just work in HTML and CSS, you can enter the code editor via the "Enter code editor" button found at the bottom of the editor. When opting out of the visual template editor, any components used in the template document will be translated into the equivalent HTML for you to take over.

Updating component styles

When using the visual template editor, a handful of CSS styles are auto-generated and included in the email layout to provide base styles for certain components. If you want to globally configure these component styles to match your design system, you can do so by updating your email layout to override the base styles we generate for components. You can learn more about updating base component styles in email layouts here.

🚨

Reminder: The visual template editor will only render component styles when you are in preview mode. Your layout (and its styles) is not rendered in editor mode.

Previewing and testing your notification template

Once you've finished editing your notification template, you can select "Preview" in the toggle in the top left of the template editor pane to enter preview mode.

🧩

Note: When you enter preview mode for an email template, you'll see your email content wrapped within the template's selected Layout.

Your notification preview is populated with the data available in the lefthand variable explorer pane. You can use the actor and recipient dropdowns to change the user data used in your preview, and you can click on any of your data variables to edit their preview value.

To test your notification, click "Save" and navigate back to the workflow canvas by clicking the back arrow in the top-left corner. You can run actual notification tests by clicking "Run a test" in the top-right corner. Just choose your actor and recipient, provide and trigger call data that you'd like included in your test, and click "Run test."

All test runner notifications are tracked under "Messages" and have a source of "Test runner" to distinguish them from notifications you've triggered via the Knock API.

Frequently asked questions

This is a common question that we hear from our customers, particularly those who currently maintain templates for their notifications in other third-party tools (often more than one!).

While planning a migration will require some upfront effort, we recommend using Knock as the source of truth for your notification templates for a number of reasons:

A consistent editing experience. When you manage all of your templates in Knock, your content authors have access to a unified template editor for a consistent experience across all delivery channels. Teams who collaborate on messaging can work with a single templating language (Liquid) for dynamic content.
Cross-channel engagement analytics. With Knock link and open tracking in your message templates, you have access to cross-channel engagement analytics for each of your notification use cases in a centralized tool.
Unlock greater efficiency. In the same way that Knock combines the logic and delivery of all of your notifications into a single API, using Knock as the source of truth for your templates means streamlining your process for cross-functional work on notifications. All changes to your message content, regardless of delivery channel, will follow the same steps for previewing, testing, and committing updates to production.
Work with your templates programmatically. With our Management API or CLI, you can work with all of your cross-channel templates as code via a single API. This enables you to integrate your templates with other tools, automate updates, and more.
Reusable content blocks. Our Partials feature allows you to create content blocks of various types that can be reused across all of your notification templates. This enables updates across all delivery channels with a single change when necessary.
Reference data from other resources stored in Knock. In addition to the context that you pass to Knock on your workflow trigger calls and reference as dynamic content in your notifications (like recipient and tenant properties, or custom data payload variables), the Knock template editor also allows you to reference data from any Users, Objects, and Tenants that exist within your Knock environment.

Referencing data is a powerful way to share context across entities in your templates without needing to manually pass the data in the data argument of your workflow trigger, and isn't possible with other templating solutions.

←Partials

Variables→