random_content_block

This Drupal module provides a configurable block that displays a random item from a selected content type. It is designed to be flexible, performant, and standards-compliant.

FEATURES

Content Selection: Choose any Content Type (Bundle) to source items from.
Field Selection: Select specifically which fields to display (e.g., Title, Body, Image).
Randomization: Fetches random published items.
AJAX Loading: Uses a "Signed Configuration" AJAX pattern to bypass Drupal's Internal Page Cache, allowing the block to refresh even on fully cached pages.
Caching Options:
- No Cache: Random item on every request.
- Time-based (TTL): Cache the random selection for a specific duration (e.g., "Scripture of the Day").
- Uses Drupal's Cache API to ensure high performance for the AJAX endpoint.
Item Count: Configure how many random items to show.

REQUIREMENTS

Drupal 10.x or 11.x

INSTALLATION

Install as you would normally install a contributed Drupal module. Visit: https://www.drupal.org/node/1897420 for further information.

CONFIGURATION

Go to Structure > Block layout.
Click Place block in the desired region.
Search for Random Content Block.
Configure the settings:
- Content Type: Select the source content type. The form will refresh to show available fields.
- Fields to Display: Check the fields you want to appear in the block.
- Item Count: Number of items to display.
- Cache Duration (seconds): Enter how long the random choice should stick in seconds. 0 means no cache.
Click Save block.

Support development on this module

A lot of hard work and dedication has gone into developing this module. If you find it helpful and would like to support ongoing development, consider buying me a coffee! Your support helps ensure that I can continue enhancing and maintaining this module for everyone. Thank you for your generosity!

Architecture

This module implements the Signed Configuration AJAX Pattern to solve the "Page Cache Paradox" (where static page caching prevents dynamic blocks from updating for anonymous users).

Block (RandomContentBlock): Renders a secure placeholder. It generates a set of configuration parameters signed with a cryptographic HMAC to prevent tampering.
Controller (RandomContentController): A stateless endpoint that validates the cryptographic signature and renders the content fragment.
Service (RandomContentFetcher): Handles the logic of querying content types, fields, and random nodes.
JavaScript (random-content-block.js): A lightweight loader that fetches the signed URL and injects the content into the placeholder.

Testing

This module includes Kernel and Functional tests.

To run the tests:

phpunit modules/custom/random_content_block

Troubleshooting: Caching Issues

Standard Drupal blocks often suffer from the Internal Page Cache limitation, where the max-age of a block is ignored and the entire page is cached permanently for anonymous users.

Drupal core's Internal Page Cache module ignores max-age bubbled metadata. To ensure the Cache-Control header correctly reflects the configured "Cache Duration" even when the Internal Page Cache is active, it is recommended to install the page_cache_max_age_bubbling module.

Random Content Block uses AJAX to retrieve the block content because it seems that blocks in regions outside of the main content have a different bubbling strategy and won't bubble to the top even when using the above module. By retrieving with AJAX, the request is handled in isolation and gets the proper max-age and expires time.

Advanced Caching

If you are using external caches (Varnish, Cloudflare, etc.), ensure they are configured to respect the Cache-Control: max-age header returned by the AJAX endpoint (/random-content-block/render).