This article is an answer to the questions on the drupal.org issue queue to provide documentation on how to install and use heartbeat. This post covers:
- Introduction to the module
- Heartbeat pages you should become familiar with
Installation and introduction
Installation in this case starts of course with downloading the module from drupal projects and enabling it. At this time, heartbeat message templates are imported and an administration link teases you to go there.
Logging site activity is most of the time a relation of users and content. In a lot of cases this is an acting user that creates, updates or replies to certain contextual topics. In some cases the actor has relations with other users, such as a friend relation, member of your group or being flagged by a user.
Heartbeat is an API that allows logging activity messages to the database. These logged messages are listed up to form a heartbeat stream. There are three built-in streams but developers can register their own. How these messages are getting logged, is fully up to you. Programmers can call the api function for events based on custom criteria. Non-developers and themers can enable the submodule heartbeat_rules so they can trigger events for heartbeat to log the activity. The powerfull module it depends on is rules.
Digging a little deeper
The heartbeat stream is nothing more than a query to the heartbeat_activity table. I call it AccessTypes because the queries mostly sets the userscope. Each fetched activity message is linked to a heartbeat message template. This template is configurable a lot. The streams that contain the messages are configurable as well. Beneath is a short example that shows the settings on a template for merged messages, one of the nice features in heartbeat.
Stalski, Zuuperman and Jovan are now friends
Stalski and Zuuperman have replied on “what’s going on in drupal lately”
Who’s allowed to see activity?
There are a lot of reasons why one user can see a message and others don’t. Is this user allowed to see this message type? Does he have the correct role?
These are message configurations which restrict the messages from being displayed in a global manner. But sometimes we want to restrict a message for a user, just because he is not in that group or he is not a friend. These are settings that fit for streams. Here it’s mostly the query that filters the result. After this some logic filtering is performed on the result as well as giving the possibility to hook into the process (hook_heartbeat_messages_alter).
- a message is public for all users. There is no limitation on that specific type of message.
- a message is restricted to friends of the user that performed the activity. This depends on the contrib you used for the friend behaviour (Friendlist, user relationships, …). One thing is for sure, heartbeat has to know a users relations by implementations of hook_heartbeat_related_uids_info.
- when users performed an operation on a node in a group, then the corresponding message is only shown to the users that are member of that same group. Such a restriction is a restriction on the message itself, overruled when a relation exists that links the two users directly (E.g. friends). In this case this is specific for the contrib organic groups.
It has to be said that the only reason why i wrote this module is because i needed it fast for a project at work. Why not using activity module? Only because i wanted merged messages as in facebook and activity did not support that at that time, don’t know if it’s built in now.
And most important, the rules module is ideal as linkage between drupal core, heartbeat and other contribs.
All this to explain that rules is of great importance and that you should at least read the project page and documentation . Basically rules allows us to define conditionally executed actions based on occurring events. In other words when an event occurs and all conditions are met, then the actions are invoked.
Rules is great and makes it possible to have a very nice event based system to log activity, based on events described in contributed modules. Heartbeat only provides a couple of actions. An action can hold several parameters needed to execute the actions. In the case of heartbeat, when an action “log activity” gets called, messages are logged to the database, together with a section of replacement holders(variables) that are assigned to tokens, used in the messages. When viewing the logged messages the variables can be used to merge related messages together (E.g. create a summary of users reacting on the same node).
You could as even make your own actions to log to the heartbeat db tables. And at last, you can use an api function of heartbeat to log to the heartbeat activity table. This way you could use heartbeat without the rules module.
Which pages will you be using?
- admin/build/heartbeat Manage your heartbeat messages
- admin/build/heartbeat/settings Configure heartbeat settings
- admin/build/heartbeat/streams Manage heartbeat streams
- heartbeat/privateheartbeat Page where you can see all messages public to all
- heartbeat/publicheartbeat Page where you can see all messages public to all
- heartbeat/connectedheartbeat The page where you can see a facebook alike view of merged messages with the activity of users related to you in some way.
- admin/rules/trigger Manage rules and actions (that will have a linkage to a heartbeat message)
After reading this introduction, you are ready to use the blocks and pages, provided in the module. But that’s not challenge of course, to take it further and more custom like you want, more work is to be done.
In the next posts, i will explain on how to create a heartbeat message yourself and howto create a rule with a executable and customized heartbeat action.
I would certainly recommend the build in blocks and pages as heartbeat is mostly a display module.
But if you need to use views, here is a small guide for it: creating a custom activity view.