Message Module API

The Message module is a general logging utility tool which you can use to log any type of activity on a Drupal website. I’ve already written about how you can use Message module with Rules. If you’ve never used this module I would recommend that you read "Log Site Activity with Message and Rules" first, so you can get a good introduction on how to use Message module.

In this article we’ll look at creating messages programmatically via Entity’s entity_metadata_wrapper() function. Finally we’ll look at how to load and display a message log. This is useful if you need to manually add a message to a template file.

The Message module ships with a message_example module. Enable this module to see the code below in action.

Create Message Logs

If you want to follow along, go to Structure -> "Message types" (admin/structure/messages) and create a message type with the values detailed in Table 1-1.

Table 1-1. Creating a message type

Message type Value
Description Node log
Message text !action by @name.
Replacement tokens !action, @name

Now let's jump into some code. To create a message log simply run:

$values = array(
  'arguments' => array(
    '!action' => ‘Content updated’, 
    '@name' => ‘John’),
);
$message = message_create('ww_node_log', $values);
$wrapper = entity_metadata_wrapper('message', $message);
$wrapper->save();

When we created the message log, we added !action by @name. into the message text. These replacement tokens would then be replaced by "Content updated by John.".

In the arguments array within the $values variable, all you need to do is define what the token should be replaced with. The $message variable is used to create the message object. All we need to pass the message_create function is message type and the $values variable defining the arguments. The $wrapper will be used to load entity_metadata_wrapper function from Entity API module and finally we just save the message with $wrapper->save().

If you have attached a field to the message type, just set the field value by using entity_metadata_wrapper’s set method. 

For example:

$wrapper = entity_metadata_wrapper('message', $message);
$wrapper->field_published->set($node->status);
$wrapper->save();

View Message Logs

In the last section we looked at creating a message log, now let’s look at loading and displaying a message. Most of the time you’ll use Views to display or list messages, however, it’s still good to know how to do all of this via code.

$message = message_load(5);
$message->getText();

In the above code example, all we have done is load a message with the message ID of 5 and display the message text via getText() method, that's the simplest example.

If you've attached a field to the message type, then you'll have to pass the $message variable via the entity_metadata_wrapper function.

For example:

$message = message_load(5);
$message->getText();
$wrapper = entity_metadata_wrapper('message', $message);
$wrapper->field_published->value();

$wrapper->field_published->value(); will display the value for the field_published field attached to the message log.

I hope you've learned something new today about the Message module. If you have any question please leave a comment below.

 

Ivan Zugec

About Ivan Zugec

Ivan is the founder of Web Wash and spends most of his time consulting and writing about Drupal. He's been working with Drupal for 10 years and has successfully completed several large Drupal projects in Australia.