Documentation
¶
Overview ¶
Package customcomponent is the in-repo example of the custom-component contract in package component. It holds the two shapes a component takes: Badge, a leaf with typed attributes and defaults, and Notice, a container that wraps child elements and contributes CSS to the document head.
A host registers the components on a renderer and gets new MJML elements, with no change to this repository:
renderer := mjmlgo.NewRenderer(mjmlgo.WithComponents(
customcomponent.Badge{},
customcomponent.Notice{},
))
var out bytes.Buffer
err := renderer.RenderFS(ctx, &out, fsys, "newsletter.mjml")
<mjml>
<mj-body>
<mj-section>
<mj-column>
<mj-badge text="New" background-color="#1f2937" />
<mj-notice>
<mj-text>Your trial ends on Friday.</mj-text>
</mj-notice>
</mj-column>
</mj-section>
</mj-body>
</mjml>
Both tags behave like built-in ones: an undeclared attribute is rejected, the declared validators run, an element under a leaf is rejected, and defaults from mj-attributes and mj-class apply before Render runs.
Badge is the shape of a leaf component:
- Name returns the tag, which must not shadow a built-in element and must be registered only once per renderer.
- AllowedAttributes declares every accepted attribute with its validator. Only the universal css-class and mj-class need no entry, and the returned map is read-only because the renderer may share it across renders.
- DefaultAttributes returns the values applied when the author wrote none.
- Render writes HTML from the node it is handed and the render context; it reads attributes through node.Node, never through package internals.
Notice is the shape of a container component:
- It implements component.ChildComponent and declares its children in AllowedChildren. A child outside the list is a disallowed-child error with the element path; a declared child nothing can render is rejected when the component is registered.
- Its Render calls component.RenderChildren to render the children it accepted - each with its own defaults applied and dispatched to its built-in or custom component - into a buffer of the component's own, then writes its wrapper markup around that HTML.
- It contributes head CSS with RenderContext.AddComponentHeadStyle (a named block), AddMediaQuery (rules inside the document's breakpoint media query) and AddFluidOnMobileClass (MJML's fluid-on-mobile rule for its own class).
Index ¶
- Constants
- type Badge
- type Notice
- func (Notice) AllowedAttributes() map[string]component.AttributeValidator
- func (Notice) AllowedChildren() []string
- func (Notice) DefaultAttributes(*component.RenderContext) map[string]string
- func (Notice) Name() string
- func (Notice) Render(ctx *component.RenderContext, w io.Writer, n *node.Node) error
Constants ¶
const BadgeTagName = "mj-badge"
BadgeTagName is the tag Badge registers.
const NoticeTagName = "mj-notice"
NoticeTagName is the tag Notice registers.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Badge ¶
type Badge struct{}
Badge is a small label rendered as a single table cell. It is a leaf: a child element under <mj-badge> is a disallowed child, because Badge does not implement component.ChildComponent.
func (Badge) AllowedAttributes ¶
func (Badge) AllowedAttributes() map[string]component.AttributeValidator
AllowedAttributes declares the attributes a document may write on <mj-badge>. css-class and mj-class are universal and need no entry.
func (Badge) DefaultAttributes ¶
func (Badge) DefaultAttributes(*component.RenderContext) map[string]string
DefaultAttributes returns the values applied when the author wrote none.
type Notice ¶
type Notice struct{}
Notice is a container: it declares mj-text children, renders them through component.RenderChildren into its own wrapper markup, and contributes CSS to the document head. It is the container counterpart of Badge.
func (Notice) AllowedAttributes ¶
func (Notice) AllowedAttributes() map[string]component.AttributeValidator
AllowedAttributes declares the attributes a document may write on <mj-notice>. css-class and mj-class are universal and need no entry.
func (Notice) AllowedChildren ¶
AllowedChildren declares the only child Notice accepts. A child outside the list is a disallowed-child error carrying the element path, and registration rejects the component if a declared child is not a content component.
func (Notice) DefaultAttributes ¶
func (Notice) DefaultAttributes(*component.RenderContext) map[string]string
DefaultAttributes returns the values applied when the author wrote none.
func (Notice) Render ¶
Render writes the notice's wrapper around its rendered children and contributes the CSS the wrapper depends on to the head.
The three head mechanisms a custom component has are all exercised here:
- AddComponentHeadStyle a named block, emitted once per document even when the document holds several notices;
- AddMediaQuery a class rule inside the document's breakpoint media query, with the Thunderbird, print and desktop-Outlook repeats MJML emits;
- AddFluidOnMobileClass the fluid-on-mobile rule for a class of its own.