Jan 12 2010
Jan 12

This page holds links to documentation about the module “heartbeat” for drupal 6. From here you will find how to install the module, how to use it and how to implement its hooks.
Heartbeat can be used with the rules module. Rules allows other modules to describe default rules events and actions, and that’s what heartbeat does. The rules as well as the messages you build are exportable into defaults. Developers can of course use an api function to log on custom criteria.
After installing, a couple of heartbeat activity messages (and default rules are activated). Add some content, change your profile or reply on some content, messages will be logged immediately. You can use the blocks and pages to view the result. With the heartbeat views submodule, you have a little more control but it is not that convenient all the time. I recommend the built-in blocks and pages.

Before you start using heartbeat

You must be aware that there are two interfaces you will be dealing with, when setting up your heartbeat. You will learn here about how to compose messages and set features to them, but you will have to learn how rules work.
You can always try it out the trial-and-error way. Suites me most of the time :-).

Heartbeat messages

Heartbeat messages are custom made messages that serve as template. When heartbeat activity gets logged, it is always linked to a heartbeat message. Depending on how you configured a message, the result messages go through a merging and grouping mechanism to (re)build the messages that seem related.
E.g. Stalski posted page1, page2 and page3.
For this to work properly as you planned, you have to think a bit about how you will group your variables. You group by user (E.g. !username) to summarize nodes (E.g. !title).

Tip: You can use html in your messages if you want to wrap something with a css class to give a link another colour for instance.

Dumb logger, smart viewer

All heartbeat does is log all we want it to, for each available language in the site. You’ ll see that you can log message activity as long as you configured a heartbeat message to link it to this activity stream (see $message_id). So what i mean with dumb logger is the fact that there are no restrictions on the logging itself. It is the display that determines what needs to be fetched and shown.
There are two ways on how to log something to the database table heartbeat_activity:
1/ use the api function

  1. /**

  2.  * API function to log a message from custom code

  3.  *

  4.  * @param string $message_id

  5.  *   Id of the message that is known in the message

  6.  * @param integer $uid

  7.  *   Actor or user performing the activity

  8.  * @param integer $uid_target [optional]

  9.  *   user id of the target user if present. Target users can be an addresse or a

  10.  *   user relation transaction with the actor $uid

  11.  * @param integer $nid [optional]

  12.  *   Node id for content (for context node)

  13.  * @param integer $nid_target [optional]

  14.  *   Node id for content that is related to other content

  15.  * @param array $variables [optional]

  16.  *   Variables can be used if you used them in the used message. Take care to use

  17.  *   the @-sign for words that are prefix with the question mark sign in the messages

  18.  * @param integer $access

  19.  *   The access to restrict the message

  20.  */

  21. function heartbeat_api_log($message_id, $uid, $uid_target = 0, $nid = 0, $nid_target = 0, $variables = array(), $access = HEARTBEAT_PUBLIC_TO_ALL) {


  23. }

2/ use a heartbeat action triggered by the rules event based system.

The screenshot shows a rules rule edit form. Choose an event, digg into the conditions and use the heartbeat user activity logger as action.
Customizing the action is basically nothing more than setting tokens to its variables. Instead of typing a message here, we choose a heartbeat message we defined earlier or that came as default. This will openup a textarea with prefilled variables from the original message. Same thing here, assign tokens to the variables, each line for another variable.
Save this and make sure the rule is active. Rules will do the rest and start logging on occurring events.

It is even possible to add your own tokens to build really nice heartbeat views. Like a gallery with image_fupload. I did this and the result will be maybe included later as image_fupload integration submodule, if there is request for it.

Heartbeat blocks

With this module come a couple of default blocks. The built sql for this depends mostly on the scope of users that performed the activity. Everyone , only your friends or only your own activity.
Here I need a little more work because this is not scalable at all. So let’s say it is on my todo list.
Another block in the heartbeat core is the flag message form. With this form, users can flag each other by chosing one of the existing flag messages to form messages like “user slaps other user in the face”. Again, build as many template flag messages you like.

Administer settings

Settings for heartbeat regulate the way things are logged and viewed.  Even a couple of template stuff.


Heartbeat has integration for some other contributes that are important because they describe user activity on a drupal site. A person that becomes friends with another or decides to subscribe to some group or channel can be logged as heartbeat message.

Heartbeat rules

This module is the module that allows you to create heartbeats with UI only.


A shout is something like twitter or facebook’s “what are you doing”. It comes with a form block you can place on your site and let people shout. The messages appear in the heartbeat messages.
Important as well is to mention that these shouts live in a separate table as well. One could decide to show the shouts in a separte way and build their views with views2.

Og activity

Organic groups is a module that has a lot of user interaction going on. At the hearbeat activity settings page, some extra settings are provided if the submodule is set to on. Organic group describes extra events and conditions that heartbeat can use and uses.

Friendlist activity

Friendlist implementation into heartbeat activity with a user-to-user interaction. By all means it is user activity. A extra default message and rule comes with this installation.


  • Messages can be grouped together when activities happen more than once in a set timespan.
  • Messages contain variable names you can choose yourself
  • It’s possible to write your own tokens to build sofisticated messages
  • You can use the message_alter hook to filter messages. (Sometimes conflicts can occur when building exactly the same messages on more than one event with the group setting on)

This entry was posted on Tuesday, January 12th, 2010 at 11:36 pm and is filed under Drupal, Heartbeat. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web