The template editor

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

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. These don't require a prefixed namespace to reference, so if you send through { "a_variable": "something" } in your data payload you can reference this as {{ a_variable }} in your template.

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.

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.

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.

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.