Simple Popup Blocks
Converts any Drupal blocks, views, forms, or custom CSS elements into configurable popups with extensive display control options.
simple_popup_blocks
Install
composer require 'drupal/simple_popup_blocks:8.x-3.5'
Overview
Simple Popup Blocks is a versatile Drupal module that transforms any block content, views, forms, or custom HTML elements into fully customizable popups. The module provides a comprehensive configuration interface where administrators can define popup behavior including positioning, display frequency, trigger methods, and visual controls.
The module supports both Drupal blocks (selected from a dropdown) and custom CSS selectors (id or class) as popup sources. It offers 10 different layout positions (corners, center, and full-width/full-height bars), three trigger methods (automatic, manual click, and browser/tab close detection), and sophisticated display frequency control through either visit counts or time-based intervals.
Each popup can be individually configured with minimize and close buttons, ESC key support, overlay backgrounds, configurable delays, responsive trigger widths, and customizable dimensions. The module uses cookies to track visitor interactions and control popup display frequency. CSS selectors are automatically generated for each popup to enable custom styling.
Features
- Transform any Drupal block into a popup by selecting from available blocks
- Create popups from custom CSS selectors (id or class) for views, forms, or any HTML element
- 10 layout positions: Top Left, Top Right, Bottom Left, Bottom Right, Center, Top Center, Top Bar, Bottom Bar, Left Bar, Right Bar
- Visit count-based display control with multi-select (show on 1st visit, 2nd visit, specific visits, or every visit)
- Time-based frequency control with Hourly, Daily, or Weekly intervals
- Three trigger methods: Automatic (with optional delay), Manual (click event on specified element), Before browser/tab close (exit intent)
- Configurable minimize, close, and minimized buttons with show/hide options
- ESC key support to close popups
- Semi-transparent overlay background option
- Configurable delay before automatic popup display (in seconds)
- Responsive trigger width setting to control popup display based on viewport width
- Customizable popup width in pixels
- Cookie expiry configuration (0 for session cookies, or specified days)
- CSS selector reference table provided after popup creation for custom styling
- Automatically hides popups on admin pages
Use Cases
Newsletter Subscription Popup
Create a block containing a newsletter signup form using the Webform module. Place the block in a region at the bottom of your page. Go to Add simple popup blocks, select the block from the dropdown, choose 'Center' layout, set trigger method to 'Automatic' with a 5-second delay. Enable overlay and close button. Set visit counts to '1' to show only on the first visit. This creates a centered modal that appears once to new visitors, prompting them to subscribe.
Cookie Consent Banner
Create a custom block with your cookie policy text and accept button. Place it in a region. Create a popup selecting this block, choose 'Bottom bar' layout to span the full width at the bottom of the page. Set visit counts to '0' to show every visit (or use time frequency set to 'Weekly'). Disable overlay since it's a non-intrusive banner. Add custom CSS using the provided selectors to style the banner to match your site design.
Exit Intent Offer
Create a promotional block with a special offer or discount code. Create a popup using the 'Before browser/tab close' trigger method with 'Center' layout and overlay enabled. Set visit counts to '1,2,3' to show on the first three visits. This creates an exit-intent popup that appears when users move their mouse toward the browser's close button, potentially converting abandoning visitors.
Click-to-Open Modal
Add a custom div with id 'contact-modal' containing a contact form anywhere in your template. Create a popup with type 'Custom css id or class', enter 'contact-modal' as the selector, select 'Css id' as the css selector type. Set trigger method to 'Manual' and enter '#contact-trigger' as the trigger selector. Add a button or link with id='contact-trigger' anywhere on your page. Clicking this element will open the contact form in a centered popup.
Mobile-Only Promotion
Create a promotional block for app download or mobile-specific content. When configuring the popup, set the 'Trigger width' to '768' pixels. The popup will only appear on devices with viewport width 768px or greater. For mobile-only popups, you would need custom JavaScript to invert this logic, but you can use the provided CSS selectors to hide the popup on desktop using media queries.
Timed Announcement with Minimize
Create an announcement block for important site updates. Configure the popup with 'Top right' layout, enable minimize button, and set a delay of 10 seconds. Enable 'Show minimized button when popup is not automatically triggered' so users can re-access the announcement. Set time frequency to 'Daily' so returning visitors see it once per day. Users can minimize the popup and click the minimized indicator to read it again.
Tips
- Place popup source blocks in a region at the bottom of your page template for best results - this ensures the element is available when JavaScript runs
- Always add the recommended 'display: none' CSS rule to your theme for popup elements to prevent content flash during page load on slow connections
- Use the CSS selectors provided on the edit form to create custom popup designs matching your site's theme
- For exit-intent popups, the trigger only fires when the mouse leaves through the top 20 pixels of the viewport, mimicking intent to close the browser tab
- Combine visit counts strategically - use '1,4,7' to show on first, fourth, and seventh visits for effective remarketing without being intrusive
- Set cookie expiry to 0 for session-based popups (like cookie consent) that should appear on every new browser session
- Use the trigger width setting to hide promotional popups on mobile devices where screen space is limited
- The minimize feature is useful for announcements that users may want to reference again during their session
- When using custom CSS selectors, ensure the target element has a unique id or class to avoid conflicts with other page elements
- Test popup configurations in an incognito/private browser window to simulate a new visitor without existing cookies
Technical Details
Admin Pages 4
/admin/config/media/simple-popup-blocks/add
Create a new popup configuration by selecting a Drupal block or custom CSS selector and configuring all display options including layout, frequency, triggers, and styling controls.
/admin/config/media/simple-popup-blocks/manage
View and manage all existing popup configurations in a table format with quick access to edit and delete operations.
/admin/config/media/simple-popup-blocks/manage/{uid}
Edit an existing popup configuration. Includes all options from the add form plus the Enable/Disable status toggle and a table of CSS selectors for styling customization.
/admin/config/media/simple-popup-blocks/delete/{uid}
Confirmation form to permanently delete a popup configuration.
Permissions 1
Hooks 2
hook_help
Provides help text on the module's help page explaining basic configuration steps.
hook_page_attachments
Attaches the popup JavaScript library and settings to non-admin pages. Reads all active popup configurations and passes them to drupalSettings for JavaScript processing.
Troubleshooting 6
Add CSS to your theme's stylesheet to hide the element by default. Use the CSS selector shown in the edit form's Adjustment class section. Example: #your-block-id { display: none; } This prevents the content from being visible until JavaScript initializes the popup.
1. Clear all Drupal caches (Administration > Configuration > Performance > Clear all caches). 2. Verify the popup status is set to 'Active' on the edit page. 3. Check if the block or CSS element actually exists on the current page. 4. If using visit counts, try setting to '0' to show on every visit for testing. 5. Check browser console for JavaScript errors.
This is expected behavior if visit counts is set to '0' (every visit). Change visit counts to specific numbers (e.g., '1') to show only once, or use time frequency with Daily/Weekly settings to limit how often the popup appears.
Ensure the trigger selector in the popup configuration starts with # or . (e.g., #my-button or .trigger-class). Verify the element with that selector exists on the page. Check that the selector matches exactly including case sensitivity.
The module automatically disables popups on admin routes. If you're seeing unexpected behavior, clear caches and verify you're testing on a non-admin page (e.g., node pages, front page).
Cookie expiry of 0 deletes the cookie when the browser closes (session cookie). Any positive number sets expiration in days. Check if your browser has cookies enabled and isn't blocking third-party cookies. Use browser developer tools to inspect the 'spb_' prefixed cookies.
Security Notes 4
- All popup settings are sanitized using Html::escape() before being passed to JavaScript to prevent XSS attacks
- The module requires the 'administer simple_popup_blocks' permission for all configuration pages
- Cookie values contain only numeric visit counts or timestamps, not sensitive data
- Custom CSS selectors entered by administrators should be validated to prevent injection attacks - the module validates that selectors don't start with . or # in the selector input field