MJML4J

A java based mjml implementation.

Require at least java 17.

Javadoc: https://javadoc.io/doc/ch.digitalfondue.mjml4j/mjml4j/latest/ch.digitalfondue.mjml4j/ch/digitalfondue/mjml4j/Mjml4j.html

Why

As far as I know, there is no pure java version of mjml. This library is quite compact with a single dependency - the html5 parser (jfiveparse).

License

mjml4j is licensed under the MIT License.

The code is based on the following projects:

• https://github.com/mjmlio/mjml/
• https://github.com/SebastianStehle/mjml-net
• https://github.com/LiamRiddell/MJML.NET

Status

Most of the mj-* tags are supported. It's currently missing:

• ~~mj-include: will be implemented~~ implemented in 1.1.1
• ~~mj-html-attributes: will be supported when the work on css selector support is done.~~ implemented in 1.2.0
• mj-style: the inline attribute will be ignored: will be supported when the work on css selector support is done. WIP

Additionally, no pretty print/minimization of the output is provided.

Download

maven:

<dependency>
   <groupId>ch.digitalfondue.mjml4j</groupId>
   <artifactId>mjml4j</artifactId>
   <version>1.2.1</version>
</dependency>

gradle:

implementation 'ch.digitalfondue.mjml4j:mjml4j:1.2.1'

Use

If you use it as a module, remember to add requires ch.digitalfondue.mjml4j; in your module-info.

The api is quite simple:

package ch.digitalfondue.test;

import ch.digitalfondue.mjml4j.Mjml4j;

public class App {
   public static void main(String[] args) {
      Mjml4j.Configuration configuration = new Mjml4j.Configuration("en");
      String renderedTemplate = Mjml4j.render("""
              <mjml>
                <mj-body>
                  <mj-section>
                    <mj-column>

                      <mj-image width="100px" src="https://github.com/digitalfondue/mjml4j/raw/mjml4j-1.2.2/assets/img/logo-small.png"></mj-image>

                      <mj-divider border-color="#F45E43"></mj-divider>

                      <mj-text font-size="20px" color="#F45E43" font-family="helvetica">Hello World</mj-text>

                    </mj-column>
                  </mj-section>
                </mj-body>
              </mjml>
              """, configuration);
      System.out.println(renderedTemplate);
   }
}

The render static method accept as a parameters: 1) a string which will be then parsed and processed by the html5 parser (jfiveparse), or it can accept a org.w3c.dom.Document 2) a configuration object with language, optionally a direction and an IncludeResolver

mj-include support

By default, mjml4j don't have an IncludeResolver configured, thus mj-include will not work out of the box, you must implement or specify yourself. mjml4j offer 2 implementations: - FileSystemResolver if your resources are present on the filesystem - SimpleResourceResolver a resolver that need a ResourceLoader to be implemented

Development notes:

• the project has a java 17 baseline
• the code is formatted using the maven spotless plugin. Use mvn spotless:apply to format it

TODO:

• when increasing min java version to 21, use https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/SequencedMap.html as an interface instead of directly using LinkedHashMap...
• validation api:
• add "parent element" check
• attribute unit type check
• improve the renderer
• cleanup/rewrite the box model, kinda hacky
• more robust handling of invalid input (check mjml behaviour)
• check differences/import tests
• allow custom components