Adding A Trigger

Using Popup Maker's trigger system, you can add new ways for popups to opened. In this example, we will be adding our delay trigger which allows admins to enter milliseconds for a delay before the popup auto-opens. On the frontend, we will use JavaScript's setTimeout to achieve the delay.

Registering the trigger

To add a new trigger, we need to utilize the pum_registered_triggers filter to merge in our trigger array. For the triggers, Popup Maker has three default tabs to add trigger settings to with keys of general, cookie, and advanced.

The settings for the trigger uses our PUM_Fields system (docs coming soon).

/**
* Adds our trigger to the registered triggers
*
* @param array $triggers The existing registered triggers.
* @return array The updated triggers array
*/
function pum_example_new_trigger( $triggers = array() ) {

    // Merge our new trigger into the current registered triggers array.
    return array_merge( $triggers, array(
        'auto_open'       => array(   // The ID for this trigger.
            'name'            => __( 'Time Delay / Auto Open', 'popup-maker' ), // The name that the admin will select to choose this trigger.
            'modal_title'     => __( 'Time Delay Settings', 'popup-maker' ), // The heading for the modal when the admin is adjusting this trigger.
            'settings_column' => sprintf( '<strong>%1$s</strong>: %2$s', __( 'Delay', 'popup-maker' ), '{{data.delay}}' ), // Data to be shown in the column of the triggers display. Should be an Underscores template.
            'fields'          => array( // The settings for the trigger.
                'general' => array( // ID of the tab to add these settings to. Each array inside should be an array of PUM_Fields arrays.
                    'delay' => array(  // The field key is how we will refer to this setting on the frontend.
                        'type'  => 'rangeslider',
                        'label' => __( 'Delay', 'popup-maker' ),
                        'desc'  => __( 'The delay before the popup will open in milliseconds.', 'popup-maker' ),
                        'std'   => 500,
                        'min'   => 0,
                        'max'   => 10000,
                        'step'  => 500,
                        'unit'  => 'ms',
                    ),
                ),
            ),
        ),
    ));
}

add_filter( 'pum_registered_triggers', 'pum_example_new_trigger' );

Triggering the popup

The actual triggering of the popup will be added to a JavaScript file. All trigger functions are contained within the $.fn.popmake.triggers property which is created by Popup Maker. To add your trigger, you can extend this object. Popup Maker will review this object with each popup it loads and then assign the functions to the correct popups.

Popup Maker will pass the popup's settings to the function when it is called. Then, since we defined our setting above with the delay key, we can access that setting using settings.delay.

We can use the PUM.getPopup method to retrieve the exact popup which we will use to check the cookies and to open the popup.

Inside your function, you can do any calculations or tests needed to decide when to open the popup. Just be sure to call $popup.popmake('open'); at some point so the popup opens. In our case, we are adding a delay, so we will place the $popup.popmake('open'); inside of setTimeout with our settings.delay as the argument.

(function ($) {
    $.extend($.fn.popmake.triggers, {
        auto_open: function (settings) { // This key must match the key used when registering the trigger.
            var $popup = PUM.getPopup(this); // Retrieve this popup.

            // Merge in defaults, in case some of the settings are missing.
            settings = $.extend({
                delay: 0,
            }, settings);

            // Set a delayed open.
            setTimeout(function () {

                // If the popup is already open return.
                if ($popup.popmake('state', 'isOpen')) {
                    return;
                }

                // If cookie exists or conditions fail return.
                if ($popup.popmake('checkCookies', settings) || !$popup.popmake('checkConditions')) {
                    return;
                }

                // Set the global last open trigger to a text description of the trigger.
                $.fn.popmake.last_open_trigger = 'Auto Open - Delay: ' + settings.delay;

                // Open the popup.
                $popup.popmake('open');

            }, settings.delay);
        },
    });
}(window.jQuery));