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
- Variables
- func NewEngine() *osteele.Engine
- func Prepare(src string) string
- func Render(src string, vars map[string]any) (string, error)
- func Vars(email, firstName, lastName string, attributes map[string]any, ...) map[string]any
- type CustomField
- type LiquidProblem
- type PersonalizationToken
- type Use
Constants ¶
const MaxOutput = 4 << 20
MaxOutput is the largest rendered result, in bytes.
const MaxRange = 1000
MaxRange is the longest literal range a for loop may iterate.
Variables ¶
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.
var ErrTooLarge = errors.New("the rendered email is larger than 4 MB")
ErrTooLarge is returned when rendering exceeds MaxOutput.
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 ¶
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.
Types ¶
type CustomField ¶
type CustomField struct {
Key, Label, Type string
}
CustomField is a workspace contact field (custom_fields).
type LiquidProblem ¶
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.