README

使用 MJML 渲染 Twig 邮件，这是唯一使响应式邮件变得简单的框架。

需求

此插件需要 Craft CMS 3.0.0-beta.23 或更高版本。

安装

要安装插件，请按照以下说明操作。

1. 打开您的终端并转到您的 Craft 项目目录

    cd /path/to/project
   

2. 然后告诉 Composer 加载插件

    composer require superbig/craft-mjml
   

3. 在控制面板中，转到设置 → 插件，并点击 MJML 的“安装”按钮。

MJML 概述

MJML 是一种旨在减少编写响应式电子邮件痛苦的标记语言。其语义语法使其简单直接，其丰富的标准组件库可以加快您的开发速度并简化电子邮件代码库。MJML 的开源引擎生成符合最佳实践的、高质量的响应式 HTML。

配置 MJML

<?php
/**
 * MJML plugin for Craft CMS 3.x
 *
 * Render Twig emails with MJML, the only framework that makes responsive email easy.
 *
 * @link      https://superbig.co
 * @copyright Copyright (c) 2018 Superbig
 */

/**
 * MJML config.php
 *
 * This file exists only as a template for the MJML settings.
 * It does nothing on its own.
 *
 * Don't edit this file, instead copy it to 'craft/config' as 'mjml.php'
 * and make your changes there to override default settings.
 *
 * Once copied to 'craft/config', this file will be multi-environment aware as
 * well, so you can have different settings groups for each environment, just as
 * you do for 'general.php'
 */

return [
    // The path to where the your version of Node is located, i.e. `/usr/local/bin/node`
    'nodePath'  => '',

    // The path to where the MJML cli installed with npm is located, i.e. `/usr/local/bin/mjml`
    'mjmlCliPath'   => '',

    // cli config args, e.g. `--config.minify true`',
    'mjmlCliConfigArgs'   => '',

    // The app id received by email
    'appId'     => '',

    // Enter the secret key received by email
    'secretKey' => '',
];

使用 MJML

您可以使用 MJML CLI 本地使用，或使用 MJML API。

要使用 CLI，您需要安装 Node 和 mjml 可执行文件

要使用 API，您需要 请求 API 密钥。

使用 MJML CLI 的动态示例

{% apply mjmlCli %}
    {%- apply spaceless %}
        <mjml>
            <mj-body>
                <mj-section>
                    <mj-column>
                        <mj-text font-size="20px" color="#F45E43" font-family="helvetica">{{ entry.title }}</mj-text>
                    </mj-column>
                </mj-section>
                {% for block in entry.matrixTestField.all() %}
                    {% if block.type == 'image' %}
                        {% set image = block.image.one() %}
                        {% if image %}
                            <mj-section>
                                <mj-column>
                                    <mj-image width="100" src="{{ image.url }}"></mj-image>
                                </mj-column>
                            </mj-section>
                        {% endif %}
                    {% endif %}
                    {% if block.type == 'text' %}
                        <mj-section><mj-column><mj-divider border-color="#F45E43"></mj-divider><mj-text font-size="20px" color="#F45E43" font-family="helvetica">{{ block.text }}</mj-text></mj-column></mj-section>
                    {% endif %}
                {% endfor %}
            </mj-body>
        </mjml>
    {% endapply %}
{% endapply %}

要使用 API，请将 mjmlCli 替换为 mjml。

缓存

上面的示例将被缓存。如果您正在传递 Twig 变量，每个输出将独特，使缓存无效。

在这种情况下，您可能想使用 include 方法

{{ craft.mjml.include('path/to/template.twig', { 
    subject: 'Static subject', 
    email: contact.email, 
}) }}

include 方法默认使用 CLI 选项，但您可以将它设置为使用 MJML API，通过传递 api 作为第三个选项，如下所示

{{ craft.mjml.include('path/to/template.twig', { 
    subject: 'Static subject', 
    email: contact.email, 
}, 'api') }}

这里是一个示例，通过 Campaign 插件内的通讯模板传递联系人。模板路径相对于您的网站模板根目录。

这将首先渲染 MJML 模板一次，将其缓存，然后为每个实例渲染动态部分。

包含

如果您想使用包含，有一个注意事项

Twig 内置的 include 方法在插件 include 方法传递的模板中与 MJML 结合使用时不起作用。

这是因为 MJML 首先渲染，然后再渲染 Twig，所以如果您在部分中包含 MJML，则不会渲染。

MJML 包含的解决方案

请注意，这仅支持 CLI 选项。

对于部分，解决方案是使用 <mj-include /> 标签。这里引用的任何部分都将相对于网站模板根目录。

<mj-include path="./mjml-partial.twig" />

请注意，您必须在此处附加文件扩展名。这将解析为 /templates/mjml-partial.twig。

关于 mj-include 的另一个注意事项是，当前在检查渲染的 MJML 模板的缓存时，不会包含部分的内容。

这意味着如果您渲染了一个包含 <mj-include /> 部分的 MJML 模板，然后更改部分的内容，缓存将过时，并且您的模板不会反映更改。

目前的一个解决方案是在这种情况发生时清除 storage/runtime/temp/mjml 文件夹。

由 Superbig 提供