Radioactivity
A Drupal module that provides field types for tracking content popularity through energy levels that increase on page views and decrease over time using configurable decay profiles.
radioactivity
Install
composer require 'drupal/radioactivity:^4.1'
composer require 'drupal/radioactivity:^4.0'
Overview
The Radioactivity module enables site builders to measure and track the popularity of their content through an innovative energy-based system. When content is viewed, energy is "emitted" and added to the content's radioactivity field. Over time, this energy can decay according to configurable profiles, allowing for dynamic popularity rankings that reflect both historical views and recent interest.
The module provides two field types: the recommended "Radioactivity Reference" field (which stores energy in a separate entity for better editorial workflow) and the legacy "Radioactivity" field (deprecated, stores energy directly on the entity). Combined with Views module, site builders can create lists of popular content, trending articles, or most-viewed items with automatic decay of older content.
Key capabilities include three energy profiles (Count for simple view counting, Linear for time-based decay, and Decay for half-life exponential decay), configurable granularity for cron processing, cutoff thresholds to limit processing overhead, and full Views integration for creating popularity-based listings. The module also supports multilingual sites through the reference field type.
Features
- Radioactivity Reference field type that stores energy values in separate entities, preventing editorial conflicts during cron updates
- Legacy Radioactivity field type (deprecated) that stores energy directly on content entities
- Three energy profile options: Count (only increases), Linear (decreases by 1/second), and Decay (50% decrease per half-life)
- Configurable granularity to control how often decay calculations are processed during cron
- Half-life time setting for exponential decay profile to fine-tune popularity decay rates
- Cutoff threshold to automatically zero-out low energy values and reduce processing overhead
- Default energy setting to give new content an initial popularity boost
- Emitter formatter that adds energy when content is displayed and optionally shows the current energy value
- Value formatter that displays only the current energy level without emitting additional energy
- Views integration through entity relationships for creating popularity-sorted content lists
- Multilingual support for the Radioactivity Reference field with per-language or shared popularity tracking
- Rules module integration with 'Energy is below cutoff' event for automated workflows
- Flexible storage options: database (default) or file-based REST storage for high-traffic sites
- Drush command for fixing empty reference fields on existing content
- Queue-based processing to prevent memory issues when handling large numbers of entities
Use Cases
Popular Articles Block
Create a block showing the 10 most popular articles on your site. Add a Radioactivity Reference field to your Article content type with decay profile. Configure the Emitter formatter on Full content view mode. Create a View of Articles with a relationship to the radioactivity field, sorted by Energy descending, limited to 10 items. Place the view as a block in your sidebar. Articles that receive more views will have higher energy and appear at the top, while older articles will decay and drop off the list.
Trending Topics Section
Build a trending topics feature that highlights content gaining recent attention. Use the Decay profile with a short half-life (e.g., 12 hours) so content must continually receive views to stay 'hot'. Set a higher cutoff value to filter out content with minimal engagement. The result is a dynamic list that responds quickly to current user interest.
Simple View Counter
Track total page views for content without any decay. Use the Count profile which only increases energy and never decreases. This provides a simple cumulative view counter. Display the energy value using the Value formatter to show total views to users.
Editorial Dashboard
Create a backend view for editors showing content popularity. Use the Value formatter (not Emitter) so viewing the dashboard doesn't artificially inflate popularity scores. Combine with other filters (content type, publication date, author) to help editors understand content performance.
Multilingual Popularity Tracking
Track popularity separately for each language version of content. Enable field translation on the Radioactivity Reference field. Each language translation will have its own radioactivity entity with independent energy values. This allows accurate popularity tracking for multilingual sites where content popularity may vary by language.
Tips
- Start with conservative settings: high half-life (1 week), low cutoff (0.1), moderate granularity (15 minutes). Adjust based on observed behavior.
- Use different energy emission values for different view modes to weight interactions differently (e.g., full page view: 10, teaser: 1).
- Monitor the radioactivity_incident table size. If it grows too large between cron runs, run cron more frequently or use REST storage.
- For high-traffic sites, consider the REST storage option to move incident collection out of the main database.
- Always use the Radioactivity Reference field for new implementations - the legacy field is deprecated and will be removed.
- Set the default energy value to give new content a 'boost' in popularity listings before it has accumulated views.
Technical Details
Hooks 5
hook_cron
Processes radioactivity decay and emission incidents during cron runs. Decay is processed based on granularity settings, while incidents are processed on every cron run.
hook_entity_load
Initializes radioactivity field values when entities are loaded, ensuring energy values are available for display.
hook_entity_presave
Handles radioactivity-related logic during entity save, including timestamp updates and preventing unnecessary revisions during radioactivity updates.
hook_page_attachments_alter
Injects the radioactivity endpoint URL into drupalSettings for the JavaScript trigger library.
hook_queue_info_alter
Ensures radioactivity queue workers are processed in the correct order (incidents before decay).
Drush Commands 1
drush radioactivity:fix-references
Fixes empty radioactivity reference fields by creating radioactivity entities and updating the references. Essential when adding a radioactivity reference field to a content type that already has existing content.
Troubleshooting 5
1) Verify the Emitter formatter is configured on the display mode being viewed. 2) Check browser network tab for POST requests to /radioactivity/emit. 3) Verify 'access content' permission is granted. 4) Run cron to process pending incidents. 5) Check drupal logs for errors.
1) Verify the field uses Linear or Decay profile (Count profile never decreases). 2) Ensure cron is running regularly (at least once per granularity period). 3) Check if the granularity threshold has been reached since last cron. 4) Set granularity to 1 for testing to process decay on every cron run.
Run 'drush radioactivity:fix-references' to create radioactivity entities for existing content. This is required when adding the field to content types with existing data.
Run 'drush radioactivity:fix-references' to create the missing radioactivity entities. This error indicates reference fields exist without corresponding radioactivity entities.
1) Increase granularity to reduce decay calculation frequency. 2) Increase cutoff value to reduce the number of entities processed. 3) Consider using REST storage for incident collection to reduce database writes during high traffic.
Security Notes 3
- Emission data is validated using a hash generated from the site's hash salt to prevent forged popularity increases.
- The /radioactivity/emit endpoint requires 'access content' permission, preventing anonymous emission if that permission is not granted.
- REST storage endpoints should be protected appropriately if exposed externally.