Token_Logic Helps Messaging and Notifications


3 min read

The Token module is implemented in many different Drupal contrib modules, where it provides simple run-time text replacement for predetermined messages. What this means is that an administrator or user can write something like this:

Hello [username]. Welcome!

The brackets will then be automatically filled in with the current user’s username. The Messaging and Notifications modules, maintained by Jose Reyero, use this functionality extensively when sending out messages. The site administrator configures a few generalized templates, which are then filled in correctly at run-time by Token for every message that is sent out:

[author-name] just posted [title].

However, this does have its limits — the biggest being that the text must be static. Notifications accepts different message templates for updates, creations, node events, etc., but this has limits in terms of implementation and usability. It just isn’t practical to provide templates for every different permutation of node type, event type, and any other tokenized information that administrators can dream up.

But there are some obvious use cases. One of the most frequently requested features for Messaging and Notifications has been the ability to send out different message templates based on the content type of the node in question. An example of this is sending a notification like “[author-name] has just blogged about [title]” when a new blog post has been published, and a notification like “A new [type-name] has been posted” when anything else is published. Previously, the way to accomplish this was to code a custom token that read in the values and conditionally returned hardcoded text. This process was time-consuming and difficult to maintain at best, and at worst not even feasible, depending on an administrator’s module-coding prowess.

Now with the new optional token_logic module, this functionality has been implemented — with no module coding required! Token logic adds five new tokens that can be input in the same manner as any preexisting tokens. These tokens allow for the basic branching in tokenized messaging based on the available token values. So, rather than being limited to just node type filtering, token_logic’s tokens can be used to filter notifications based on anything from author name to term id to recipient name. Here’s how this would look for the blog post use case:

[if][type][equals]blog[then][author-name] just blogged[endif]
[if][type][notequals]blog[then]A new [type-name] has been posted[endif]

Additionally tokenlogic supports nesting within the body of the branches, the implementation is flexible and self-contained, and it’s by no means limited to Messaging. Any modules that use tokens and want to use tokenlogic just have to add in one conditional function call before returning the fully replaced text. If you find it useful in notifications, recommend or submit a patch to the maintainers of the other modules where you’d like to see this functionality. The requisite patch is very simple — preexisting token code would look like:

return token_replace_multiple($text, $objects);

The modified code to support token_logic as well without any dependency would look like:

if (module_exists('token_logic')) {
    return token_logic_replace_multiple($text, $objects);
  } else {
    return token_replace_multiple($text, $objects);

The token module may be in line for some major changes in the near future, as well as possible integration into Drupal 7 core. There are ways of doing this that would provide more flexibility to implementing modules, allowing token_logic to interface directly through tokens without requiring any modifications to other modules to make use of it. Stay tuned!

What we're doing.