liquid

package
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 24, 2026 License: AGPL-3.0 Imports: 9 Imported by: 0

Documentation

Overview

Package liquid renders personalization in subjects, preheaders and email bodies with Liquid (osteele/liquid): {{ first_name | default: "there" }}.

Email HTML escapes quotes and angle brackets, and editors write them as entities, so Prepare decodes entities inside {{ … }} and {% … %} before parsing. The composer's short form {{ first_name | "there" }} is accepted and read as default: "there". Rendering is bounded: no include or render (templates can't load other templates or files), ranges of at most 1,000 items and at most 4 MB of output.

Index

Constants

View Source
const MaxOutput = 4 << 20

MaxOutput is the largest rendered result, in bytes.

View Source
const MaxRange = 1000

MaxRange is the longest literal range a for loop may iterate.

Variables

View Source
var ContactFields = []PersonalizationToken{
	{Key: "first_name", Label: "First name", Kind: "contact", Fallback: "there"},
	{Key: "last_name", Label: "Last name", Kind: "contact"},
	{Key: "email", Label: "Email address", Kind: "contact"},
}

ContactFields are on every contact.

View Source
var ErrTooLarge = errors.New("the rendered email is larger than 4 MB")

ErrTooLarge is returned when rendering exceeds MaxOutput.

View Source
var SystemFields = []PersonalizationToken{
	{Key: "unsubscribe_url", Label: "Unsubscribe link", Kind: "system"},
	{Key: "preferences_url", Label: "Email preferences link", Kind: "system"},
	{Key: "view_in_browser_url", Label: "View in browser link", Kind: "system"},
}

SystemFields are links ReputeCast fills in per recipient at send time.

Functions

func NewEngine

func NewEngine() *osteele.Engine

NewEngine returns a Liquid engine that can't read files. Every package that parses Liquid uses it.

osteele/liquid's include and render tags load other templates from the engine's template store, which by default reads files under the working directory: an email could print the server's files, and a template that renders itself recursed until the stack overflowed, killing the process. Both tags are removed, so using one is a parse error with its line, and the store holds no templates, so a tag added later can't read files either.

func Prepare

func Prepare(src string) string

Prepare decodes HTML entities inside Liquid delimiters and rewrites the short fallback form, so Liquid embedded in compiled HTML parses.

func Render

func Render(src string, vars map[string]any) (string, error)

func Vars

func Vars(email, firstName, lastName string, attributes map[string]any, links map[string]string) map[string]any

Vars builds the variables of one recipient: contact fields, custom fields (attributes) and the per-recipient links. Contact fields are also available as contact.first_name.

Types

type CustomField

type CustomField struct {
	Key, Label, Type string
}

CustomField is a workspace contact field (custom_fields).

type LiquidProblem

type LiquidProblem struct {
	Line    int    `json:"line"`
	Message string `json:"message"`
}

LiquidProblem is a template error with its line.

func Validate

func Validate(src string) []LiquidProblem

Validate parses a template and returns its problems (empty when it parses).

type PersonalizationToken

type PersonalizationToken struct {
	Key   string `json:"key" example:"first_name"`
	Label string `json:"label" example:"First name"`
	Kind  string `json:"kind" enum:"contact,custom,system"`
	// Fallback is the suggested default for contacts without a value.
	Fallback string `json:"fallback,omitempty"`
}

PersonalizationToken is a personalization token offered by the composer.

func Catalog

func Catalog(custom []CustomField) []PersonalizationToken

Catalog lists the tokens of a workspace: contact fields, its custom fields, then the system links.

type Use

type Use struct {
	Key         string `json:"key"`
	Fallback    string `json:"fallback,omitempty"`
	HasFallback bool   `json:"hasFallback"`
	Count       int    `json:"count"`
}

Use is a variable a template prints, with its fallback.

func Uses

func Uses(src string) []Use

Uses lists the variables printed with {{ … }}, in order of first use.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL