This comprehensive reference provides developers with all the tools needed to extend and customize Simply Popups beyond the standard settings.

Table of Contents

1. Architecture Overview
2. Customizing the Frontend
3. Allowing Script Tags
4. Hooks and Filters
5. JavaScript Extension
6. Extending Blocks

Architecture Overview

Simply Popups is built using:

• React for the Block Editor (Gutenberg) interface.
• Standard WordPress PHP API for backend logic and rendering.
• Vanilla JavaScript for frontend interactions (no jQuery required for the core modal functionality, though jQuery is supported).

Customizing the Frontend

CSS Customization

Simply Popups uses Bootstrap 5 Modal CSS classes for styling.

Core Classes:

• .simply-popups : The main modal wrapper (also has .modal for Bootstrap compatibility).
• .modal-backdrop : The background backdrop.
• .modal-content : The inner container holding your content.
• .modal-header : The header section containing the title and close button.
• .modal-body : The main content area.
• .close : The close button.
• .wp-block-simply-popups-content : Block-specific wrapper class.

You can enqueue custom styles using the standard WordPress wp_enqueue_scripts hook, or use the Additional CSS section in the Customizer.

Disabling Default Styles

If you prefer to provide 100% custom styling and want to disable the plugin’s default CSS:

add_action( 'wp_enqueue_scripts', function() {
    wp_dequeue_style( 'simply-popups' );
}, 20 );

Allowing Script Tags

By default, Simply Popups restricts the use of <script> tags within popup content for security reasons. However, developers can enable script tags (for example, to embed third-party forms or tracking codes) using a WordPress filter.

Security Warning

The simply_popup_allowed_tags Filter

You can use the simply_popup_allowed_tags filter to modify the list of allowed HTML tags and attributes in Simply Popups content.

Code Snippet

Add the following code to your theme’s functions.php file or a custom code snippets plugin:

add_filter( 'simply_popup_allowed_tags', function( $tags ) {
    // Add script tag to allowed list
    $tags['script'] = array(
        'src' => true,
        'type' => true,
        'async' => true,
        'defer' => true,
    );
    
    return $tags;
} );

Parameters

• $tags (array): An array of allowed HTML tags and their attributes, formatted for wp_kses.

How It Works

1. The filter intercepts the allowed tags list before the popup content is rendered.
2. We add the 'script' key to the array.
3. Inside the 'script' array, we define which attributes are allowed (e.g., src, type). Setting them to true permits them.

Testing Your Changes

1. Add the code snippet to your site.
2. Open the Block Editor and add a Custom HTML block inside your Simply Popups block.
3. Insert your script code, for example:

   <script src="https://example.com/external-script.js"></script>
   <script>console.log('Popup script loaded');</script>

1. Update the page and view the popup on the frontend.
2. Open the browser console (F12) to verify the script executes.

Troubleshooting

• Script not running? Ensure you have cleared any caching plugins after adding the code.
• Editor warning? The Block Editor might still show a warning about “invalid HTML,” but the frontend should render the script if the filter is active.
• Attributes stripped? Make sure you have explicitly listed all attributes you need (like id , class , data-attributes ) in the array.

Hooks and Filters

Simply Popups provides several hooks and filters that allow developers to modify the plugin’s behavior and output.

Filters

simply_popup_allowed_tags

Modifies the list of allowed HTML tags and attributes within the popup content. This is useful for allowing restricted tags like <script> or <iframe> that are normally stripped for security.

Parameters:

• $tags (array): An array of allowed tags and attributes compatible with wp_kses.

Usage Example:

add_filter( 'simply_popup_allowed_tags', 'my_custom_popup_tags' );

function my_custom_popup_tags( $tags ) {
    // Allow script tags
    $tags['script'] = array(
        'src' => true,
        'type' => true,
    );
    return $tags;
}

Actions

simply_popups_shortcode

Fires when a Simply Popups shortcode is being processed. Use this to perform additional actions when a popup is rendered.

Parameters:

• $atts (array): The shortcode attributes passed by the user.

Usage Example:

add_action( 'simply_popups_shortcode', function( $atts ) {
    // Log popup usage or enqueue additional scripts
    error_log( 'Popup rendered with attributes: ' . print_r( $atts, true ) );
} );

Filters (continued)

frm_modal_link

Filters the HTML of the trigger link/button generated by the shortcode.

Parameters:

• $link_html (string): The full HTML <a> tag for the trigger.
• $atts (array): The shortcode attributes.

Usage Example:

add_filter( 'frm_modal_link', function( $link_html, $atts ) {
    // Add a tracking class to all modal links
    return str_replace( 'class="', 'class="track-click ', $link_html );
}, 10, 2 );

JavaScript Events

Simply Popups uses Bootstrap 5 Modal under the hood, so you can listen to Bootstrap modal events on the popup elements. Note that Bootstrap is bundled internally and not exposed as a global bootstrap object, but the events still work normally.

shown.bs.modal

Triggered when a popup is fully shown (after CSS transitions complete).

Usage:

document.addEventListener('shown.bs.modal', function(e) {
    console.log('Popup opened!', e.target.id);
});

hidden.bs.modal

Triggered when a popup is fully hidden.

Usage:

document.addEventListener('hidden.bs.modal', function(e) {
    console.log('Popup closed!', e.target.id);
});

Other Bootstrap Modal Events

• show.bs.modal – Fires immediately when show is called
• hide.bs.modal – Fires immediately when hide is called

JavaScript Extension

Using Data Attributes (Recommended)

The easiest way to trigger popups programmatically is using Bootstrap data attributes on any element:

<!-- Add this to any element to trigger a popup -->
<button data-bs-toggle="modal" data-bs-target="#simply-popups-0">Open Popup</button>

<!-- For links -->
<a href="#" data-bs-toggle="modal" data-bs-target="#simply-popups-0">Open Popup</a>

The popup ID follows the pattern simply-popups-{index} where index starts at 0 for the first popup on the page.

Using jQuery (If Available)

If your theme or another plugin loads jQuery with Bootstrap modal support, you can use jQuery methods:

// Open a popup
jQuery('#simply-popups-0').modal('show');

// Close a popup
jQuery('#simply-popups-0').modal('hide');

// Toggle a popup
jQuery('#simply-popups-0').modal('toggle');

Using Vanilla JavaScript

You can trigger popups by simulating a click on the trigger button:

// Find and click the popup trigger button
const triggerButton = document.querySelector('[data-bs-target="#simply-popups-0"]');
if (triggerButton) {
    triggerButton.click();
}

// Or dispatch a custom event to close
const modal = document.getElementById('simply-popups-0');
const closeBtn = modal.querySelector('[data-bs-dismiss="modal"]');
if (closeBtn) {
    closeBtn.click();
}

Extending Blocks

Since Simply Popups is a standard Gutenberg block, you can extend it using WordPress Block Filters.

Modifying Block Attributes

You can use the blocks.registerBlockType filter in JavaScript to add custom attributes to the Simply Popups block.

function addCustomAttribute( settings, name ) {
    if ( name !== 'simply-popups/popup' ) {
        return settings;
    }

    return lodash.assign( {}, settings, {
        attributes: lodash.assign( {}, settings.attributes, {
            myCustomAttribute: {
                type: 'string',
                default: '',
            },
        } ),
    } );
}
wp.hooks.addFilter(
    'blocks.registerBlockType',
    'my-plugin/add-custom-attribute',
    addCustomAttribute
);

Related Articles

• Complete Styling Guide
• Using Simply Popups in Gutenberg
• Troubleshooting Common Issues