Getting started with Themes

You can use Themes to create default content and layouts for Emails and Landing Pages written in the Twig templating language.

You can use Themes to also customize Forms, for example when visiting /form/ID, or using an iframe to embed a Form into a third party page. You can also customize the Form structure and fields but need to use PHP files, which disqualifies the Theme from being installable through Mautic’s Theme manager. It must therefore be manually uploaded to the server.

Finally, use a special system Theme to override system templates to avoid losing core code changes with future upgrades.

Directory structure

A Theme consists of three components: the configuration, Twig files with content, and thumbnails:

config.json
    html/
        email.html.twig
        form.html.twig
        message.html.twig
        page.html.twig
thumbnail.png
thumbnail_email.png
thumbnail_form.png
thumbnail_page.png

Configuration file

The configuration file tells Mautic how to utilize the Theme.

{
  "name": "Theme Name",
  "author": "John Doe",
  "authorUrl": "https://example.com",
  "features": [
    "email",
    "form",
    "page"
  ],
  "builder": ["legacy", "grapesjsbuilder"]
}

name

This is the name of the Theme as displayed in Mautic.

author

This displays in the Theme manager as credit to the author of the Theme. Any Themes added to Mautic Core use ‘Mautic Team’ as the author.

authorUrl

This enables the author to provide a URL displayed in the Theme manager.

features

An array of strings that tells Mautic which features the Theme supports. Currently recognized values are:

email The Theme is compatible with the Email Builder. See html/email.html.twig.

form The Theme is compatible with the customizing Forms. See html/form.html.twig.

page The Theme is compatible with the Page Builder. See html/page.html.twig.

A corresponding html/[feature].html.twig file is required for each feature supported. For example, if the Theme supports email, then there should be a html/email.html.twig file. See Twig files more information on each feature.

builder

This contains an array of strings declaring which Builder the Theme supports. This currently only applies to Themes that support page or email. By default, Themes without this line are only recognized by Mautic’s Legacy Builder. New Themes built should declare the specific Builders it supports.

Twig files

html/message.html.twig

This file is mainly used as the Landing Page for when a Contact unsubscribes or resubscribes to the system’s Emails. Other areas use this so all Themes should include it.

It requires echoing two variables: message and content.

message contains the string message such as “You have been unsubscribed.”

content is empty or contains the HTML of a Form associated with the Email as an unsubscribe Form.

<html>
    <head></head>
    <body>
        <div>
            <h2>{{ message|raw }}</h2>
            {% if content is defined %}
            <div>{{ content|raw }}</div>
            {% endif %}
        </div>
    </body>
</html>

html/email.html.twig

This file defines the base template when creating a new Email and should contain HTML suited for email clients.

The GrapesJS Builder supports the MJML email framework.

<mjml>
  <mj-body>
    <mj-raw>
      <!-- Company Header -->
    </mj-raw>
    <mj-section background-color="#f0f0f0">
      <mj-column>
        <mj-text font-style="bold" font-size="24px" color="#6f6f6f">My Company</mj-text>
      </mj-column>
    </mj-section>
    <mj-raw>
      <!-- Confirm  text -->
    </mj-raw>
    <mj-section background-color="#fafafa">
      <mj-column width="400px">
        <mj-text font-style="bold" font-size="22px" font-family="Helvetica Neue" color="#626262">Please confirm your subscription!</mj-text>
        <mj-button background-color="#F45E43" font-style="bold" href="#">Yes, subscribe me to the list</mj-button>
        <mj-text color="#525252" font-size="16" line-height="1.5">If you received this email by mistake, simply delete it. You won't be subscribed if you don't click the confirmation link above.<br/><br/>For questions about this list, please contact:
email@example.com</mj-text>
      </mj-column>
    </mj-section>
        <mj-raw>
      <!-- Confirm  text -->
    </mj-raw>
        <mj-section background-color="#fafafa">
      <mj-column width="400px">
        <mj-text color="#525252" line-height="1.2">
          <p>Company Name<br/>111 Amazing Street<br/>
            Beautiful City</p></mj-text>

      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

html/page.html.twig

This file defines the base template when creating a new Landing Page and can contain advanced HTML for browsers.

<!DOCTYPE html>
<html>
    <head>
        {% if page is defined %}
        <title>{pagetitle}</title>
        <meta name="description" content="{pagemetadescription}">
        {% endif %}
        {{ outputHeadDeclarations() }}
    </head>
    <body>
        {{ outputScripts('bodyOpen') }}
        {% block content %}{% endblock %}
        {{ outputScripts('bodyClose') }}
    </body>
</html>

html/form.html.twig

Mautic uses this file when accessing the form at /form/ID, embedding a Form in a Landing Page, or using the iframe method of embedding a Form into a third party page.

This should output the variables message, header, and content.

See Customizing Forms on how to customize Form fields.

<html>
    <head></head>
    <body>
        {% if message is defined %}
            <div>
                <h2>{{ message|raw }}</h2>
            </div>
        {% endif %}

        <div>
            {% if header is defined %}
            <h4>{{ header }}</h4>
            {% endif %}
            {{ content|raw }}
        </div>
    </body>
</html>

Thumbnails

The thumbnail should be a screenshot of the Theme with demo content. The dimensions should be 575x600px. Mautic displays thumbnails in the Email edit Form, Landing Page edit Form, and the Theme Manager.

Mautic looks for thumbnail.png by default, however if you want a specific image for different feature, you can add a thumbnail_[feature].png with a custom thumbnail. For example, thumbnail_email.png, thumbnail_page.png or thumbnail_form.png.