garagist/

将 MJML 集成到 Neos。与 Garagist.Mautic 一起使用效果极佳

维护者

详细信息

github.com/Garagist/Garagist.Mjml

源代码

问题

安装次数: 226

依赖项: 0

建议者: 0

安全: 0

星星: 1

关注者: 2

分支: 0

公开问题: 0

类型:neos-plugin

0.2.3 2022-09-29 11:42 UTC

Requires

Suggests

GPL-3.0-or-later 384a8861dfddd0233088cf7e541fea081caa0e74

This package is auto-updated.

Last update: 2024-09-07 00:22:30 UTC

README

Latest stable version GitHub stars GitHub watchers GitHub license GitHub issues GitHub forks

MJML 是一种标记语言，通过提供语义语法和丰富的标准组件库来构建响应式电子邮件模板。

此包添加了编译 MJML 标记的 Eel Helper 以及一些 Fusion 原型，允许使用 TailwindCSS 类。但稍后我们再详细说明。

安装

将包添加到您的站点包中

composer require --no-update garagist/mjml

然后在项目根目录中运行 composer update

使用方法

您可以使用来自 MJML 的官方 API 或与 Docker 以及 Adrian Rudnik 的 MJML 镜像 一起使用此包。

使用 MJML 官方 API

要使用 MJML API，将 apiEndpoint 设置为 true。您还必须设置 applicationID 和 secretKey。如果您不想使用环境变量，您可以直接在您的 Settings.yaml 文件中覆盖它们。

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

使用 Docker

设置环境变量 MJML_API_ENDPOINT，或在您的 Settings.yaml 中设置它

Garagist:
  Mjml:
    apiEndpoint: "mjml:80"

使用 ddev 进行开发

如果您使用 ddev 进行开发，可以使用以下配置

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

之后，您的 MJML 端点可能是这样的 ddev-DDEV_SITENAME-mjml:80

Mixin 隐藏节点

此包添加了一个节点类型 Mixin Garagist.Mjml:Mixin.Visibility。使用它，您只能在网站上或在通讯录中显示内容节点。只需将 Mixin 添加到您的内容节点即可

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

Fusion 原型

此包添加了几个 Fusion 原型，以便更容易地集成您的 MJML 标记。让我们从小的开始

Garagist.Mjml:Presentation.Spacer

此原型非常适合在元素之间添加间隔。如果您想添加一个宽度为全宽、高度为 40px 的彩色栏，可以这样做

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

除了 fullWidth 和 height 之外的所有属性都传递给 mj-section。

Garagist.Mjml:Presentation.Image

这是一个渲染 mj-image 或 mj-carousel-image 的小助手。在一个 mj-carousel 中，将 carousel 设置为 true 以渲染 mj-carousel-image。

image 属性

image 属性是一个 Neos.Fusion:DataStructure，您可以传递来自 Neos.Neos:ImageUri 的所有选项。

thumbnail 属性

thumbnail 属性是一个 Neos.Fusion:DataStructure，您可以传递来自 Neos.Neos:ImageUri 的所有选项。这用于设置一个不同的图像，使其缩略图与链接的图像不同。如果将 carousel 设置为 false，则此属性无效果。

除了 carousel、image 和 thumbnail 之外的所有属性都传递到 mj-image 或 mj-carousel-image。

Garagist.Mjml:Presentation.Page

这是 Fusion MJML 原型的核心。它生成 MJML 代码，并将其编译为 HTML。它有以下属性：

颜色

为每个颜色集添加多个 mj-class 标签。在此，颜色键作为前缀来控制每个属性。以下是一个配置示例：

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

使用 <mj-text mj-class="text-black"> 将文本颜色设置为黑色。使用 <mj-text mj-class="text-tahiti-light"> 将文本颜色设置为 #67e8f9。一个特殊情况是 DEFAULT 值：可以通过不指定 DEFAULT 来达到这个值：<mj-text mj-class="text-tahiti">。

  • text-COLOR-PATH 设置 color
  • bg-COLOR-PATH 设置 background-color
  • container-bg-COLOR-PATH 设置 container-background-color
  • inner-bg-COLOR-PATH 设置 inner-background-color

字体大小

为每个字体大小集添加多个 mj-class 标签。以下是一个配置示例：

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

使用 <mj-text mj-class="text-xs"> 将字体大小设置为 12 像素和行高为 16px。使用 <mj-text mj-class="text-sm"> 将字体大小设置为 14 像素。

字体粗细

为每个字体粗细集添加多个 mj-class 标签。以下是一个配置示例：

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

使用 <mj-text mj-class="font-normal"> 将字体粗细设置为 400。使用 <mj-text mj-class="font-semibold"> 将字体粗细设置为 600。

Garagist.Mjml:Helper.Visibility

这个小助手读取属性 mjmlVisibility（来自混合 Garagist.Mjml:Mixin.Visibility）并根据请求中的参数和用户是否在后台返回 true 或 false。此原型自动添加到 Neos.Neos:ContentComponent 和 Neos.Neos:Content。

Garagist.Mjml:Component

此原型使用 Neos.Fusion:Component 并添加了助手 Garagist.Mjml:Helper.Visibility。

Garagist.Mjml:Page

此原型使用 Garagist.Mjml:Presentation.Page 并设置以下属性：

  • language：设置 <html> 标签的 lang 属性
    • 如果设置了 language，则将其用作语言。
    • 如果存在 languageDimension（默认设置为 language），则使用 documentNode 的语言。
    • 如果没有设置语言维度，则使用 Neos.Flow.i18n.defaultLocale 作为语言。
    • 如果以上所有设置都无法完成，则不定义语言。
  • title：尝试从 documentNode 获取属性 titleOverride 或 title
  • debugUrl：生成当前 URL 的 URL 用于日志输出

此外，还将采用各种原型

  • Neos.Neos:ContentCase
    • 检查是否存在具有 .Mjml（例如 Foo.Bar:Content.Text.Mjml）的原型并输出它。
    • 如果没有找到原型，则会根据 Garagist.Mjml.debugOutputMode 设置创建一条渲染器未找到的消息。以下是一些可能的值：
      • true：创建一个可见的警告消息
      • comment：创建一个带有警告的 HTML 注释
      • false：不输出警告消息
    • 默认情况下，在 开发 环境下发出可见警告，在 生产 环境下隐藏警告。
  • Neos.Neos:NodeUri：将 absolute 设置为 true
  • Neos.Neos:ConvertUris:
    • 将 absolute 设置为 true
    • 将 forceConversion 设置为 true
    • 将 externalLinkTarget 设置为 ''
    • 将 resourceLinkTarget 设置为 ''

Eel 辅助函数

Mjml.compile(mjml, url)

将 mjml 字符串编译为 HTML。其中 url 用于日志输出。

Mjml.theme(path)

从 Garagist.Mjml.theme 获取设置。它与 eel 辅助函数 Configuration.setting 类似，只是对 DEFAULT 值有特殊处理：如果您设置了以下颜色

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

Mjml.theme('colors.tahiti') 将返回 #06b6d4，因为这是默认值。其他值如 Mjml.theme('colors.tahiti.dark') 等将返回相应的颜色。简而言之，它的工作方式类似于 theme() 函数在 TailwindCSS。