Getting started with Themes

Note

此页面的内容需要进行重大更新。旧页面包含过时且可能不准确的信息。您仍然可以通过 Mautic Developer Documentation archived repository 访问它。

如果您有兴趣帮助开发此页面和其他新内容的，请考虑加入文档编写工作。

请阅读 Contributing Guidelines 和 Contributing to Mautic’s documentation 以开始您的贡献。

您可以使用主题来创建电子邮件和着陆页的默认内容和布局，这些内容使用 Twig templating language 编写。

您还可以使用主题自定义 Mautic 表单，例如在访问 /form/ID 时，或使用 iframe 将表单嵌入到第三方页面中。您可以自定义表单结构和字段，但需要使用 PHP 文件，这使得该主题无法通过 Mautic 的主题管理器进行安装。因此，必须手动将其上传到服务器。

最后，使用一个特殊的 system 主题来覆盖系统模板，以避免在未来升级时丢失核心代码更改。

目录结构

一个主题由三个组件组成：配置、包含内容的 Twig 文件和缩略图。

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

配置文件

配置文件告诉 Mautic 如何使用该主题。

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

name

这是在 Mautic 中显示的该主题的名称。

author

这会在主题管理器中显示，以表彰该主题的作者。添加到 Mautic 核心的主题使用“Mautic Team”作为作者。

authorUrl

这允许作者提供一个 URL，并在主题管理器中显示。

features

一个字符串数组，告诉 Mautic 该主题支持哪些功能。当前已识别的值包括：

email 该主题与电子邮件构建器兼容。请参阅 themes/getting_started:html/email.html.twig。

为每个支持的功能，需要一个对应的 html/[feature].html.twig 文件。例如，如果主题支持 email，则应存在一个 html/email.html.twig 文件。有关每个功能的更多信息，请参阅 Twig files。 builder

此部分包含一个字符串数组，声明主题支持的构建器。目前这仅适用于支持 page 或 email 的主题。默认情况下，不包含此行的主题只能由 Mautic 的 Legacy Builder 识别。新创建的主题应声明其支持的具体构建器。

Twig 文件

`html/message.html.twig`

该文件主要用作联系人取消订阅或重新订阅系统邮件时的着陆页。其他区域也使用此文件，因此所有主题都应包含它。

它需要回显两个变量：message 和 content。

message 包含字符串消息，例如“您已取消订阅”。

content 为空或包含与电子邮件关联的表单的 HTML，该表单用作取消订阅表单。

<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`

该文件定义了创建新电子邮件时的基本模板，应包含适用于电子邮件客户端的 HTML。

GrapesJS 构建器支持 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. 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”>

Company Name 111 Amazing Street 
Beautiful City</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>

Template sandbox restrictions

Mautic 在受限的 Twig 沙箱环境中渲染用户上传的主题模板。该沙箱会阻止某些可能导致远程代码执行、数据泄露或文件系统探测的功能和过滤器。

如果您的主题模板使用了受限的功能或过滤器，Mautic 会抛出异常，例如 SecurityNotAllowedFilterError 或 SecurityNotAllowedFunctionError。请使用替代方法，这些方法不需要使用受限的操作。

缩略图

缩略图应是包含演示内容的该主题的屏幕截图。其尺寸应为 575x600 像素。Mautic 在电子邮件编辑表单、着陆页编辑表单以及主题管理器中显示缩略图。

默认情况下，Mautic 会查找 thumbnail.png 文件，但是，如果您希望为不同的功能使用特定的图像，您可以添加一个名为 thumbnail_[feature].png 的自定义缩略图文件。例如，thumbnail_email.png、thumbnail_page.png 或 thumbnail_form.png。

准备您的主题以用于 Packagist

Mautic 使用 Packagist 来分发主题和插件。您必须采取某些步骤，以确保您的主题已准备好进行分发。

确保在您主题目录的根目录下存在一个 composer.json 文件。请确保该文件包含以下信息，特别是验证 Mautic 的最低支持版本：

{
  "name": "mautic/theme-yourthemename",
  "description": "A theme for Mautic",
  "type": "mautic-theme",
  "keywords": ["mautic", "theme"],
  "extra": {
    "install-directory-name": "yourthemename"
  },
  "minimum-stability": "dev",
  "require": {
    "mautic/core": "^5.0"
  }
}

确保您在主题的 .github/workflows 文件夹中添加一个 close_pull_requests.yml 文件。此文件会自动关闭在主题存储库中打开的拉取请求。请查看其他主题以获取示例。
确保将您的主题添加到以下文件中，或创建这些文件：
- .github/subtree-splitter-config.json - 此文件设置了 Mautic GitHub 仓库中的文件夹与主题的独立存储库之间的连接。在合并对核心代码的更改（这些更改会影响此主题）或进行发布时，GitHub 会自动将更改推送到该主题的存储库。请将您的主题添加到列表末尾。
- .github/workflows/gitsplit/theme-yourthemename.json - GitHub Actions 使用此文件来同步对主题存储库的更改。为添加到 Mautic 仓库中的每个新主题创建一个文件。
- .githu/workflows/split-monorepo-in-multi-repo.yml - 此文件由 GitHub Action 使用，用于创建矩阵，该矩阵在拆分存储库并将更改推送到主题存储库时使用。请使用新的主题名称更新此文件。
将您的主题以及前面步骤中的相关文件提交到 Mautic 的代码仓库（Pull Request）。合并后，GitHub Action 会自动将更改推送到您的主题代码仓库。
请核心团队在 Mautic GitHub 组织中创建一个新的代码仓库，用于存放您的主题。他们必须将核心团队成员添加到该代码仓库，以便 GitHub Actions 能够正常工作。代码仓库的命名规范为 theme-yourthemename。
合并后，请要求核心团队为您的主题创建一个 Packagist 包。创建完成后，提交另一个 Pull Request，将该包添加到 composer.json 文件中。确保您也运行 composer require mautic/theme-yourthemename 命令，这将更新 composer.lock 文件，并将您的新主题添加进去。然后，检查 composer.json 文件，并将该包从 ‘require’ 部分移动到 ‘replace’ 部分，使用 self.version。提交对 composer.json 和 composer.lock 文件的更改。
合并后，提交您最后的 Pull Request 到 :xref:`Recommended Project 代码仓库，将您的主题添加到 composer.json 文件末尾的列表中。
庆祝一下，您成功了！恭喜 🎉。