implico/email-framework

本包最新版本（1.6.2）无可用许可证信息。

基于Smarty的电子邮件编码框架

维护者

详细信息

github.com/implico/email-framework

源代码

问题

安装: 68

依赖: 0

建议者: 0

安全: 0

星标: 2

关注者: 1

分支: 0

开放问题: 0

1.6.2 2017-10-16 02:37 UTC

Requires

Unknown License 68f35983eb2948504a136eedd0dca242198765c5

This package is not auto-updated.

Last update: 2024-09-14 18:26:18 UTC

README

Smarty模板引擎电子邮件编码框架。一种预处理程序，方便日常使用电子邮件模板。

概念与示例

在开发电子邮件模板时，你经常会遇到以下问题

  • 在整个项目中设置相同的（通常是史前的）属性和CSS属性，如

    <table width="600" cellpadding="0" cellspacing="0" border="0">
  <tr>
    <td width="600" valign="top">
      <img src="image.jpg" width="400" height="300" alt="Image" border="0" style="display: block">

  • 使用font标签不方便

  • 手动设置img的大小

  • 对于同一个布局有多个语言版本（或模板之间的其他微小差异）

  • 在整个项目中使用相同的值（如宽度等） - 这些值可以作为变量访问（在某些情况下，如果未设置，也可以取默认配置值，如字体参数）

生成的代码通常难以维护。

该框架提供了配置好的Smarty插件和CLI接口，因此您可以像这样开发项目

{$marginHeight = 50}
{table}
  {tr}
    {td colspan=2}
      {font size=20}Title{/font}
    {/td}
  {/tr}

  {margin height=$marginHeight colspan=2}

  {tr}
    {td width=400}
      {a href="http://example.com/"}{img src="image.jpg"}{/a}
    {/td}
    {td width=200 align=left padding="0 0 0 10px"}
      {font bold=true}{#configVariable#}{/font}
    {/td}
  {/tr}
{/table}

<p>
  Of course, you can use your own markup or easily create custom Smarty plugins, like {literal}{h1}Header{/h1}{/literal}.
</p>

并运行监视器

iemail compile [project_name] -w

代码被转换（可能根据实际设置而有所不同）为

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <style type="text/css"> #outlook a {padding:0;} body{width:100% !important; -webkit-text-size-adjust:100%; -ms-text-size-adjust:100%; margin:0; padding:0;} .ExternalClass {width:100%;} .ExternalClass, .ExternalClass p, .ExternalClass span, .ExternalClass font, .ExternalClass td, .ExternalClass div {line-height: 100%;} #backgroundTable {margin:0; padding:0; width:100% !important; line-height: 100% !important;} table td {border-collapse: collapse;} </style>
  </head>
  <body>
    <table cellpadding="0" cellspacing="0" border="0" align="center" width="600" style="border-collapse:collapse;mso-table-lspace:0pt;mso-table-rspace:0pt;">
      <tr>
        <td width="600" colspan="2" valign="top" align="center">
          <font color="#000000" size="5" face="Arial,Tahoma,sans-serif" style="font-size:20px;">Title</font>
        </td>
      </tr>
      <tr>
        <td height="50" colspan="2" style="font-size:1px;">&nbsp;</td>
      </tr>
      <tr>
        <td width="400" valign="top" align="center">
          <a href="http://example.com/" style="text-decoration:none;text-decoration:none !important;">
            <img src="image.jpg" width="400" height="200" alt="Click Show Images option to see the picture" vspace="0" hspace="0" border="0" style="display:block;margin:0;border:none;outline:none;text-decoration:none;-ms-interpolation-mode:bicubic;" />
          </a>
        </td>
        <td width="200" valign="top" align="left" style="padding:0 0 0 10px;">
          <b>
            <font color="#000000" size="3" face="Arial,Tahoma,sans-serif" style="font-size:13px;">This content is set in the configuration file</font>
          </b>
        </td>
      </tr>
    </table>
    
    <p>
      Of course, you can use your own markup or easily create custom Smarty plugins, like {h1}Header{/h1}.
    </p>
  </body>
</html>

安装

要使用此框架，您需要以下软件

  • PHP >= 5.5，已启用openssl和mbstring扩展
  • Composer
    • 对于Windows，使用安装程序
    • 对于Linux，全局安装
  • 可选，如果您想利用gulp（即每次更改时使用Browsersync进行实时浏览器刷新），则需要安装：nodejs和当然还有gulp（使用gulp-cli的新正确方式）

PHP安装

  • Windows

    1. 将下载的PHP存档（例如，PHP 5.6.x非线程安全Zip - 而不是7.x）解压到c:\PHP
    2. 将c:\PHP添加到您的PATH环境变量中
    3. 将c:\PHP\php.ini-development重命名为php.ini，编辑并取消注释
    • extension_dir = "ext"
    • extension=php_mbstring.dll
    • extension=php_openssl.dll

  • Linux - 在终端中运行

    sudo apt-get install php5-cli

框架安装

  1. 打开控制台/终端窗口。
  2. 运行
composer global require implico/email-framework
  1. 将Composer的全局bin文件夹添加到您的PATH变量中。首先，要获取路径，运行
composer global config bin-dir --absolute

然后

  • Windows：遵循说明
  • Linux：以root用户编辑/etc/environment文件（如果您在那里看不到PATH定义，则编辑/etc/profile）并重新启动系统
  1. 您现在可以开始一个新的项目 - 请参阅示例部分以了解更多信息。

框架更新

composer global update implico/email-framework

CLI

全局可执行文件名为iemail。从您的项目目录（例如，email-projects）运行它。

初始化项目目录

iemail create projects_dir_name

使用指定的project_name创建一个新的项目目录（您的项目将保存在其中）。创建_custom子目录，其中包含主配置文件和自定义插件目录。

选项

  • projects_dir_name：目录名称

示例

iemail create email-projects

初始化新项目

iemail init project_name [base_project_name]

使用指定的 project_name 创建新项目。在 create 命令创建的目录中运行。

base_project_name 的内容被复制到一个新目录中。首先，脚本在当前工作目录中搜索它，然后在核心框架的 samples 中。

选项

  • base_project_name：输入要复制的基项目名称；默认为 plain

示例（基于 multilang 核心示例创建 test 项目）

iemail init test multilang

编译项目

iemail compile project_name [-s script_name(s)] [-d projects_dir] [-w] [-o m|f]

使用指定的 project_name 编译项目。选项

  • -s（--script）：脚本名称（s），如果未设置 - 编译所有脚本
  • -d（--dir）：项目目录，默认为当前目录
  • -w（--watch）：监视模式 - 开始监视项目目录，并在任何更改时编译
  • -o（--output）：输出模式 - 压缩（m）或带有缩进的格式化（f）

示例（编译并监视 test 项目以检测更改）

iemail compile test -w

发送测试邮件

iemail send project_name [-s script_name] [-d projects_dir] [-t address(es)] [-f filename] [--fromname name] [--fromaddress address] [-u subject] [-a attachment(s)] [--minified] [-i interval_ms] [--errorstop]

为指定的 project_name 发送测试邮件。所有图像都转换为 cid 并嵌入。 SMTP 和默认选项在配置文件中设置。

选项

  • -s（--script）：脚本名称，默认为 index
  • -d（--dir）：项目目录，默认为 projects
  • -t（--toaddress）：目标地址（s），默认为配置设置（对于多个，请使用： -t a1@a.com -t a2@a.com）
  • -f（--toaddressfn）：项目根目录中的文本文件名称，其中包含目标地址（由换行符分隔）
  • --fromname：发件人名称，默认为配置设置
  • --fromaddress：发件人地址，默认为配置设置
  • -u（--subject）：电子邮件主题，默认为配置设置
  • -a（--attachments）：从输出目录附加一个或多个文件（对于多个，请使用： -a file1 -a file2）
  • -m（--minified）：使用压缩版脚本而不是格式化
  • -l（--log）：将地址记录到项目的根目录中
    • log-done.txt：发送成功的地址
    • log-fail.txt：最终发送失败的地址
  • -i（--interval）：发送每封邮件之间的间隔（毫秒），默认为 1000
  • --errorstop：出错时退出

示例（将 test 项目发送到 test@example.com）

iemail send test -t test@example.com

Gulp 集成

新初始化的项目目录包含 package.json 和 gulpfile.js，允许您使用 gulp 监视和 Browsersync 在每次源代码更改时实时刷新浏览器。

对于首次运行，在使用 iemail create 后，进入新项目目录并执行（假设已安装 nodejs 和 gulp）

npm install

然后您可以使用简单的 gulp api

gulp -p project_name [-s script_name] [-a] [-r]

编译项目并打开网页浏览器。然后监视项目，在更改时编译并重新加载浏览器。

选项

  • -p（--project）：项目名称（必需）
  • -s（--script）：脚本名称，默认为 index；如果没有指定（gulp -p sample -s），则将在浏览器中列出所有脚本
  • -a（--params）：传递给编译命令的附加参数，例如 gulp -p sample -a ' -om' 将生成压缩版本（注意前面的空格）
  • -r（--resume）：防止打开新的浏览器窗口

目录结构

框架

框架目录结构概述

  • core：PHP 文件、Smarty 插件和主配置文件
  • samples：示例项目，也用于引导
  • vendor：使用 Composer 安装的模块

项目目录

_custom 子目录包含可选内容：自定义主配置文件和您的Smarty插件 - 将它们放在 plugins 目录中。

其他目录包含每个项目的文件。每个目录都具有以下结构

  • configs：整个项目的配置和特定脚本的配置
  • views：视图模板
    • layout.tpl：主要视图（布局）文件
    • scripts：如果您想要为单个主要布局（在语言或颜色、图形等细节上有所不同）拥有多个视图，请将其放在此处；默认情况下，只有一个脚本：script.tpl；请参阅多语言示例以了解用法
  • styles：CSS样式（作为Smarty模板，因此您可以访问配置变量）
    • layout.tpl：包含在视图布局模板中的主要样式（您可以重命名或创建新的样式文件）
    • inline.tpl：使用 CssToInlineStyles 放置的内联样式（您不能重命名它，但可以在其中包含其他模板）
  • outputs：编译的项目文件（HTML）；将您的图像放在这里

插件参考

参考方案

{plugin_name parameter1=0 parameter2=#config_value# parameter3=false}

位置

  • parameter1 被设置为 0
  • parameter2 被设置为配置值 config_value
  • parameter3 不显示

与HTML中相同的属性名称不是camelCase（如 cellpadding，bordercolor），其他如 lineHeight 是。

标准参数包括

  • style：额外的CSS样式，例如 border: 1px solid #000;
  • id：id属性
  • class：由空格分隔的一个或多个类
  • attrs：额外的HTML属性，例如 valign="middle" border="0"

以下不会进行描述。

函数插件只有一个开始标签，例如 {margin height=20}，其他（块）插件必须具有结束标签，例如 {table}...{/table}。

指定宽度、高度和字体大小时不使用单位。

表格

{table width=#tableWidth# cellpadding=0 cellspacing=0 bgcolor=false border=0 bordercolor=false align=#tableAlign# maxWidth=false style=false id=false class=false attrs=false}

注释

  • maxWidth：设置 max-width 样式并创建一个Outlook条件包装表格

Tr

{tr style=false id=false class=false attrs=false}

Td

{td width=#tdWidth# height=false colspan=1 align=#tdAlign# valign=#tdValign# padding=0 overflow=#tdOverflow# bgcolor=false background=false backgroundNoRepeat=true lineHeight=#tdLineHeight# borderRadius=false noFont=!#fontStyleTdTag# fontFamily=#fontFamily# fontSize=#fontSize# fontColor=#fontColor# style=false id=false class=false attrs=false}

注释

  • 当使用 background（图像）时，您可能想要使用 bgcolor 设置一个后备颜色；请注意，作为cids嵌入的背景图像似乎在Gmail移动应用中不起作用（但在外部URL引用时可以工作）
  • backgroundNoRepeat 使背景图像填充整个单元格空间
  • padding：设置为CSS padding 属性值，例如 10px 20px
  • noFont：即使将 fontStyleTdTag 配置值设置为 true，也会应用字体样式
  • overflow：设置为 true 以隐藏（缩写）

垂直边距（函数）

创建一个指定高度的行。

{margin height=false colspan=1 bgcolor=false style=false id=false class=false attrs=false}

字体

{font color=#fontColor# size=#fontSize# sizeForce=false family=#fontFamily# bold=false italic=false underlined=false centered=false noWrap=false style=false id=false class=false attrs=false}

注释

  • sizeForce：将 !important 添加到CSS font-size 属性值（当您不希望字体在例如移动Gmail应用中缩放时很有用）
  • bold、italic、underlined、centered：具有从第一个字母派生的别名；设置任何真值，例如 {font b=1}
  • noWrap 添加样式并将内容空白替换为 &nbsp;

链接

{a href="" target=#aTarget# textDecoration=#aTextDecoration# buttonHeight=false style=false id=false class=false attrs=false}

注释

  • textDecoration：使用CSS值设置 text-decoration 属性
  • buttonHeight：如果您想将链接“按钮化”，设置其高度；您应该将 sizeForce=true 参数添加到该按钮内部使用的 {font} 中，以防止在移动Gmail应用中缩放字体；您可能还需要在包装 {td} 时设置按钮的背景颜色；有关跨客户端解决方案，请参阅按钮插件

按钮

{button href="" width=false height=false bgcolor=false bordercolor=false borderRadius=false centered=true style=false id=false class=false attrs=false}

注释

  • 创建一个与Microsoft Outlook兼容的按钮（基于 Bulletproof email buttons）
  • centered：指按钮内容的居中，请记住为包含的 {td} 设置 align="center"
  • 您可以嵌套标记以获取字体样式，例如。
{button href="http://example.com/" width=150 height=40 bgcolor="#e10000" borderRadius=10}
  {font size=14 color="#ffffff" bold=1}See more{/font}
{/button}

图片（功能）

{img src="" width=false height=false autoSize=#imgAutoSize# alt=#imgAlt# padding=false margin=0 marginV=0 marginH=0 align=false display=#imgDisplay# border=0 bordercolor=false style=false id=false class=false attrs=false}

注释

  • autoSize：如果为 true，则当未指定宽度和高度时，使用实际图像尺寸
  • marginV 和 marginH：垂直和水平边距（设置 vspace 和 hspace 属性 + CSS 边距）

强制剥离

要强制空白剥离（在格式化的版本中），请使用以下语法：#(strip)[stripped_code]#(/strip)


配置

默认设置在主文件 core/config.conf 中定义。要更改它们，编辑（如果不存在则创建）以下文件

  • [projects_dir]/_custom/config.conf：应用于所有项目的自定义通用配置
  • [projects_dir]/[project_name]/configs/config.conf：应用于项目的配置
  • [projects_dir]/[project_name]/configs/scripts/[script_name].conf：每个脚本的配置（命名方式与脚本名称相同）

大多数最新选项都在主文件中进行了描述。您可以更改（包括其他）

  • 编码、字体定义模式（作为 font 标签、span 和/或在 td 单元格标签中）
  • 默认表格和单元格属性、字体家族/颜色/大小、链接和图片样式
  • 发送测试电子邮件选项，例如默认主题/目标地址或SMTP访问

示例

启动新项目

要创建一个用于存放项目的目录，请使用 create 命令

iemail create email-projects

这将创建一个名为 email-projects 的目录，包含自定义配置和插件文件夹。

然后，转到此目录并运行 init 命令

iemail init my_project_name

默认情况下，基本（复制源）项目是核心中的 plain 示例（除非您创建自己的 plain 项目，则它将成为引导默认项目）。您可以通过第二个参数指定基本项目

iemail init my_project_name other_project_name

如果基本项目在当前目录中未找到，它将在框架核心的 sample 目录中进行搜索。

初始化后，以监视模式运行编译器

iemail compile my_project_name -w

打开位于您的项目 outputs 目录中的脚本 HTML 文件。每次编译时都刷新，以查看更改。

或者，使用更方便的 gulp 集成指南 来监视更改。

纯文本

这是一个纯文本、引导型项目。仅包含具有主表格定义的布局。

网格

这展示了如何构建更复杂的项目，包括列表和按钮。

响应式

展示了如何构建响应式（实际上 - 流体）项目。注意

  • 配置选项 tableWidth 和 tdWidth 设置为 100%
  • 布局模板
    • <meta name="viewport"> 被取消注释，主要针对支持媒体查询的 Apple 设备（请参阅限制表格宽度的最后一个媒体查询）
    • 添加了 Outlook max-width 漏洞作为条件注释（在主表格定义之前和之后）
    • 向主表格添加了 max-width（例如 Gmail）
  • 所有宽度单位（表格、单元格、图像）都设置为百分比

多语言

多语言项目展示了为英语和波兰语定义语言特定内容的两种方法。概念是布局模板（layout.tpl）通过语言脚本（请参阅 Smarty 模板继承），在这种情况下 en.tpl 和 pl.tpl）进行扩展。

第一种方法是设置脚本特定的配置值在 configs/scripts 目录中，然后只需像 {#title#} 一样使用它。

第二种方法是使用语言脚本中的块注入内容。


集成

要在您的 PHP 脚本中使用该框架

  • 使用 Composer 进行安装

    {
  "require": {
    "implico/email-framework": "1.*"
  },
}

  • 要渲染电子邮件，首先创建一个 Smarty 对象

    $smarty = new \Smarty();

  • 添加插件目录

    $smarty->addPluginsDir(path_to_core_plugins_dir);

    将 path_to_core_plugins_dir 替换为实际路径，例如 __DIR__.'/vendor/email-framework/core/plugins/'。

  • 加载配置文件

    $smarty->configLoad(path_to_config_file1);  //first one should be the core config, e.g. __DIR__.'/vendor/email-framework/core/config.conf'
$smarty->configLoad(path_to_config_file2);  //project or script-specific config files

  • 设置模板所引用的目录，如下所示

    $smarty->setTemplateDir(array(
  0 => path_to_project,
  'layouts' => path_to_project_layouts,
  'scripts' => path_to_project_scripts,
  'styles' => path_to_project_css
));

  • 执行脚本，然后使用您喜欢的库（如 PHPMailer 或 Swift Mailer）发送邮件

    $html = $smarty->fetch(path_to_script)

//send the email
//...

  • 对于 PHPMailer，您可以使用 msgHTML 方法嵌入图片作为 cids


快速提示

  • 要创建垂直线（<hr>），可以使用以下代码

    {margin height=1 bgcolor="#000000"}

  • 要创建无序列表，使用 &bull; 实体，例如

    {tr}
  {td align=center}
    {font}&bull;{/font}
  {/td}
  {td}
    {font}list item 1{/font}
  {/td}
{/tr}

  • 如果您有重复的代码，可以利用 函数；如果代码在项目间重复，可以考虑创建自己的插件（模板函数或块函数）

  • 以像素为单位设置行高，而不是百分比或数字（Outlook 会将其视为像素）；如果 Gmail 移动应用在小屏幕上错误转换，可以通过媒体查询在 CSS 中针对更现代的客户端应用补丁，例如

    @media all {
  #footer { line-height: 1.4; }
}

  • 为了达到精度（并避免在某些情况下 Outlook 的错误），通过嵌套表格来定义单元格填充，而不是设置 CSS 的 padding 属性

  • 在表格上设置背景色，而不是在单元格上设置（在 iPhone 上会导致间隙线）


待办事项

[x] 与 gulp 集成

[ ] 使用 TinyPNG

[ ] 当项目所需的子目录之一不存在时的错误处理


替代方案

看看其他有趣的工具和框架