diff --git a/content/concepts/subscriptions.mdx b/content/concepts/subscriptions.mdx index 1efd57ef7..323f66863 100644 --- a/content/concepts/subscriptions.mdx +++ b/content/concepts/subscriptions.mdx @@ -132,6 +132,19 @@ As an example, if you have a property `role` under your subscription properties, } /> +## Referencing subscriptions in templates + +You can use the `subscriptions` Liquid filter to dynamically load up to 25 active subscriptions for a user in your notification templates. This is useful when you want to render content based on what a user is subscribed to without passing subscription data in the workflow trigger. + +```liquid title="Rendering a user's subscriptions in a template" +{% assign subs = recipient.id | subscriptions %} +{% for sub in subs %} + {{ sub.object.id }} - {{ sub.properties.role }} +{% endfor %} +``` + +For more details, see [referencing data in templates](/template-editor/referencing-data#referencing-subscriptions-via-the-subscriptions-filter). + ## Modeling nested subscription hierarchies It's possible to model nested subscription hierarchies by associating child objects as subscribers of a parent object. This allows you to create structures like "organizations" having many "teams" which have many "team members" (users). diff --git a/content/template-editor/reference-liquid-helpers.mdx b/content/template-editor/reference-liquid-helpers.mdx index 791d86328..582f1c221 100644 --- a/content/template-editor/reference-liquid-helpers.mdx +++ b/content/template-editor/reference-liquid-helpers.mdx @@ -1,7 +1,19 @@ --- title: "Liquid helpers" description: A reference to help you work with the Liquid templating language in Knock. -tags: ["liquid", "template", "variables", "currency", "timezone", "pluralize"] +tags: + [ + "liquid", + "template", + "variables", + "currency", + "timezone", + "pluralize", + "user", + "object", + "tenant", + "subscriptions", + ] section: Working with templates --- @@ -201,6 +213,37 @@ The Knock template editor uses Liquid syntax for control flow and variable decla ]} /> +## Dynamic data filters + +Knock provides a set of Liquid filters that dynamically load data from your Knock environment at template render time. These filters enable you to reference entities like users, objects, tenants, and subscriptions in your templates without passing all of the data in your workflow trigger call. For more details and examples, see [referencing data in templates](/template-editor/referencing-data). + + + ### Date format options The `format_date_in_locale` and `format_datetime_in_locale` helpers accept date format options that control how the date portion is displayed: diff --git a/content/template-editor/referencing-data.mdx b/content/template-editor/referencing-data.mdx index 6b8cc03df..42180da95 100644 --- a/content/template-editor/referencing-data.mdx +++ b/content/template-editor/referencing-data.mdx @@ -1,14 +1,31 @@ --- title: "Referencing data in templates" description: Documentation outlining how to work with data in your templates. -tags: ["liquid", "template", "objects", "users", "tenants"] +tags: ["liquid", "template", "objects", "users", "tenants", "subscriptions"] section: Working with templates --- -In addition to the [variables](/template-editor/variables) available as part of the workflow run scope, you can also reference data from the users, objects, and tenants that exist within your Knock environment. +In addition to the [variables](/template-editor/variables) available as part of the workflow run scope, you can also reference data from the users, objects, tenants, and subscriptions 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. + + The user, object, tenant, and{" "} + subscriptions filters all dynamically load data from your + Knock environment at render time. You can find a full reference of these + filters in the{" "} + + Liquid helpers reference + + . + + } +/> + ## Referencing users via the `user` filter To reference a user, you can use the `user` filter. This will return a serialized `User`, which you can then use to output data in your template. @@ -70,6 +87,34 @@ Tenants returned will have all custom properties available, as well as the `id`, {% assign tenant = data.other_tenant_id | tenant %} ``` +## Referencing subscriptions via the `subscriptions` filter + +To reference the subscriptions for a user, you can use the `subscriptions` filter. This filter loads up to 25 active subscriptions for the given user and returns a list of serialized subscription objects. + +Each subscription returned includes the `object` the user is subscribed to, along with any custom `properties` set on the subscription. You can iterate over the results to render subscription-specific content in your templates. + +```liquid title="Loading subscriptions for the current recipient" +{% assign subs = recipient.id | subscriptions %} +{% for sub in subs %} + {{ sub.object.id }} - {{ sub.properties.role }} +{% endfor %} +``` + +
+ +```liquid title="Loading subscriptions for a user via a dynamic identifier" +{% assign subs = data.user_id | subscriptions %} +{% for sub in subs %} + {{ sub.object.id }} +{% endfor %} +``` + + + ## Frequently asked questions