Message Templates API

Основной точкой входа в API дополнения является Spring bean MessageTemplatesGenerator. Этот бин предоставляет методы для генерации сообщений из шаблонов и может быть внедрен в ваши сервисы или экраны. Например:

@Autowired
private MessageTemplatesGenerator messageTemplatesGenerator;

Создание сообщений на основе шаблонов

Вы можете сгенерировать сообщение из шаблона с помощью метода generateMessage(). Этот метод принимает два параметра:

  1. Template Code: Уникальный код шаблона сообщения, который вы хотите использовать.

  2. Parameter Map: Map<String, Object>, содержащая динамические данные, которые будут вставлены в шаблон.

Предположим, у вас есть шаблон с кодом booking-confirmation, который содержит плейсхолдеры, такие как {booking.title} и {booking.room}. Вы можете сгенерировать сообщение следующим образом:

Map<String, Object> params = new HashMap<>();
params.put("booking.title", "Conference Room Booking");
params.put("booking.room", "Room 101");

String message = messageTemplatesGenerator.generateMessage("booking-confirmation", params);

Использование генераторов шаблонов

Чтобы упростить процесс генерации сообщений и повторного использования шаблонов или параметров, дополнение предоставляет три специализированных генератора. Эти генераторы позволяют динамически создавать сообщения, объединяя шаблоны с картами параметров. Ниже приводится подробное описание каждого генератора и способов их использования.

SingleTemplateGenerator

SingleTemplateGenerator используется для создания сообщения на основе одного шаблона и одной карты параметров. Это идеально подходит для сценариев, когда вам нужно сгенерировать одно сообщение, используя определенный шаблон и фиксированный набор данных.

Пример использования:

messageTemplatesGenerator.generateSingleTemplate()
             .withTemplateCode("my-template") (1)
             .addParam("username", "admin") (2)
             .addParam("firstName", "John")
             .addParam("lastName", "Doe")
             .generate(); (3)
1 Укажите код шаблона
2 Добавьте параметры
3 Сгенерируйте сообщение

Основные характеристики:

  • Один шаблон: Использует один шаблон для генерации сообщения.

  • Одна карта параметров: Применяет одну карту параметров к шаблону.

  • Результат: Возвращает одно сообщение, в котором шаблон заполнен предоставленными параметрами.

MultiTemplateGenerator

MultiTemplateGenerator используется для создания сообщений на основе нескольких шаблонов и одной карты параметров. Это полезно, когда вам нужно сгенерировать несколько сообщений, используя разные шаблоны, но один и тот же набор данных.

Пример использования:

List<String> messages = messageTemplatesGenerator.generateMultiTemplate()
             .withTemplateCodes("my-first-template", "my-second-template") (1)
             .addParam("username", "admin") (2)
             .addParam("firstName", "John")
             .addParam("lastName", "Doe")
             .generate(); (3)
1 Укажите несколько кодов шаблонов
2 Добавьте параметры
3 Сгенерируйте сообщения

Основные характеристики:

  • Несколько шаблонов: Использует несколько шаблонов для генерации сообщений.

  • Одна карта параметров: Применяет одну и ту же карту параметров ко всем шаблонам.

  • Результат: Возвращает список сообщений, каждое из которых сгенерировано из отдельного шаблона, но с использованием одних и тех же параметров.

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

Каждый шаблон будет извлекать и использовать только те параметры, которые ему действительно нужны. Любые неиспользованные параметры в предоставленной карте будут просто проигнорированы конкретным шаблоном. Это позволяет эффективно генерировать сообщения из нескольких шаблонов с различными требованиями к параметрам, используя один вызов.

Если шаблон содержит параметр, который не найден в предоставленной карте параметров, генерация сообщения завершится неудачей. Однако это поведение можно изменить, предварительно настроив конфигурацию FreeMarker таким образом, чтобы она обрабатывала отсутствующие параметры без выдачи исключения.

MultiParamTemplateGenerator

MultiParamTemplateGenerator используется для создания сообщений на основе одного шаблона и нескольких карт параметров. Это идеально подходит для сценариев, когда вам нужно сгенерировать несколько сообщений, используя один и тот же шаблон, но с разными наборами данных.

Пример использования:

List<String> messages = messageTemplatesGenerator.generateMultiParamTemplate()
             .withTemplateCode("my-template") (1)
             .addParams(Map.of( (2)
                 "username", "admin",
                 "firstName", "John",
                 "lastName", "Doe"
             ))
             .addParams(Map.of( (3)
                 "username", "user",
                 "firstName", "Mary",
                 "lastName", "Smith"
             ))
             .generate(); (4)
1 Укажите код шаблона
2 Добавьте первый набор параметров
3 Добавьте второй набор параметров
4 Сгенерируйте сообщения

Основные характеристики:

  • Один шаблон: Использует один шаблон для генерации сообщений.

  • Несколько карт параметров: Применяет разные карты параметров к одному и тому же шаблону.

  • Результат: Возвращает список сообщений, каждое из которых сгенерировано из одного и того же шаблона, но с использованием разных параметров.

Использование конфигурации FreeMarker

Дополнение Message Templates позволяет настраивать генерацию сообщений. Для дальнейшей оптимизации этого процесса вы можете создавать и применять собственные конфигурации FreeMarker. Это позволяет вам адаптировать способ обработки шаблонов FreeMarker. Вот пример создания базовой пользовательской конфигурации:

Configuration configuration =
        new Configuration(messageTemplateProperties.getFreemarkerVersion());
configuration.setDefaultEncoding("UTF-8");
configuration.setDateFormat("yyyy, MM/dd"); (1)

List<String> messages = messageTemplatesGenerator.generateMultiTemplate()
        .withTemplateCodes("booking-email-subject", "booking-email-body")
        .withParams(
                Map.of(
                        "booking", booking,
                        "today", new Date(),
                        "penalty", 5000
                ))
        .withConfiguration(configuration) (2)
        .generate();
1 Настраивает шаблонизатор FreeMarker с указанной версией, кодировкой и форматом даты.
2 Используйте гибкий интерфейс MessageTemplatesGenerator, чтобы применить созданную ранее конфигурацию.