Sitewide Alert
Provides ability to display alert messages at the top of all pages without requiring block configuration.
sitewide_alert
Install
composer require 'drupal/sitewide_alert:^3.0'
composer require 'drupal/sitewide_alert:^2.2'
Overview
Sitewide Alert is a comprehensive module that enables site administrators to display prominent alert messages across all pages of a Drupal site. Unlike block-based solutions, alerts are automatically rendered at the top of every page regardless of theme configuration.
The module provides a custom content entity type with full revision control, translation support, and fieldability. Alerts can be scheduled to appear during specific time windows, dismissed by visitors (with localStorage persistence), and filtered by page path patterns. Multiple alerts can be displayed simultaneously with configurable ordering.
For performance optimization, the module offers both client-side (JavaScript AJAX) and server-side rendering modes. The client-side approach is cache-friendly and default, while server-side rendering is available when JavaScript is not desired. The module includes configurable automatic refresh to show new alerts without page reload.
Features
- Automatic rendering at page top without block configuration required
- Multiple simultaneous alerts with ascending/descending display order
- Configurable visual styles (colors/appearance) via admin settings
- Optional visitor dismissal with per-browser localStorage persistence
- Path-based visibility restrictions with wildcard support
- Scheduled alerts with start and end datetime ranges
- Server-side or client-side (AJAX) rendering options
- Full multilingual support with translation capabilities
- Revision control for content versioning and rollback
- Fieldable entity allowing custom field additions
- Automatic refresh polling for real-time alert updates
- Drush commands for CLI-based alert management
- Domain module integration via submodule for multi-site setups
- Block placement option via submodule for theme control
Use Cases
Planned Maintenance Notification
Schedule an alert to appear 24 hours before planned maintenance. Set the start date to when you want visitors to see the notice, and end date to when maintenance begins. Use a distinctive style like 'warning' to catch attention. The alert automatically appears and disappears without manual intervention.
Flash Sale Announcement
Create a time-limited alert for promotional events. Enable scheduling with precise start/end times. Make it dismissible so returning visitors aren't repeatedly bothered. Use the dismiss reset feature if you need to re-show the alert after updating content.
Emergency Site Notice
Quickly create an unscheduled alert using Drush from the command line: drush sitewide-alert:create 'Emergency' 'We are experiencing issues. Thank you for patience.' --style=danger. Disable when resolved with drush sitewide-alert:disable.
Page-Specific Information
Show alerts only on certain pages using path patterns. For example, show shipping delay notices only on /cart and /checkout/* pages, or show department-specific announcements on /department/sales/* paths.
Multi-Domain Announcements
With the domain submodule, create alerts that only appear on specific domains in a multi-site setup. Useful for domain-specific sales, regional announcements, or brand-specific messaging.
High-Traffic Site Optimization
For sites with aggressive page caching, keep server_side_render disabled (default). Alerts load via JavaScript AJAX call which doesn't interfere with full-page caching. Adjust cache_max_age based on how quickly alert changes need to propagate.
Tips
- Use the automatic refresh feature for time-sensitive alerts - visitors will see updates without page reload
- For scheduled alerts, set end time slightly before actual maintenance to give visitors time to complete actions
- Create multiple alert styles (e.g., info|Information, warning|Warning, danger|Urgent) to visually distinguish alert severity
- When using the block submodule, you gain full control over alert placement via block layout but lose automatic page_top positioning
- For development/staging, use Drush commands to quickly create test alerts without accessing the admin UI
- The dismissible feature uses browser localStorage - consider this for GDPR compliance as it stores the alert UUID
- Path visibility supports wildcards (*) but only at the end of paths - /blog/* works, */edit does not
- Server-side rendering improves accessibility for non-JavaScript users but may reduce caching effectiveness
Technical Details
Admin Pages 3
/admin/config/sitewide_alerts
Configure global settings for sitewide alerts including visual styles, display order, caching behavior, and rendering mode.
/admin/content/sitewide_alert
List, create, edit, and delete sitewide alert entities. Shows overview of all alerts with their status, scheduling, and visibility settings.
/admin/content/sitewide_alert/{sitewide_alert}
Edit form for creating and modifying sitewide alert content, scheduling, visibility, and dismissibility options.
Permissions 10
Hooks 4
hook_theme
Defines the sitewide_alert theme hook for rendering alert entities.
template_preprocess_sitewide_alert
Prepares variables for the sitewide-alert.html.twig template including entity data, styling, and dismissibility.
hook_theme_suggestions_sitewide_alert
Provides theme suggestions for sitewide alert templates based on style and dismissibility.
hook_page_top
Injects sitewide alert render array into page_top region. Skipped if sitewide_alert_block submodule is enabled.
Drush Commands 4
drush sitewide-alert:create
Create a new sitewide alert from the command line.
drush sitewide-alert:delete
Delete sitewide alerts matching a label.
drush sitewide-alert:disable
Disable (unpublish) sitewide alerts. Without arguments, disables all alerts.
drush sitewide-alert:enable
Enable (publish) a sitewide alert.
Troubleshooting 6
Verify the alert is set to 'Active' (published). Check if scheduling is enabled and current time is within the scheduled range. Ensure anonymous users have 'view published sitewide alert entities' permission. If using server-side rendering, clear Drupal caches.
Dismissal state is stored in browser localStorage. If users clear browser data, dismissals reset. To intentionally reset dismissals (e.g., after updating alert content), edit the alert and check 'Ignore Previous Dismissals' then save.
With client-side rendering (default), alerts refresh based on refresh_interval setting (default 15 seconds). For immediate updates, reduce cache_max_age or have users hard-refresh. With server-side rendering, clear Drupal caches.
By default, 'Show on Administration Pages' is disabled. Check the setting at /admin/config/sitewide_alerts if alerts shouldn't appear on admin pages.
Ensure no JavaScript conflicts. The module requires core/once, core/drupal, and core/drupalSettings libraries. Check browser console for specific errors. Verify the /sitewide_alert/load endpoint returns valid JSON.
Path patterns must start with /. Use * as wildcard at end only (e.g., /products/*). For language-prefixed paths, include the prefix or use wildcards. The 'Negate' option inverts the logic (show everywhere except listed pages).
Security Notes 4
- The 'administer sitewide alert' and 'administer sitewide alert entities' permissions should only be granted to trusted administrators as they provide full control over site-wide messaging
- Alert message content supports HTML - ensure only trusted users can create/edit alerts to prevent XSS
- The AJAX endpoint /sitewide_alert/load respects the 'view published sitewide alert entities' permission
- Dismissal data stored in localStorage contains only alert UUIDs and timestamps, no sensitive information