Message groups

A module may define a message group to specify which token types it expects some messages will allow. For example, suppose a commerce module defines an "Order" entity type and wants to send a message whenever the order status changes. In this situation, it expects the used messages to allow at least a token for that order. If this module also wants to allow the user to define several messages for this purpose - for different types of orders, for example - it may provide a group of messages, which defines the allowed token types and includes the "Order" token.

Defining a message group

Message groups are defined in YAML files named example.sender_message_groups.yml placed in the module's root folder, where "example" must be replaced by the module's name.

Each message group defined in the YAML has the following structure:

example_order:
  label: 'Order'
  token_types:
    - order
    - ...

The group IP ("example_order" in the example) must be unique so it should be prefixed by the module's name.

The "token_types" key defines a list of allowed token types for messages of this group. The group a message belongs to can be defined in the administrative UI or in YAML configuration file.

Showing message options

A module that allows several messages to be provided for some purpose will likely have a configuration form to select the message that should be used. The Sender module provides a form element, which shows a "select" element with message options, optionally filtered by group. To use it, add it to your configuration form like this:

$form['order_message'] = [
  '#type' => 'sender_message_select',
  '#title' => $this->t('Message for new orders'),
  '#message_group' => 'example_order',
];