开始使用

本章节介绍如何在应用程序中使用邮件模板。我们将创建一个简单的应用层管理用户的订阅。这个应用程序会在订阅生命周期事件发生时使用邮件模板发送邮件。

首先，按照 安装 部分的说明在项目中添加邮件模板扩展组件。

创建数据模型和界面

我们创建下列实体类：

  1. Customer 实体，带有字段：

    • firstName，为 String 类型。

    • lastName，为 String 类型。

    • email，为 String 类型。

  2. Subscription 实体，带有字段：

    • name，为 String 类型。

    • active，为 Boolean 类型。

    • expiryDate，为 Date 类型。

    • customer 关联至 Customer，一对多。

为 Customer 和 Subscription 实体创建编辑和浏览界面。

创建邮件模板

我们用可视化设计器创建第一个模板。

启动应用程序，打开 Administration（管理） → Email templates（邮件模板） 界面，点击 Create（新建） → From designer（设计器） 按钮

然后会打开 Email template（邮件模板） 界面。修改下列字段：

  • Name（名称）：Subscription created。

  • Code（编码）：subscription_created。

  • Subject（标题）：Subscription created。

下面创建模板内容，可以从右侧的工具箱将需要的元素拖放至画布中。

我们的模板包含三个 section。

template designer

在第一个 section 中，我们添加公司的 logo 图片。找到 Image 元素并放置于第一个 section 中。

可以为图片提供一个链接或者从文件存储上传图片。

第二个 section 包含来自 “customer” 的信息。在模板中，我们可以使用模板参数，这些参数会自动创建。在 Text 元素中输入带参数掩码的信息：Hi, ${customer.firstName} ${customer.lastName}!

text element

然后切换至 Parameters and formats（参数和格式） 标签页并点击 Create from template（从模板创建）。系统会创建一个别名为 customer，实体类型为 Customer 的模板参数。

param template

可以为每个模板参数设置正确的参数类型，并配置其他值。

我们为模板中的参数定义一个格式。切换至 Main（主要信息） 标签页，在画布中添加 Text 元素。输入下列内容：Your subscription will be expired on ${subscription.expiryDate?string("YYYY-MM-dd")}。注意，我们将订阅的过期时间添加为模板参数，并使用特殊的值格式。

text format

可以看到 Subscription 实体类型的 subscription 变量已经创建。

param with format

切换至 Main（主要信息） 标签页，在画布中添加 Text 元素。输入下列内容：Best regards, Сompany team。模板创建完成。

打开 Email templates（邮件模板） 浏览界面，选择刚创建的模板，并点击 Send（发送） 按钮。

send email

填写必需的参数，然后点击 Preview（预览） 按钮，检查生成的邮件内容。

preview

添加事件监听器

现在为应用程序加一些自动化处理的工作。

如需在订阅生命周期事件中自动发送模板邮件，我们需要创建事件监听器。在监听器中，当订阅创建时，我们使用邮件模板 API 发送 "Subscription created" 邮件。

@Component
public class SubscriptionEventListener {

    private static final Logger log =
            LoggerFactory.getLogger(SubscriptionEventListener.class);

    @Inject
    EmailTemplates emailTemplates;  (1)

    public static final String CREATED_TEMPLATE_CODE = "subscription_created";

    @EventListener
    void onSubscriptionSaving(EntitySavingEvent<Subscription> event) {
        if (event.isNewEntity()) {
            try {
                emailTemplates.buildFromTemplate(CREATED_TEMPLATE_CODE)
                        .setTo(event.getEntity().getCustomer().getEmail()) (2)
                        .setBodyParameter("subscription", event.getEntity()) (3)
                        .setBodyParameter("customer", event.getEntity().getCustomer()) (4)
                        .sendEmail(); (5)
            } catch (TemplateNotFoundException | EmailException |
                    ReportParameterTypeChangedException e) {
                log.info(e.getMessage());
            }
        }
    }
}
1 EmailTemplates 提供流式构建器接口，可用于自定义邮件模板。
2 设置邮件模板的 to 属性。
3 设置 subscription 模板参数。
4 设置 customer 模板参数。
5 使用 io.jmix.email.Emailer 发送填写完成的邮件模板。

启动应用程序，检查在创建了订阅之后会发送邮件。