mj-hydrate v1.0.0

<mj-hydrate>

A powerful mjml component that embed the {{ handlebars }} syntax in your mjml files.

• Create and reuse UI components for emailing
• Create advanced layout logic
• Easily reusable for emails on steroids.

Usage

<mj-hydrate> needs:

• a .mjml file to include refered with the path attribute
• data to process the handlebars tag (remember to use {{{ syntax }}} to avoid HTML escaping).

You can pass data in many ways:

Inside the tag:

<!-- index.mjml -->
<mj-hydrate path="path/to/mjml.mjml">Lorem ipsum...</mj-hydrate>

<!-- path/to/mjml.mjml -->
<mj-text>{{{mjHydrateContent}}}</mj-text> 

Inject innerHTML in .mjml file

<mj-hydrate path="path/to/mjml.mjml">Lorem ipsum...</mj-hydrate>

and use in path/to/mjml.mjm

==> <mj-text>Lorem ipsum...</mj-text>

use global data object (only in nodejs)

see Define data section

<mj-hydrate path="path/to/mjml.mjml"></mj-hydrate>

and use in path/to/mjml.mjm

<mj-text>Hello {{user.firstname}} {{user.lastname}}</mj-text> 
==> <mj-text>Hello John Doe</mj-text>

use a specific key of the global data object (only in nodejs)

<mj-hydrate path="path/to/mjml.mjml" source="user"></mj-hydrate>

and use in path/to/mjml.mjm

<mj-text>Hello {{firstname}} {{lastname}}</mj-text> 
==> <mj-text>Hello John Doe</mj-text>

use your own key/value by passing attributes

<mj-hydrate path="path/to/mjml.mjml" firstname="Jane" lastname="Doh"></mj-hydrate>

and use in path/to/mjml.mjm

<mj-text>Hello {{firstname}} {{lastname}}</mj-text> 
==> <mj-text>Hello Jane Doh</mj-text>

use "mapping" attributes to pass a key/value list

<mj-hydrate path="path/to/mjml.mjml" mapping="key:value;foo:baz;"></mj-hydrate>

and use in path/to/mjml.mjm

<mj-text>{{key}} / {{foo}}</mj-text> 
==> <mj-text>value / baz</mj-text>

you can embed <mj-hydrate> in <mj-hydrate>

<mj-hydrate path="path/to/mjml.mjml"></mj-hydrate>

and use in path/to/mjml.mjm

<mj-text>This is a title</mj-text>
<mj-hydrate path="{{layout.header}}"></mj-hydrate>
==>
<mj-text>This is a title</mj-text>
<mj-section>... HEADER ...</mj-section>

you can use JSON.stringified string

Use simple quote around attribute value

The value of the attribute will be JSON.parse(), the value needs to be valid JSON (with double-quoted property). If this method throws an error, the value of the attribute will be used as string.

<mj-hydrate path="path/to/mjml.mjml" myJson='{"key": "a json value", "number":42}'></mj-hydrate>

and use in path/to/mjml.mjm

<mj-text>{{key}} // {{number}}</mj-text> 
==> <mj-text>a json value // 42</mj-text>

# Define data only in nodejs

Before executing the mjml2html(...) method, add some data to the context.

This is only available if you run the nodejs version. Not available in mjml app.

MjHydrate.setData({
    user: {
        firstname: "John",
        lastname: "Doe",
        email: "johndoe@yopmail.com"
    },
    layout: {
        header: "inc/header.mjml",
        footer: "inc/footer.mjml",
    }
    
})

mjml2html(...)

Limitations

<mj-hydrate> have some limitations as it works like an <mj-include> but it's not treated as one by the MJML XML Parser.

Then each <mj-hydrate> tag is treated by the parser in the XML flow, not before the other tags.

The MJML XML Parser seems to process the <mj-include> tags before the other tag.

Known bugs

• bad computation of <mj-column> width. To resolve the issue, specify the "width" attribute.

Usefull links

• Documentation MJML
• Documentation {{ handlerbars }}
• Complete exemple