Message Templates API

The primary entry point to the add-on’s API is the MessageTemplatesGenerator Spring bean. This bean provides methods for generating messages from templates and can be injected into your services or views. For example:

@Autowired
private MessageTemplatesGenerator messageTemplatesGenerator;

Generating Messages from Templates

You can generate messages from templates using the generateMessage() method. This method requires two parameters:

  1. Template Code: The unique code of the message template you want to use.

  2. Parameter Map: A Map<String, Object> containing the dynamic data to be inserted into the template.

Suppose you have a template with the code booking-confirmation that includes placeholders like {booking.title} and {booking.room}. You can generate a message like this:

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);

Using Template Generators

To simplify the process of generating messages and reusing templates or parameters, the add-on provides three specialized generators. These generators allow you to create messages dynamically by combining templates with parameter maps. Below is a detailed explanation of each generator and how to use them.

SingleTemplateGenerator

SingleTemplateGenerator is used to create a message based on a single template and a single map of parameters. This is ideal for scenarios where you need to generate one message using a specific template and a fixed set of data.

Example usage:

messageTemplatesGenerator.generateSingleTemplate()
             .withTemplateCode("my-template") (1)
             .addParam("username", "admin") (2)
             .addParam("firstName", "John")
             .addParam("lastName", "Doe")
             .generate(); (3)
1 Specify the template code
2 Add parameters
3 Generate the message

Key features:

  • Single Template: Uses one template for message generation.

  • Single Parameter Map: Applies one map of parameters to the template.

  • Output: Returns a single message with the template filled with the provided parameters.

MultiTemplateGenerator

MultiTemplateGenerator is used to create messages based on multiple templates and a single map of parameters. This is useful when you need to generate multiple messages using different templates but the same set of data.

Example usage:

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 Specify multiple template codes
2 Add parameters
3 Generate the messages

Key features:

  • Multiple Templates: Uses multiple templates for message generation.

  • Single Parameter Map: Applies the same map of parameters to all templates.

  • Output: Returns a list of messages, each generated from a different template but using the same parameters.

It’s not necessary for all templates to use every parameter provided. A perfectly valid scenario is where the parameter map contains parameters specific to one template, parameters specific to another, and potentially some parameters shared between them.

Each template will only extract and utilize the parameters that it actually needs. Any unused parameters in the provided map will simply be ignored by a particular template. This allows you to efficiently generate messages from multiple templates with varying parameter requirements using a single call.

If a template contains a parameter that is not found in the provided parameter map, message generation will fail. However, this behavior can be modified by pre-configuring the FreeMarker configuration to handle missing parameters without throwing an exception.

MultiParamTemplateGenerator

MultiParamTemplateGenerator is used to create messages based on a single template and multiple maps of parameters. This is ideal for scenarios where you need to generate multiple messages using the same template but with different data sets.

Example usage:

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 Specify the template code
2 Add the first set of parameters
3 Add the second set of parameters
4 Generate the messages

Key features:

  • Single Template: Uses one template for message generation.

  • Multiple Parameter Maps: Applies different maps of parameters to the same template.

  • Output: Returns a list of messages, each generated from the same template but using different parameters.

Using Freemarker Configuration

The Message Templates add-on allows for customizable message generation. To further refine this process, you can create and apply custom FreeMarker configurations. This enables you to tailor how FreeMarker processes your templates. Here’s an example of how to create a basic custom configuration:

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 Configures the FreeMarker template engine with the specified version, encoding, and date format.
2 Use the MessageTemplatesGenerator's fluent interface to apply the configuration we created earlier.