Radioactivity 2: basics
With Radioactivity 2 nearly out of its beta form, I thought I'd write a bit about what it is and what you can do with it and most importantly walk you through on how to use it.
Radioactivity 2 allows you to track any fieldable entities; users, nodes, commerce products, etc. It can be used as a simple view counter but also as a popularity or activity meter, e.g. with it you can create a 'most viewed nodes at this moment' list. There is also limited rules which allows you to create an activity meter for basically whatever you want.
After that we need to create three things:
- Decay profile
- Radioactivity field
Before we dwell deeper lets go through some of the terminology and settings.
- Energy: the hotness/popularity/views/etc. of the field.
- Incident: an event where a value is added to or subtracted from energy.
- Decay profile: defines whether or not the energy decays and has settings for it.
- Granularity: how often is the field energy updated - in essence this defines the resolution in which the ordering happens. You can easily visualize this with the graph.
- Half life: how long does it takes for energy to half.
- Cut off: at which point is the energy considered non-existent.
- Incident storage: where are the incidents stored and how they are processed.
There are two very important parts on the Radioactivity settings page:
Salt for checksums and the Configuration (assist). To prevent 3rd parties from manipulating the field energies with scripts/bots, you should choose a good random string (a salt) used in calculating the checksums for the ajax callbacks.
The second important part is to set up the radioactivity configuration file: radioactivity-boostrap.cfg.inc. This file holds all the required settings for the callback script to work without drupal and this is important for high traffic sites; If the file is missing the callback script does a partial drupal bootstrap so that it can function properly. Note that Live and Deferred storage types require drupal to bootstrap while the experimental File storage does not (non-boostrap memcache support is under development).
All that boils down to this: A user navigates to a node, node has a radioactivity field which - when visible - generates an incident with an ajax callback which increments the fields energy. The energy is manipulated with the settings defined in the decay profile (granularity, half-life) over time (cron runs) and it is considered to be zero when energy level is below the cut off level.
Lets get started.
We will create a setup which tracks article popularity in a 6 hour timeframe so that the articles without views for 6 hours will have half of the initial energy and that it takes 50 views for them to reach the same energy level as a brand new one with 1000 energy.
1. Decay Profile
Navigate to the Radioactivity decay profiles page under Structure (admin/structure/radioactivity). Notice that there are no decay profiles yet, so lets create a decay profile by clicking the Add link at the top.
You are presented with the following form:
The form is filled with default values that should be suitable for most use cases with a good number of daily visitors. For this example we will use the defaults which is a 6 hour half life with 1 minute granularity. Note that finding the correct values for your site may take a few weeks and it usually requires some grooming.
At the moment there are three working storage types available:
- Live storage - this updates the energy directly to the field, which means that all incidents affect the ordering in real time. Requires bootstrap.
- Deferred storage - incidents are stored to a separate table and cron is responsible for adding the incidents to the field. Requires bootstrap.
- File storage - this is an experimental lightweight incident storage which stores incidents to a temporary file. Non-bootstrap.
- Memcached storage is going to be released soon.
Lets choose the live storage for this profile.
We're done here so save the profile.
2. Radioactivity Field
Next navigate to Content types under Structure (admin/structure/types) and click on manage fields on the Article content type we wish to add Radioactivity to. Create a new Radioactivity field. Once you have clicked save you are taken to the Field settings tab (which is empty). Click on the Edit tab. On this page select the profile we just created (since there is only one profile it is automatically selected) and add a reasonable default value for the energy field; 1000 points should be sufficient if one incident emits 10 points of energy.
Next, go back to the Content types page and click on the manage display link. Here we can configure the way the field works.
We can choose the amount of energy of one view emits or disable it by setting it to 0. We also have an option to display the amount of energy the field holds as a raw value or percentage. Usually this is only needed on admin listing pages, so lets decide not to show anything (Note: at the moment due to field caching these are not updated live; cache clear or a cron run solves the problem).
The final piece missing is a view which is ordered by the field we just created.
Go to the Views listing page under Structure (admin/structure/views) and click on Add a new view. We will be listing Content of type Article with no default sorting on a page so choose some title and path for it also. The settings here do not really matter as we are only interested in the sorting order. Click on Continue and edit.
At the bottom left click on the add button to add a new sort criteria. On the following form we have to locate our field and add the field energy as the sorting criteria. Be sure to set the sorting to descending - otherwise you have the most popular articles at the bottom. Click on save and we're done!
After creating articles and viewing them - and of course running cron - the ordering on the listing page we just created should be that of the articles popularity in the wanted time frame defined in the decay profile.
That is the most basic use case for Radioactivity both for historical and technical reasons.