3. Email Generation from Templates

Let’s walk through an example of generating an email from subject and message body templates created in the previous section.

Before we begin, confirm that the Email Sending add-on is installed. If it is not currently installed, please install it before continuing.

Next, configure the required email sending parameters to enable successful email delivery.

Adding Notify by Email Button

Let’s add a Notify by Email button to the booking list view. This button will allow users to send an email notification to the creator of the booking selected in the data grid.

Find booking-list-view.xml in the Jmix tool window and double-click it. The view designer appears. Select action within the Jmix UI hierarchy panel or in the XML descriptor. Next click the Add button in the component inspector panel. From the drop-down list, choose Action:

add email action

Select the list_itemTracking action in the Add Action dialog. The list_itemTracking action will automatically become active only when a specific item is selected in the associated dataGrid.

Configure the following attributes for this action:

<action id="notifyEmail"
        type="list_itemTracking"
        icon="ENVELOPE"
        text="msg://notifyEmail.text"/>

Then, in the buttonsPanel hbox, add a button and associate it with the newly created action.

<hbox id="buttonsPanel" classNames="buttons-panel">
    <!--...-->
    <button id="notifyEmailButton" action="bookingsDataGrid.notifyEmail"/>
</hbox>

Generating an Email from the Template

Generate an ActionPerformedEvent handler method for the notifyEmailButton action. Add the logic to it:

@ViewComponent
private DataGrid<Booking> bookingsDataGrid;
@Autowired
private MessageTemplateProperties messageTemplateProperties; (1)
@Autowired
private MessageTemplatesGenerator messageTemplatesGenerator; (2)
@Autowired
private Emailer emailer; (3)
@Autowired
private Notifications notifications; (4)

@Subscribe("bookingsDataGrid.notifyEmail")
public void onBookingsDataGridNotifyEmail(final ActionPerformedEvent event) {
    Booking booking = bookingsDataGrid.getSingleSelectedItem();
    User creator = booking.getCreator(); (5)

    String email = creator.getEmail();
    if (email == null) {
        showNoEmailNotification(creator); (6)
        return;
    }

    List<String> messages = messageTemplatesGenerator.generateMultiTemplate()
            .withTemplateCodes("booking-email-subject", "booking-email-body") (7)
            .withParams(
                    Map.of(
                            "booking", booking,
                            "today", new Date(),
                            "penalty", 5000
                    )) (8)
            .generate();

    EmailInfo emailInfo = EmailInfoBuilder.create()
            .setAddresses(email)
            .setSubject(messages.get(0))
            .setBody(messages.get(1))
            .setBodyContentType("text/html; charset=UTF-8")
            .build(); (9)

    try {
        emailer.sendEmail(emailInfo); (10)
    } catch (EmailException e) {
        showSendingErrorNotification(email);
    }

    showSendingSuccessNotification(email); (11)
}

private void showSendingErrorNotification(String email) {
    notifications.create("Failed to send email to %s".formatted(email))
            .withThemeVariant(NotificationVariant.LUMO_ERROR)
            .show();
}

private void showNoEmailNotification(User creator) {
    notifications.create("%s did not specify an email".formatted(creator.getDisplayName()))
            .withThemeVariant(NotificationVariant.LUMO_ERROR)
            .show();
}

private void showSendingSuccessNotification(String email) {
    notifications.create("The message has been successfully sent to %s".formatted(email))
            .withThemeVariant(NotificationVariant.LUMO_SUCCESS)
            .show();
}
1 Provides configuration properties for the FreeMarker template engine.
2 A bean for generating messages from templates.
3 A bean for sending emails.
4 A bean for displaying notifications to the user.
5 Fetches the selected booking and its creator from the bookingsDataGrid.
6 Checks if the creator has an email address. If not, a notification is displayed, and the method exits.
7 Generates the message subject and body using FreeMarker templates (booking-email-subject and booking-email-body).
8 Passes dynamic parameters (booking, today, and penalty) to the templates.
9 Constructs an EmailInfo object with the recipient’s email, subject, body, and content type.
10 Attempts to send the email using the emailer bean. If an error occurs, a failure notification is displayed.
11 Displays a success notification if the email is sent successfully.

Summary

In this section, you learned how to work with message templates to automate email notifications within your app.

You gained practical experience in adding the Notify by Email button to a view, configuring an action to trigger the email sending process, and writing the code to dynamically generate an email message using data from the selected entity.

You also learned the importance of configuring email sending parameters and ensuring the Email Sending add-on is installed.