Modal
Allows creation and management of Bootstrap-based modal dialogs through the CMS without coding.
modal_page
Install
composer require 'drupal/modal_page:^5.1'
composer require 'drupal/modal_page:^5.0'
Overview
Modal Page is a comprehensive Drupal module that enables site administrators to create and manage modal dialogs (lightboxes) entirely through the CMS interface. The module provides a flexible configuration entity system for defining modals with rich customization options.
Modals can be triggered in multiple ways: automatically on page load, after a delay, when scrolling to a specific page position, or when clicking on a designated HTML element. Each modal supports role-based access control, multilingual filtering, and scheduling for automatic publish/unpublish at specified times.
The module integrates with Bootstrap 3 or 5 for modal display and includes extensive customization options for headers, footers, buttons, styles, and behavior. A "Don't show again" feature with cookie management allows users to dismiss modals permanently.
Features
- Create unlimited modals through admin UI without writing code
- Display modals on specific pages using path patterns with wildcard support
- Display modals via URL parameter (?modal=value)
- Auto-open modals on page load with optional delay in seconds
- Trigger modals based on scroll position (pixels or percentage)
- Trigger modals by clicking on custom CSS selectors (class or ID)
- Bootstrap 3 and Bootstrap 5 support with automatic loading detection
- Customizable modal sizes (small, medium, large)
- Full control over modal header: title display, horizontal line, close button (X), maximize button
- Full control over modal footer: OK button, dismiss button, "Don't show again" checkbox
- Cookie-based "Don't show again" functionality with customizable expiration time
- Show modal only once per session option
- Auto-hide modal after specified seconds
- Role-based access control to restrict modals to specific user roles
- Multilingual support: restrict modals to specific languages
- Scheduling: auto-publish and auto-unpublish modals at specified dates/times
- YouTube video embedding support in modal body
- Redirect to URL after clicking OK button
- Custom CSS classes for modal, header, footer, and all buttons
- Close modal behavior: ESC key and clicking outside configurable
- Programmatic modal creation via Entity API
- Hooks for altering modals and handling submit events
- Drush command for cron-based scheduling
- Theme template override support with suggestion patterns
Use Cases
Welcome Message for First-Time Visitors
Create a modal that appears on the homepage (<front>) with auto-open enabled. Enable "Show modal only once" so returning visitors don't see it again. Use a friendly welcome message with a link to popular content.
Cookie Consent Notice
Create a modal with the "Don't show again" option enabled. Set to appear on all pages (leave Pages field empty). Configure a short cookie expiration time (e.g., 365 days) for compliance. Add custom CSS class for styling and use the redirect link feature to link to your privacy policy.
Newsletter Subscription Popup
Create a modal with a delay of 30 seconds or triggered after scrolling 50% down the page. Include your newsletter signup form in the body using an embedded form or iframe. Enable "Show modal only once" to avoid annoying returning visitors.
Video Tutorial on Specific Pages
Use the YouTube field to embed an instructional video. Set the modal to appear on specific documentation or feature pages. Enable the maximize button so users can watch in full-screen mode.
Promotional Campaign with Scheduling
Create a promotional modal with specific publish and unpublish dates for a sale or event. Use role restriction to show only to authenticated users. Set up the redirect link to go directly to the promotion page when users click OK.
Members-Only Announcement
Create a modal restricted to specific roles (e.g., authenticated users, premium members). Use the language restriction feature for multilingual announcements. Schedule automatic publish/unpublish for time-sensitive content.
Click-Triggered Modal for Product Details
Disable auto-open and set "Open this modal clicking on this element" to a CSS class like ".product-quick-view". Add this class to product cards on your site. The modal displays detailed product information without page navigation.
Exit Intent Alternative
Create a modal triggered at 90% scroll height. This catches users who have read most of your content. Display a call-to-action or subscription offer before they leave.
Tips
- Use path wildcards strategically: /products/* matches all product pages, /blog/* matches all blog content
- For A/B testing different modal messages, create multiple modals with the same configuration but different content and restrict each to specific user roles
- Use the browser's developer tools to inspect the modal HTML and add custom CSS overrides in your theme
- Template suggestions allow per-modal templates: create modal-page--[modal-id].html.twig for custom designs
- For programmatic modal creation, use \Drupal::entityTypeManager()->getStorage('modal')->create() with setters for each property
- The modal_submit hook is ideal for tracking analytics events when users interact with modals
- Combine scroll-triggered modals with specific page paths to create contextual prompts that appear when users engage with content
Technical Details
Admin Pages 4
/admin/structure/modal
Lists all modals with operations to add, edit, and delete. Displays modal title, type, pages/parameters, and published status.
/admin/structure/modal/add
Form for creating a new modal with all configuration options organized in vertical tabs.
/admin/config/user-interface/modal-page/settings
Global configuration settings for the Modal Page module.
/admin/modal/help
Help page with module documentation and links to administration pages.
Permissions 1
Hooks 3
hook_modal_alter
Allows modules to alter any modal before it is displayed. Called for every modal that will be shown on the current page.
hook_modal_ID_alter
Allows modules to alter a specific modal by its machine name. Replace ID with the modal's machine name.
hook_modal_submit
Triggered via AJAX when a user clicks the OK button on a modal. Use this for custom actions like logging, redirects, or data processing.
Drush Commands 1
drush modal_page:cron
Run the Modal Page scheduler to process scheduled publish/unpublish operations. Use this for more frequent scheduling without running full Drupal cron.
Troubleshooting 5
Verify the modal is published, the current path matches the configured pages (check for leading slashes), and the current user has the required role if role restriction is enabled. Check browser console for JavaScript errors.
Enable "Verify and Load Bootstrap automatically" in global settings. If your theme already loads Bootstrap, ensure it's not conflicting with the module's version. Try switching between Bootstrap 3 and 5 in settings.
Check that cookies are enabled in the browser. Verify the cookie expiration is set correctly (0 means session-only). Clear browser cookies and test again. Check if "Show modal only once" conflicts with "Don't show again".
Ensure Drupal cron is running regularly. For more precise scheduling, set up a dedicated cron job using the Modal Page cron endpoint (/modal-page/cron/{cron-key}) or Drush command (drush modal_page:cron).
Check the path patterns in the modal configuration. Remember wildcards (*) must be at the end of paths. Use <front> for the homepage. Paths are case-insensitive and compared against path aliases.
Security Notes 4
- The 'administer modal page' permission is marked as restricted access - only grant to trusted administrators
- Modal body content is processed through Drupal's text format system, providing XSS protection based on the selected format
- Allowed HTML tags for modal content are configurable in global settings to balance functionality and security
- The scheduling cron endpoint requires the site's cron key for authentication