Tokens

On the "Templates" page, a simple example was presented to illustrate the basic functionality. However, the Message module offers more advanced features through tokens, allowing for dynamic message generation based on contextual information. To utilize tokens within messages, the Token module and Entity Token module (part of the Entity module, a dependency of the message stack) are required.

If you've worked with tokens in Drupal previously, employing them within the Message module should feel familiar. Nonetheless, the Message module introduces a distinct token syntax. Let's examine three variations of a message text field:

Static Message

<p>Something happened</p>

Dynamic Token

Something happened. Node [message:field-node-ref:title] was created.

Here, the token [message:field-node-ref:title] will be replaced at runtime with the title of the referenced node.

Dynamic tokens allow Drupal tokens to be utilized within any message field, injecting specific content dynamically. For instance, entering [current-date:short] in the message text will display the current request time. Similarly, [message:user:mail] it will be replaced with the message author's username during display. If the message contains fields, such as field_node_ref, its contents are accessible via the token system as well (e.g., [message:field_node_ref:title]). This functionality relies on the "Entity token" module provided with Entity API. Enabling the "Token" module is also advisable, as it offers more tokens and displays a token browser on the message template creation page.

Single Use Token

Something happened. Node [message:field-node-ref:title] was created by @{message:user:name}

In this case, @{message:user:name} is also replaced at runtime. However, during the initial display, the replaced text (e.g., a user name) is stored within the message record in the database. Subsequent renditions of the message retrieve the replaced text directly from the message table, offering improved performance, especially when the token value is unlikely to change in the future.

Single-use tokens, akin to dynamic tokens, are replaced by their content as the message is created. This means the content won't update if its reference changes. For instance, @{message:user:name} will be replaced by the message author's name during message creation. This approach is useful when the referenced content, such as a user's name, is unlikely to change frequently.

Token Callback

When creating a message, custom arguments can be stored and replaced when presenting the message. For example, if a message includes an argument like @sometext, it will be inserted into the message text whenever the string @sometext is encountered during display. Additionally, this method supports custom callback functions with optional arguments stored within the message. To utilize a callback, create the message with an argument such as !replaced-by-foo:

'!replaced-by-foo' => [ 'callback' => 'foo', 'callback arguments' => ['x', 'z'] ]

In this case, the string !replaced-by-foo within the message body will be replaced by the output of calling foo('x', 'z').

Custom Tokens

Token Project

hook_tokens

hook_tokens_alter