Використання шаблонів електронних листів ThymeLeaf та FreeMarker з Spring

1. Огляд

У нашій попередній статті ми побачили, як використовувати Spring для написання та надсилання текстових листів.

Але також можна використовувати движки шаблонів Spring для написання красивих електронних листів HTML з динамічним вмістом .

У цьому підручнику ми дізнаємось, як це зробити, використовуючи найвідоміші з них: Thymeleaf та FreeMarker .

2. Весняні електронні листи HTML

Почнемо з підручника Spring Email.

Спочатку ми додамо метод до класу EmailServiceImpl для надсилання електронних листів із тілом HTML:

private void sendHtmlMessage(String to, String subject, String htmlBody) throws MessagingException { MimeMessage message = emailSender.createMimeMessage(); MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8"); helper.setTo(to); helper.setSubject(subject); helper.setText(htmlBody, true); emailSender.send(message); }

Ми використовуємо MimeMessageHelper для заповнення повідомлення . Важливою частиною є справжнє значення, передане методу setText : воно визначає тип вмісту HTML.

Давайте подивимось зараз, як створити цей htmlBody за допомогою шаблонів Thymeleaf та FreeMarker.

3. Конфігурація чебрецю

Почнемо з конфігурації. Ми можемо виділити це в класі під назвою EmailConfiguration .

По-перше, ми повинні надати вирішувач шаблонів, щоб знайти каталог файлів шаблонів .

3.1. Шаблони як ресурси шляху до класу

Файли шаблонів можуть передаватися у файлі JAR , що є найпростішим способом збереження згуртованості між шаблонами та їх вхідними даними.

Щоб знайти шаблони з JAR, ми використовуємо ClassLoaderTemplateResolver . Наші шаблони знаходяться в головному каталозі / resources / mail-templates , тому ми встановлюємо атрибут Prefix щодо каталогу ресурсів :

@Bean public ITemplateResolver thymeleafTemplateResolver() { ClassLoaderTemplateResolver templateResolver = new ClassLoaderTemplateResolver(); templateResolver.setPrefix("mail-templates/"); templateResolver.setSuffix(".html"); templateResolver.setTemplateMode("HTML"); templateResolver.setCharacterEncoding("UTF-8"); return templateResolver; }

3.2. Шаблони із зовнішнього каталогу

В інших випадках ми можемо захотіти змінити шаблони без необхідності перебудовувати та розгортати . Для цього ми можемо розмістити шаблони у файловій системі.

Може бути корисним налаштувати цей шлях у application.properties, щоб ми могли змінювати його для кожного розгортання. Доступ до цієї властивості можна отримати за допомогою анотації @Value :

@Value("${spring.mail.templates.path}") private String mailTemplatesPath;

Потім ми передаємо це значення FileTemplateResolver замість ClassLoaderTemplateResolver у нашому методі thymeleafTemplateResolver :

FileTemplateResolver templateResolver = new FileTemplateResolver(); templateResolver.setPrefix(mailTemplatesPath);

3.3. Налаштуйте движок Thymeleaf

Останнім кроком є ​​створення заводського методу для двигуна Thymeleaf. Нам потрібно буде повідомити двигуну, який TemplateResolver ми вибрали, який ми можемо вводити через параметр до методу фабричного заготовки:

@Bean public SpringTemplateEngine thymeleafTemplateEngine(ITemplateResolver templateResolver) { SpringTemplateEngine templateEngine = new SpringTemplateEngine(); templateEngine.setTemplateResolver(templateResolver); templateEngine.setTemplateEngineMessageSource(emailMessageSource()); return templateEngine; }

Тут створений нами раніше розподільник автоматично вводиться Spring у заводський метод механізму шаблонів.

4. Конфігурація FreeMarker

Таким же чином, як Thymeleaf, у класі EmailConfiguration ми налаштуємо вирішувач шаблонів для шаблонів FreeMarker (.ftl ) :

Цього разу розташування шаблонів буде налаштовано у компоненті FreeMarkerConfigurer .

4.1. Шаблони в Classpath

Тут ми маємо ті самі варіанти, що і для Чебрецю. Давайте налаштуємо шаблони як ресурси шляху до класу:

@Bean public FreeMarkerConfigurer freemarkerClassLoaderConfig() { Configuration configuration = new Configuration(Configuration.VERSION_2_3_27); TemplateLoader templateLoader = new ClassTemplateLoader(this.getClass(), "/mail-templates"); configuration.setTemplateLoader(templateLoader); FreeMarkerConfigurer freeMarkerConfigurer = new FreeMarkerConfigurer(); freeMarkerConfigurer.setConfiguration(configuration); return freeMarkerConfigurer; }

4.2. Шаблони у файловій системі

Щоб налаштувати шаблони з іншого шляху у файловій системі, нам потрібно буде замінити екземпляр TemplateLoader :

TemplateLoader templateLoader = new FileTemplateLoader(new File(mailTemplatesPath));

5. Локалізація за допомогою Thymeleaf та FreeMarker

Для управління перекладами за допомогою Thymeleaf ми можемо вказати екземпляр MessageSource для механізму :

@Bean public ResourceBundleMessageSource emailMessageSource() { ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource(); messageSource.setBasename("mailMessages"); return messageSource; }
@Bean public SpringTemplateEngine thymeleafTemplateEngine() { ... templateEngine.setTemplateEngineMessageSource(emailMessageSource()); ... }

Потім ми створили пакети ресурсів для кожної підтримуваної локалі:

src/main/resources/mailMessages_xx_YY.properties

Оскільки FreeMarker пропонує локалізацію шляхом дублювання шаблонів , нам не потрібно налаштовувати там джерело повідомлень.

6. Зміст шаблонів Thymeleaf

Далі, давайте подивимось на файл template-thymeleaf.html :

Як бачимо, ми використовували позначення Thymeleaf, тобто $ {…} для змінних та # {…} для локалізованих рядків .

Оскільки механізм шаблонів правильно налаштований, використовувати його дуже просто: ми просто створимо об’єкт Context, який містить змінні шаблону (переданий тут як Карта ).

Потім ми передамо його в метод процесу разом із назвою шаблону:

@Autowired private SpringTemplateEngine thymeleafTemplateEngine; @Override public void sendMessageUsingThymeleafTemplate( String to, String subject, Map templateModel) throws MessagingException { Context thymeleafContext = new Context(); thymeleafContext.setVariables(templateModel); String htmlBody = thymeleafTemplateEngine.process("template-thymeleaf.html", thymeleafContext); sendHtmlMessage(to, subject, htmlBody); }

Тепер давайте подивимося, як зробити те саме з FreeMarker.

7. Вміст шаблонів FreeMarker

Як бачимо, синтаксис FreeMarker простіший, але знову ж таки він не управляє локалізованими рядками. Отже, ось англійська версія:

Hi ${recipientName}

${text}

Regards,

${senderName} at Baeldung

Потім ми повинні використовувати клас FreeMarkerConfigurer, щоб отримати файл шаблону, і, нарешті, FreeMarkerTemplateUtils для введення даних з нашої карти :

@Autowired private FreeMarkerConfigurer freemarkerConfigurer; @Override public void sendMessageUsingFreemarkerTemplate( String to, String subject, Map templateModel) throws IOException, TemplateException, MessagingException { Template freemarkerTemplate = freemarkerConfigurer.getConfiguration() .getTemplate("template-freemarker.ftl"); String htmlBody = FreeMarkerTemplateUtils.processTemplateIntoString(freemarkerTemplate, templateModel); sendHtmlMessage(to, subject, htmlBody); }

Щоб піти далі, ми побачимо, як додати логотип до нашого підпису електронної пошти.

8. Електронні листи із вбудованими зображеннями

Оскільки дуже часто включення зображень до електронного листа HTML, ми побачимо, як це зробити за допомогою вкладення CID.

The first change concerns the sendHtmlMessage method. We have to set MimeMessageHelper as multi-part by passing true to the second argument of the constructor:

MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");

Then, we have to get the image file as a resource. We can use the @Value annotation for this:

@Value("classpath:/mail-logo.png") Resource resourceFile;

Notice that the mail-logo.png file is in the src/main/resources directory.

Back to the sendHtmlMessage method, we'll add resourceFile as an inline attachment, to be able to reference it with CID:

helper.addInline("attachment.png", resourceFile);

Finally, the image has to be referenced from both Thymeleaf and FreeMarker emails using CID notation:

9. Висновок

У цій статті ми бачили, як надсилати електронні листи Thymeleaf та FreeMarker, включаючи багатий вміст HTML.

На закінчення, більша частина роботи пов’язана з Весною; отже, використання того чи іншого досить подібне для таких простих потреб, як надсилання електронних листів .

Як завжди, повний вихідний код прикладів можна знайти на GitHub.