Guideline for heartbeat activity
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:
- Installation
- 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).
Examples:
- 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.
Administration
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.
January 31st, 2010 at 7:24 am
Hi menhir, I tried Activity2 the last days but now I might switch to your Heartbeat module since I saw the demo-site you run. It looks very promising and more like what I need to have (a Facebook-like stream). What I would like to ask you: On your demo-site, you have configured and themed it very like Facebook. Since that is exactly what I need for my site I would like to ask if this configuration and theme is included with the module or if you could provide it otherwise? Thank you!
February 3rd, 2010 at 10:01 pm
I will provide the custom modules that tweak the heartbeat (override and rethemed) . For the moment, you can see the stream configuration next the heartbeat activity stream pages. You can find them under the “activity streams” menu item.
Because i am still working on it, the complete heartbeat_implementation module is not downloadable yet. This will not be included in the project.
In short: the demosite is build with heartbeat with the submodule heartbeat_example enabled. This module provides all hook implementations available to let you know what you can do with it. I have a second module that is called heartbeat_implementations where i do very site specific things, as you can see. So basically the example module already shows what you can achieve but you could wait untill the implementations module is downloadable.
February 4th, 2010 at 11:19 pm
Is there a more detailed tutorial on how to set up this module and configure it? I have installed it and can not get anything to work. The shouts don’t appear. The default blocks don’t display anything. I am not a programmer but I have been working with drupal for about eight months or so and I have done some mild editing, themeing, and coding.
February 4th, 2010 at 11:27 pm
Well i am planning a screencast. I hope this will be available soon.
February 4th, 2010 at 11:46 pm
Is there something in particular that I might be doing wrong? (or not doing at all). Does heartbeat depend on rules? I just thought the default blocks would work upon installation. If there is more set up involved please let me know. I absolutely love the look of this module and would like to be able to use it.
February 5th, 2010 at 12:34 am
I have no idea actually. hrules module (submodule) uses rules and you may need to configure the default heartbeat rules.
Have you configured the stream and did not deny the messages?
Is there something logged what so ever in heartbeat_activity table?
My guess is that nothing is logged because no rules are triggered. Or you call the api function to log, or you use rules, but something has to be logged ofcourse.
Why the shouts block is not appearing, i don’t have a clue. i cannot reproduce the problem. Does the permission “make shout” is set ok?
Try it out and create an issue on drupal.org . It will be much easier to follow it there.
February 5th, 2010 at 3:38 pm
Gotcha. No worries. I did get the shouts working. I haven’t had much time to play around with the rest but I will. I think it’s a matter of saving the configuration of the rules. Even though they are automatically created, it seems they need to be saved once before taking effect. (at least that seems to be the issue). I’ll continue to play with the rules and settings when I have some more time. Thanks for a great module. I think it’s perfect for the site I’m building.
February 9th, 2010 at 7:33 am
Thank you for answering my question. However, I have to say that I am confused now.
I really don’t know what the heartbeat_example and heartbeat_implementation modules are which you are talking about in your reply to my initial comment. 
However, as far as I understand you, you are still doing some work on the module which will be released soon. So for the moment, it would already help me a lot if you could tell me if the current version (the version which is available for download on drupal.org) is capable of implementing a Facebook-like stream like you did here on your website. If so, I would even more appreciate if you could provide some hints how to tune it that way (e.g. if using the version from drupal.org there has to be much customization to be done, where to start, etc.)
Thank you very much!
February 9th, 2010 at 12:21 pm
First of all. Have you visited the demo site at heartbeat.menhireffect.be. I am talking about the features exposed there. Look closely to everything installed and explained! heartbeat implementations module is downloadable there to show some nice stuff.
Heartbeat_example module is a show-off module that comes within the heartbeat module install!
I am doing work on the module, but it is released and stable as you can see at drupal.org
In short: The facebook alike streams is very much possible with current stable release as i did it. The custom modules and rules export i have put in the downloads section at the heartbeat demo site!
February 10th, 2010 at 5:51 pm
Yes, I visited the demo site as mentioned earlier and I am impressed of what the module does there - that’s why I am asking here if and how the current version is capable of what you are doing on the demo site. However, it is still somewhat confusing: There are 2 module versions on drupal.org for download, then there is the download section here with 2 additional downloads. I do not know what to install and how to install it and there is no documentation provided (neither on Drupal.org nor here; all the text-files here are dummy files named “test” or whatever). Or do I miss something?
February 10th, 2010 at 6:41 pm
Yes you don’t understand it completely.
http://drupal.org/project/heartbeat Here this is only ONE version of heartbeat!! The red one is a development release, read drupal documentation!
The modules that are downloadable at the demosite are NOT for production usage. It is a demo module!!! You can use things from it as you want.
So basically just install heartbeat and read documentation. There’s nothing more to it than that.
I have the intension that this is your first drupal setup? I never got questions like that actually …
I hope you understand i cannot help you learn drupal from scratch. Heartbeat is not the most simple module, so maybe you need to try some basic drupal stuff.
February 11th, 2010 at 12:42 pm
Yes, I am rather new to Drupal. However, I understand the difference between development release and stable release as well as I know how to install a Drupal module and configure it. What I wanted to know is:
- Use the development release or the stable release?
- How to use the example module? It does not seem to be a normal Drupal module which you can install through the administration backend.
- Where exactly can I find the documentation? The text-files on the demo site are empty.
February 11th, 2010 at 12:52 pm
This is the documentation page: http://heartbeat.menhireffect.be/page/documentation All links in the sidebar (titled “Guideline”) as well in the main body are empty or lead to empty pages or 404s.
February 11th, 2010 at 2:33 pm
yes, documentation says: “The best way to find documentation for what you need on this site, is to try it out. Most of the time you will be lead over to sections that show a use case like yours. ” So look on the right or left of a heartbeat stream! it will explain everything.
“It does not seem to be a normal Drupal module which you can install through the administration backend”
The example module is a normal module, it’s installed at the demosite. I really don’t know what you are talking about. Even worse , i told you this is not to enable! it is a cheatmodule to show you what you can do.
the choice of stable or dev is your choice, i would always recommend stables of course.
“Where exactly can I find the documentation”
The documentation pages are indeed not yet completed but you can find info here as well. So read all stuff at the project page and this blog.
I don’t think i can help you any more than this.