Documentation
¶
Overview ¶
Package mjml works with MJML documents on the server: a tolerant parser for outlines, warnings and wireframes, the server-side compiler (gomjml, MJML 4.15) used when content arrives as MJML only (API and automation sends), and head helpers that keep <mj-title>/<mj-preview> in step with the subject and preheader.
The composer compiles in the browser with mjml-browser (grapesjs-mjml); both engines target MJML 4 and parity is checked by tests.
Index ¶
- Constants
- func ChangedSections(base, next string) []string
- func ConditionalID(n *Node) string
- func HeadMeta(src string) (title, preview string)
- func PrepareCompile(src string) string
- func RemoveAttr(src string, n *Node, name string) (string, bool)
- func SectionLabel(n *Node, index, total int) string
- func SectionWord(l i18n.Lang, label string) string
- func SetAttr(src string, n *Node, name, value string) (string, bool)
- func SetHeadMeta(src, title, preview string) string
- func StripMarkers(html string) string
- type Attr
- type MJMLProblem
- type MJMLThumbItem
- type Node
- type ParseError
- type Result
- type Section
Constants ¶
const ( AttrVisible = "rc-visible" AttrName = "rc-name" AttrPoll = "rc-poll" AttrOmit = "rc-omit" AttrShowOn = "rc-show-on" // ShowOnWeb is a Web only block: it isn't part of the email. ShowOnWeb = "web" )
AttrVisible, AttrName, AttrPoll and AttrOmit are ReputeCast's own attributes; AttrShowOn is a block's "Show on" (the publication website, design expansion phase 7): "email", "web", or absent for both.
const ( MarkerIf = "<!--rc:if " MarkerFi = "<!--rc:fi " )
Marker comments around a conditional block in compiled HTML.
Variables ¶
This section is empty.
Functions ¶
func ChangedSections ¶
ChangedSections compares two documents and returns the labels of the sections of `next` that differ from `base` (added, edited or moved), plus the labels of sections removed from base.
func ConditionalID ¶
ConditionalID returns the id of a conditional element: one with a Visibility rule that doesn't show it to everyone. "" otherwise.
func PrepareCompile ¶
PrepareCompile turns a document into what the compilers get: rc-* attributes removed, Web only blocks (the post's, not the email's) and blocks marked rc-omit (shown in the editor only) left out, and conditional blocks wrapped in their markers. A document that doesn't parse is returned unchanged (the compiler reports its error). A block whose id appears twice is marked once, the first time: the composer gives a copied block an id of its own.
func RemoveAttr ¶
RemoveAttr removes an attribute of an element in the source.
func SectionLabel ¶
SectionLabel names a top-level body element: the ReputeCast marker when there is one, otherwise what it looks like.
func SectionWord ¶
SectionWord names a section label (Outline, SectionLabel) in a reader's language, in lower case as it reads inside a sentence: "chân thư" for "footer", "2 cột" for "2 columns". Labels it doesn't know, such as a block's own name, stay as they are.
func SetAttr ¶
SetAttr sets an attribute of an element in the source: it replaces the value or adds the attribute after the tag's name. Values are written double-quoted, escaped.
func SetHeadMeta ¶
SetHeadMeta writes <mj-title> (the subject) and <mj-preview> (the preheader) into a document so the compiled HTML's title and hidden preview text always match the fields. Empty values remove the element. A document that doesn't parse is returned unchanged.
func StripMarkers ¶
StripMarkers removes the conditional markers from compiled HTML: the email every recipient would get if no block were conditional.
Types ¶
type MJMLProblem ¶
type MJMLProblem struct {
Line int `json:"line"`
Message string `json:"message"`
Tag string `json:"tag,omitempty"`
// contains filtered or unexported fields
}
MJMLProblem is a compile error or warning with its line (0 when unknown). Message is in English; In writes it in a reader's language.
func Lint ¶
func Lint(src string) []MJMLProblem
Lint returns layout warnings the MJML compiler doesn't report: images wider than their column (Outlook draws them at full width and breaks the layout) and columns adding up to more than their section. They are in English; LintIn writes them in a reader's language.
type MJMLThumbItem ¶
type MJMLThumbItem struct {
H int `json:"h,omitempty"`
W int `json:"w,omitempty"`
Accent bool `json:"accent,omitempty"`
Row []MJMLThumbItem `json:"row,omitempty"`
}
MJMLThumbItem is one bar of a template's wireframe thumbnail in the gallery: a grey block of height H (px) and width W (% of the thumbnail; 0 = full), an accent pill for buttons, or a row of blocks for columns.
func Thumb ¶
func Thumb(src string) []MJMLThumbItem
Thumb derives the gallery wireframe from a document: a short bar for the header, a block for a hero image, a row of blocks for columns, lines for text and a pill for a button. It keeps at most five items and stops at the first one that doesn't fit the thumbnail, so no bar is cut off.
type Node ¶
type Node struct {
Tag string
Attrs []Attr
Children []*Node
// Inner is the raw content of ending tags (mj-text, mj-button, mj-raw…),
// which hold HTML rather than MJML elements.
Inner string
// Marker is the ReputeCast block a preceding <!-- rc:… --> comment names
// ("footer", "header-logo"), empty otherwise.
Marker string
// Line is the 1-based line of the opening tag.
Line int
// Start and End are byte offsets of the element in the source.
Start, End int
}
Node is one element of an MJML document.
func Parse ¶
Parse reads an MJML document and returns its <mjml> root. It is lenient about whitespace, attribute quoting, comments and void tags, and reports tags that are never closed with their line.
type ParseError ¶
ParseError is a syntax problem with its line. Message is in English; In writes it in a reader's language.
func (*ParseError) Error ¶
func (e *ParseError) Error() string
type Result ¶
type Result struct {
HTML string
Errors []MJMLProblem
Duration time.Duration
}
Result is the outcome of a server-side compile.
type Section ¶
type Section struct {
// Index is the position among mj-body's elements (comments excluded).
Index int `json:"index"`
Tag string `json:"tag"`
// Label names the section the way the layer tree does: "header", "hero",
// "2 columns", "text", "footer".
Label string `json:"label"`
// Marker is the ReputeCast block it was inserted from ("footer"), if any.
Marker string `json:"marker,omitempty"`
Line int `json:"line"`
// Hash fingerprints the section's source, to tell which sections changed
// between two versions.
Hash string `json:"-"`
}
Section is one top-level block of <mj-body>.