KnockDocs

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 notify 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

Inserting variables into your notification template

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:

Data payload variables. Variables sent in the data payload of your notify call are injected with curly braces and don't require a prefixed namespace.

User properties. If you want to reference a user property, such as name, use the actor and recipient namespaces. This looks up the actor or a 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:

Account and environment constants. You can also set constants at an account or environment level in Knock for variables that won't change across your different notification workflows. (For more information read our guide on environments.) Common use cases for constants include base URLs for routing (e.g. dashboard.knock.app v. dashboard.knock-dev.app) and product names. To access constants in your notification templates, use the vars namespace. Here's a code example of an action URL for an in-app feed notification that uses an environment constant: {{ vars.app_url }}/page/{{ page_id }}.

Workflow state variables. There are a standard set of workflow state variables that are available on all workflow runs, but that you'll find especially useful if you start to work with batch functions. These variables are available on all workflows and keep track of the activities kept within the state of a given workflow run (i.e. the number of notify calls that workflow run has received.)

  • total_activities - The number of activities included within the batch. (An example: In the notification "Dennis Nedry left 8 comments for you", the total_activities count equals eight.)

  • total_actors - The number of unique actors that triggered activities included within the batch. (An example: In the notification "Dennis Nedry and two others left comments for you", the total_actors count equals three, Dennis plus the two others you mentioned in the notification.)

  • activities - A list of up to ten of the activity objects included within the batch, where each activity equals the state sent across in your notify call. The activities variable lists the first ten activity objects added to the batch. Each activity includes any data properties you sent along in the notify call, as well as any user properties for your actor and recipient(s). You can use the activities variable to create templates like this:

  • actors - A list of up to ten of the unique actors included within the batch, where each actor is a user object with the properties available on your Knock user schema. The actors variable lists the first ten actors added to the batch.

  • timestamp - The time in which the activity occurred, as an ISO-8601 datetime string.

In addition to injecting custom variables, you'll also have access to data properties about the recipient (the user who is receiving the message) as well as the actor (the user who performed the action that generated the message.)

The custom variables will be passed to the template via the notify call when triggering the workflow.

Adding control flow and iteration to your template with liquid

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 notify 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 supports visual editing that allows you to compose a notification template with components you can drag and drop into the template document.

Please note: this is currently available for email templates only.

In the visual template editor, in addition to the Variables data pane on the left, you have the Components panel on the right, where you can access available components.

Once you add a new component to the document, the Components pane will automatically switch to the 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.

Moreover, please note the following features of the components:

  • Markdown (and Blockquote) components support liquid and basic Markdown syntax. To learn more about Markdown, check out 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.

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. Refer to the reference guide for more details.

Lastly, if you ever want to take complete control of the notification template and manually edit in the code editor, you can do so 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.

Previewing and testing your notification template

Once you've finished editing your notification template, you can click "preview" in the top-left corner of the editor 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 notify 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.