customcomponent

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 8 Imported by: 0

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

View Source
const BadgeTagName = "mj-badge"

BadgeTagName is the tag Badge registers.

View Source
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.

func (Badge) Name

func (Badge) Name() string

Name returns the element's tag name.

func (Badge) Render

func (b Badge) Render(_ *component.RenderContext, w io.Writer, n *node.Node) error

Render writes the badge's HTML. The renderer has already validated the author attributes and applied both the component's defaults and the document's mj-attributes/mj-class defaults, so every accessor below sees the effective value.

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

func (Notice) AllowedChildren() []string

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) Name

func (Notice) Name() string

Name returns the element's tag name.

func (Notice) Render

func (Notice) Render(ctx *component.RenderContext, w io.Writer, n *node.Node) error

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.

Jump to

Keyboard shortcuts

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