Grout Image Placeholder

Introduction

Grout Image integrates with the Grout on-demand image API to provide automatic fallback images whenever media fields are empty. It is designed for sites that perform bulk content imports (movies, books, people) where posters, covers, or headshots may not always be available.

The module provides:

• A URL generator service (grout_image.url_generator) that builds Grout avatar and placeholder URLs from configurable defaults.
• Twig filter grout_avatar and function grout_placeholder for use directly in templates.
• A field formatter "Grout Fallback" for entity_reference fields that target media entities: shows the real image when present, and a Grout-generated image when the field is empty. The fallback is sized to match the output dimensions of the selected Drupal image style so the layout does not shift.
• A settings page at Configuration > Media > Grout Image for site-wide defaults (base URL, colours, size, format).

Grout API endpoints used

Type URL pattern Avatar https://grout.in/avatar/{name}.{format}?size=128&background= random&color=f0e9e9&rounded=true&bold=false Placeholder https://grout.in/placeholder/{W}x{H}.{format}?text=John+Doe&bg=random&color=000000

No API key is required.

Requirements

• Drupal 11 or later
• The drupal:media and drupal:field core modules

Installation

Install as you would any Drupal module. See Installing Drupal Modules for details.

composer require drupal/grout_image
drush en grout_image

Configuration

1. Navigate to Configuration > Media > Grout Image (/admin/config/media/grout-image).
2. Set the Grout API base URL (default: https://grout.in; change only when using a self-hosted Grout instance).
3. Configure the site-wide default avatar size, background colour, text colour, and image format. These apply whenever no per-formatter override is set.

Field formatter

1. On a content type (or media type) that has an entity_reference field pointing to media entities, go to Manage display.
2. Set the formatter for the media reference field to Grout Fallback.
3. In the formatter settings:
   • Choose Fallback type: Avatar (initials) or Placeholder (solid colour).
   • Choose the Image style — the fallback image will be generated at the same output dimensions as that style. For crop/resize styles (e.g. Scale and Crop) the exact pixel dimensions are used; for scale-only styles the configured maximum dimension is used as a bounding box.
   • Optionally override background colour, text colour, and image format.
   • Choose the View mode used to render the real media entity when the field is populated.

Twig usage

The filter and function are available in any Twig template once the module is enabled.

{# Avatar — pass the entity label as the name #}
<img src="{{ node.label|grout_avatar({size: 200, rounded: true}) }}" alt="{{ node.label }}"> 

{# Placeholder — width × height, optional text and colours #}
<img src="{{ grout_placeholder(300, 450, {text: node.label, bg: '1a1a2e'}) }}" alt="{{ node.label }}"> 

Available options for grout_avatar:

Option Default Description size module default (128) Square size in pixels background module default Hex colour without # color module default Text colour hex without # rounded true Circular avatar bold true Bold initials format module default (png) png, jpg, or webp

Available options for grout_placeholder:

Option Default Description text — Text label drawn on the placeholder bg module default Background hex without # color module default Text colour hex without # format module default (png) png, jpg, or webp

Overriding defaults in settings.php

$config['grout_image.settings']['base_url'] = 'https://grout.example.com';
$config['grout_image.settings']['default_bg'] = '1a1a2e';
$config['grout_image.settings']['default_color'] = 'ffffff';
$config['grout_image.settings']['default_size'] = 200;
$config['grout_image.settings']['default_format'] = 'webp';

Troubleshooting

The fallback image does not appear when the field is empty. Confirm that the formatter is set to Grout Fallback on the correct view mode in Manage display and that caches have been rebuilt (drush cr).

The fallback image is a different size than the real image. Choose an image style that produces fixed output dimensions (e.g. Scale and Crop). Scale-only styles do not have deterministic output dimensions; the module uses the configured maximum dimension as an approximation.

I see a broken image icon instead of a Grout placeholder. Check that the Grout base URL is reachable from the server and that there is no firewall blocking outbound requests to grout.in.

Maintainers

Current maintainers for this project:

• credevator