garagist/mjml

Integrate MJML into Neos. Works great togehter with Garagist.Mautic

0.2.3 2022-09-29 11:42 UTC

Requires

• php: ^8.0
• carbon/eel: ^2.0
• carbon/notification: ^2.4
• garagist/plaintext: ^0.1
• neos/neos: ^7.3 || ^8.0

Suggests

• garagist/mautic: To use the Mautic integration

GPL-3.0-or-later

• Jon Uhlmann

README

MJML is a markup language to build responsive email templates by providing a semantic syntax and a rich standard component library.

This package adds the Eel Helper for compiling MJML markup as well as some Fusion prototypes, which allow using TailwindCSS like classes. But more about that later.

Installation

Add the package to your site package:

composer require --no-update garagist/mjml

Then run composer update in your project root.

Usage

You can use this package with the official API from MJML or with Docker and the MJML image from Adrian Rudnik.

Use with the official API from MJML

To use it with the MJML API, set apiEndpoint to true. You must also set the applicationID and the secretKey. If you don't want to use the environment variables, you can simply overwrite them in your Settings.yaml file.

Garagist:
  Mjml:
    apiEndpoint: true
    applicationID: "%env:MJML_API_APPLICATION_ID%"
    secretKey: "%env:MJML_API_SECRET_KEY%"

Use with docker

Set the enviroment variable MJML_API_ENDPOINT, or set it in your Settings.yaml:

Garagist:
  Mjml:
    apiEndpoint: "mjml:80"

Development with ddev

If you use ddev for development, you can use the following configuration:

version: "3.6"
services:
  mjml:
    container_name: ddev-${DDEV_SITENAME}-mjml
    hostname: ${DDEV_SITENAME}-mjml
    image: adrianrudnik/mjml-server
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    environment:
      - HTTP_EXPOSE=8080
      - CORS=*
      - MJML_KEEP_COMMENTS=true
      - MJML_VALIDATION_LEVEL=strict
      - MJML_MINIFY=false
      - MJML_BEAUTIFY=true
      - HEALTHCHECK=false

After that, your MJML endpoint is something like ddev-DDEV_SITENAME-mjml:80

Mixin to hide nodes

This package adds a node type mixin Garagist.Mjml:Mixin.Visibility. With this, you can show content nodes only on the website or in the newsletter. Just add the mixin to your content nodes:

Foo.Bar:Content.Text:
  superTypes:
    Garagist.Mjml:Mixin.Visibility: true

Fusion prototypes

This package adds several Fusion prototypes for easier integration of your MJML markup. Let's start with the small ones:

Garagist.Mjml:Presentation.Spacer

This prototype is great for adding a spacer between elements. If you want to add a colored, full-width bar with a height of 40px, you can do it like that:

<Garagist.Mjml:Presentation.Spacer fullWidth={true} height={40} background-color="#00adee" />

All properties except fullWidth and height are transferred to the mj-section.

Garagist.Mjml:Presentation.Image

This prototype is a small helper to render mj-image or mj-carousel-image. Inside a mj-carousel, set carousel to true to render a mj-carousel-image.

The image property

The image property is a Neos.Fusion:DataStructure where you can pass all options from Neos.Neos:ImageUri.

The thumbnail property

The thumbnail property is a Neos.Fusion:DataStructure where you can pass all options from Neos.Neos:ImageUri. This is used to set a different image to have a thumbnail different than the image it's linked to. This has no effect if carousel is set to false.

All properties except carousel, image and thumbnail are transferred to mj-image or mj-carousel-image.

Garagist.Mjml:Presentation.Page

This is the heart of the Fusion MJML prototypes. It generates the MJML code, which is compiled to HTML. It has the following properties:

Colors

Adds multiple mj-class tags for each set colors. Here, the color key is prefixed to control each property. Let's assume the following configuration:

Garagist:
  Mjml:
    theme:
      colors:
        black: "#000"
        tahiti:
          light: "#67e8f9"
          DEFAULT: "#06b6d4"
          dark: "#0e7490"

With <mj-text mj-class="text-black"> the text color is set to black. With <mj-text mj-class="text-tahiti-light"> the text color is set to #67e8f9. A special case is the DEFAULT value: This can be reached without specifying DEFAULT: <mj-text mj-class="text-tahiti">.

• text-COLOR-PATH sets color
• bg-COLOR-PATH sets background-color
• container-bg-COLOR-PATH sets container-background-color
• inner-bg-COLOR-PATH sets inner-background-color

Font sizes

Adds multiple mj-class tags for each set font sizes. Let's assume the following configuration:

Garagist:
  Mjml:
    theme:
      fontSize:
        xs:
          pixel: 12
          lineHeight: 16px
        sm: 14

With <mj-text mj-class="text-xs"> you'll set the font size to 12 pixel and the line height to 16px. With <mj-text mj-class="text-sm"> you'll set the font size to 14 pixel.

Font weights

Adds multiple mj-class tags for each set font-weight. Let's assume the following configuration:

Garagist:
  Mjml:
    theme:
      fontWeight:
        normal: 400
        semibold: 600

With <mj-text mj-class="font-normal"> you'll set the font weight to 400. With <mj-text mj-class="font-semibold"> you'll set the font weight to 600.

Garagist.Mjml:Helper.Visibility

This small helper reads the property mjmlVisibility (from the mixin Garagist.Mjml:Mixin.Visibility) and returns true or false based on the arguments in the request and if the user is in the backend. This prototype is is added to Neos.Neos:ContentComponent and Neos.Neos:Content) automatically.

Garagist.Mjml:Component

This prototype uses Neos.Fusion:Component and adds the helper Garagist.Mjml:Helper.Visibility.

Garagist.Mjml:Page

This prototype uses Garagist.Mjml:Presentation.Page and sets the following properties:

• language: Set the lang attribute from the <html> tag
  • If language is set, this will be used as the language.
  • If languageDimension (set to language by default) is present, the language of the documentNode will be used.
  • If no language dimension is set, Neos.Flow.i18n.defaultLocale will be used as language.
  • If none of the above can be set, no language will be defined.
• title: Try to get the property titleOverride or title from the documentNode
• debugUrl: Generates the URL of the current URL for the log output

Furthermore, various prototypes will be adopted:

• Neos.Neos:ContentCase
  • Checks if there is a prototype with .Mjml (e.g. Foo.Bar:Content.Text.Mjml) and outputs it.
  • If no prototype is found, it creates a message that the renderer was not found, based on the Garagist.Mjml.debugOutputMode setting. The following values are possible:
    • true: Creates a visible warning message
    • comment: Creates a HTML comment with the warning
    • false: Does not output a warning message
  • By default, the visible warning is issued in the Development context, and the warning is hidden in the Production context.
• Neos.Neos:NodeUri: Set absolute to true
• Neos.Neos:ConvertUris:
  • Set absolute to true
  • Set forceConversion to true
  • Set externalLinkTarget to ''
  • Set resourceLinkTarget to ''

Eel helper

Mjml.compile(mjml, url)

Compile the mjml string to HTML. The url is for the log output.

Mjml.theme(path)

Get the setting from Garagist.Mjml.theme. It is similar to the eel helper Configuration.setting with only special treatment for DEFAULT values: If you have set these colors:

Garagist:
  Mjml:
    theme:
      colors:
        tahiti:
          light: "#67e8f9"
          DEFAULT: "#06b6d4"
          dark: "#0e7490"

Mjml.theme('colors.tahiti') will return #06b6d4 as this is the default value. The other values like Mjml.theme('colors.tahiti.dark') etc. will return the corresponding color. In short, it works similar to the theme() function in TailwindCSS.