Garagist.Mjml

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:

Property	Description
`owa`	If set to `"desktop"`, switch force desktop version for older (self-hosted) version of Outlook.com that doesn't support media queries. Defaults to `null`
`lang`	Used as `<html lang="">` attribute. Defaults to `null`
`dir`	Used as `<html dir="">` attribute. Defaults to `null`
`backgroundColor`	The general background color (color formats). Defaults to `null`
`cssClass`	Class name, added to the root HTML element created. Defaults to `null`
`width`	Email's width in px. Defaults to `600`
`title`	Defines the document's title that browsers show in the title bar or a page's tab. Defaults to `null`
`preview`	This allows you to set the preview that will be displayed in the inbox of the recipient. If you use Garagist.Mautic, there is no need to set this, as it will be set automatically. Defaults to `null`
`attributes`	Set `mj-attributes` in the `mj-head`. Defaults to `null`
`htmlAttributes`	Set `mj-html-attributes` in the `mj-head`. Need to be a nested DataStructure where the first key is the `mj-selector` and the children are `mj-html-attribute` (`itemKey` is the name and `item` is the value). Defaults to `null`
`breakpoint`	This allows you to control on which breakpoint the layout should go desktop/mobile. Integer value in pixels. Defaults to `null`
`head`	Additional tags for `mj-head`. Defaults to `null`
`content`	The content section of the email. Defaults to `null`
`trackingPixel`	Add the markup for the tracking pixel. If you use Garagist.Mautic, there is no need to set this, as it will be set automatically. Read the setting `Garagist.Mjml.trackingPixel`
`debugUrl`	Debug url for logging. Defaults to `null`
`defaults`	Set some default CSS setting for the email. Look at `Settings.Garagist.yaml` to see the defaults. Read the setting `Garagist.Mjml.theme.defaults`
`colors`	Adds colors as `mj-class`. More about this below. Take a look to `Settings.Garagist.yaml` to see the defaults. Read the setting `Garagist.Mjml.theme.colors`
`fontSize`	Adds font sizes as `mj-class`. More about this below. Look at `Settings.Garagist.yaml` to see the defaults. Read the setting `Garagist.Mjml.theme.fontSize`
`fontWeight`	Adds font weights as `mj-class`. More about this below. Look at `Settings.Garagist.yaml` to see the defaults. Read the setting `Garagist.Mjml.theme.fontWeight`

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.

Name		Name	Last commit message	Last commit date
Latest commit History 43 Commits
.github		.github
Classes		Classes
Configuration		Configuration
Resources/Private		Resources/Private
.editorconfig		.editorconfig
.gitattributes		.gitattributes
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Garagist.Mjml

Installation

Usage

Use with the official API from MJML

Use with docker

Development with ddev

Mixin to hide nodes

Fusion prototypes

`Garagist.Mjml:Presentation.Spacer`

`Garagist.Mjml:Presentation.Image`

The `image` property

The `thumbnail` property

`Garagist.Mjml:Presentation.Page`

Colors

Font sizes

Font weights

`Garagist.Mjml:Helper.Visibility`

`Garagist.Mjml:Component`

`Garagist.Mjml:Page`

Eel helper

`Mjml.compile(mjml, url)`

`Mjml.theme(path)`

About

Releases 5

Languages

License

Garagist/Garagist.Mjml

Folders and files

Latest commit

History

Repository files navigation

Garagist.Mjml

Installation

Usage

Use with the official API from MJML

Use with docker

Development with ddev

Mixin to hide nodes

Fusion prototypes

Garagist.Mjml:Presentation.Spacer

Garagist.Mjml:Presentation.Image

The image property

The thumbnail property

Garagist.Mjml:Presentation.Page

Colors

Font sizes

Font weights

Garagist.Mjml:Helper.Visibility

Garagist.Mjml:Component

Garagist.Mjml:Page

Eel helper

Mjml.compile(mjml, url)

Mjml.theme(path)

About

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases 5

Languages

`Garagist.Mjml:Presentation.Spacer`

`Garagist.Mjml:Presentation.Image`

The `image` property

The `thumbnail` property

`Garagist.Mjml:Presentation.Page`

`Garagist.Mjml:Helper.Visibility`

`Garagist.Mjml:Component`

`Garagist.Mjml:Page`

`Mjml.compile(mjml, url)`

`Mjml.theme(path)`