mj-include injected JSON subdocument

[mifi]

Update: I created a library mjml-dynamic for this.

Given that it's possible to define the document using JSON, I would love to be able to include such JSON partials from a mjml xml document.

This would allow users to easily customise parts of the content of their emails using the JSON structure created from JS code, while still providing an overall layout defined in mjml. This eliminates the need to use a templating language for replacing placeholders etc in the mjml document, and would eliminate all issues related to correctly escaping and injection attacks with untrusted data.

Example mj-include could have a json option:

// template.mjml
<mjml>
  <mj-body>
    <mj-include path="header.mjml" />

    <mj-include json="mytable" />

    <mj-include path="footer.mjml" />
  </mj-body>
</mjml>

Then when rendering to html, we could inject this JSON:

const mytable = {
    tagName: 'mjml',
    attributes: {},
    children: [{
        tagName: 'mj-body',
        attributes: {},
        children: [{
            tagName: 'mj-section',
            attributes: {},
            children: [{
                tagName: 'mj-column',
                attributes: {},
                children: [{
                    tagName: 'mj-image',
                    attributes: {
                        'width': '100px',
                        'src': '/assets/img/logo-small.png'
                    }
                },
                {
                    tagName: 'mj-divider',
                    attributes: {
                        'border-color' : '#F46E43'
                    }
                }, 
                {
                    tagName: 'mj-text',
                    attributes: {
                        'font-size': '20px',
                        'color': '#F45E43',
                        'font-family': 'Helvetica'
                    },
                    content: 'Hello World'
                }]
            }]
        }]
    }]
};

const mjml = fs.readFileSync('template.mjml', 'utf-8');
const { html } = mjml2html(mjml, { json: { mytable } });

[iRyusa]

It's really a niche need with not so many use case. I don't think we'll provide anything like that

…

On Thu, Jan 12, 2023 at 4:28 PM Mikael Finstad ***@***.***> wrote: Given that it's possible to define the document using JSON, I would love to be able to include such JSON partials from a mjml xml document. This would allow users to easily customise parts of the content of their emails using the JSON structure created from JS code, while still providing an overall layout defined in mjml. This eliminates the need to use a templating language for replacing placeholders etc in the mjml document, and would eliminate all issues related to correctly escaping and injection attacks with untrusted data. Example mj-include could have a json option: // template.mjml <mjml> <mj-body> <mj-include path="header.mjml" /> <mj-include json="mytable" /> <mj-include path="footer.mjml" /> </mj-body> </mjml> Then when rendering to html, we could inject this JSON: const mytable = { tagName: 'mjml', attributes: {}, children: [{ tagName: 'mj-body', attributes: {}, children: [{ tagName: 'mj-section', attributes: {}, children: [{ tagName: 'mj-column', attributes: {}, children: [{ tagName: 'mj-image', attributes: { 'width': '100px', 'src': '/assets/img/logo-small.png' } }, { tagName: 'mj-divider', attributes: { 'border-color' : '#F46E43' } }, { tagName: 'mj-text', attributes: { 'font-size': '20px', 'color': '#F45E43', 'font-family': 'Helvetica' }, content: 'Hello World' }] }] }] }]}; const mjml = fs.readFileSync('template.mjml', 'utf-8');const { html } = mjml2html(mjml, { json: { mytable } }); — Reply to this email directly, view it on GitHub <#2619>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAELHTOB3OUHN2DWDOLVKXDWSAPKPANCNFSM6AAAAAATZMHWE4> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[mifi]

Thanks for your quick reply! I would think most people who use mjml would want to inject some kind of dynamic data into their emails, so I'm not sure why it's a nice use case. I'm pretty sure most people use templating languages for that and precompile their mjml to first insert this dynamic data with placeholders. But I think JSON could be an elegant alternative without having to use templates at all. Awesome project btw! 🙂

[iRyusa]

For templating, we let users plug any templating lang they want to MJML. If we open template features to MJML, people will ask for conditionnals/for-loops/... so we won't add anything like that to MJML. As you're already in node ecosystem, you can use Handlebars/MustacheJS/PugJs/...

[mifi]

I totally understand that you don't want to add any templating features. However I believe this JSON injection feature is completely different from templating, as it's instead about allowing dynamically created content using MJML's own JSON DSL. No condition/for-loop etc support would ever be needed, because the user can create the JSON subtree exactly how they like it, using plain javascript. But this can still be done using plain JSON (no .mjml files), and I respect the decision of not including this feature.

Maybe I'll try to make an npm module that wraps mjml to provide this functionality. Looking at #2465, it looks like it could be done with something like this:

import mjml2html from 'mjml'                          
import components from 'mjml-core/lib/components.js'
import Parser from 'mjml-parser-xml'
import jsonToXML from 'mjml-core/lib/helpers/jsonToXML.js'
import { readFile } from 'fs/promises';

const xml = await readFile('test.mjml');

const mjml = Parser(xml, {
      components,
      filePath: '.',
      actualPath: '.'
})

console.log(JSON.stringify(mjml, null, 2))
// console.log(jsonToXML(mjml))

// test.mjml

<mjml>
  <mj-body>
    <mj-include path="header.mjml" />

    <mj-json-include key="test" />

    <mj-include path="footer.mjml" />
  </mj-body>
</mjml>

...this outputs the whole JSON tree, in particular:

        {
          "file": ".",
          "absoluteFilePath": "",
          "line": 5,
          "includedIn": [],
          "tagName": "mj-json-include",
          "attributes": {
            "key": "test"
          }
        },

...then this node could be replaced with the custom JSON contents before calling mjml2html on it.

[mifi]

I created a library mjml-dynamic for this. Feel free to mention if you'd like:)

btw I love the simplicity of mjml and the fact that you don't do custom templating tags etc, just pure XML. The fact that mjml maps so well to JSON removes the need for it.