Triggers

Popup Maker uses the trigger system to determine what should cause a popup to open. If you are new to Popup Maker, you can review our "What is a Trigger" documentation to understand what the triggers are. The core parts of this system are:

1. /classes/Triggers.php - Used to initialize and set up triggers
2. /assets/js/src/admin/popup-editor/plugins/triggers.js - Used to handle adding triggers to a popup in the popup editor
3. /assets/js/src/site/plugins/pum-triggers.js - Handles the actual triggering of a popup based on which triggers are used on the popup.

Initialization and saving of triggers

The PUM_Triggers class handles registering, preparing, and retrieving the triggers. All active triggers are stored within the $triggers property of the class: https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Triggers.php#L29

The add_trigger method takes a trigger array, prepares it, and adds it to the $triggers property: https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Triggers.php#L66

All triggers can include settings which can be added to any of the trigger setting tabs registered in get_tabs: https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Triggers.php#L325

The add_triggers method can take an array of trigger arrays and pass it to the add_trigger method individually: https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Triggers.php#L53

The register_triggers method handles the default built-in triggers by preparing the trigger arrays and passing them to add_triggers. To allow for extending and adding new triggers, the triggers array is passed through the pum_registered_triggers filter: https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Triggers.php#L147

Once registered, the triggers are retrieved using get_triggers or get_trigger.

The trigger array

All trigger arrays will have the following keys:

• id - The unique identifier of the trigger. When passed through add_triggers, the key for each trigger array within the triggers array becomes the id if no id is included.
• name - The label for the trigger which will appear in several places including when adding a trigger in the popup editor.
• modal_title - The heading to appear on the settings modal when adding or editing this trigger in the popup editor.
• settings_column - Handles what is shown in the popup editor on the "Triggers" tab. Should be an Underscores template with {{}} to display values.
• priority - The importance of the trigger. Used to order a list of triggers. Lower is more important.
• tabs - The tabs used for the trigger settings. Pass PUM_Triggers->get_tabs() for defaults.
• fields - An array of settings of the trigger. Each key should match one of the settings tabs (such as general). Within each key should be array of PUM_Fields arrays.

Triggers in the popup editor

When the popup editor is loaded, the PUM_Admin_Popups::render_settings_meta_box method is called: https://github.com/PopupMaker/Popup-Maker/blob/cf71d1c064c1fa6c37ce527150639fdc406b0051/classes/Admin/Popups.php#L157

This sets up the JS object which includes triggers: window.pum_popup_settings_editor.triggers. https://github.com/PopupMaker/Popup-Maker/blob/cf71d1c064c1fa6c37ce527150639fdc406b0051/classes/Admin/Popups.php#L178

Then, triggers.js sets up the Trigger table: https://github.com/PopupMaker/Popup-Maker/blob/master/assets/js/src/admin/popup-editor/plugins/triggers.js#L306 and sets up the click event handlers for creating, editing, and removing triggers: https://github.com/PopupMaker/Popup-Maker/blob/master/assets/js/src/admin/popup-editor/plugins/triggers.js#L359

When the button to add a new trigger is clicked, trigger.js uses Popup Maker's template system (docs coming soon) to add the form to Popup Maker's modal system (docs coming soon). The template for the adding trigger modal is defined in PUM_Admin_Templates here: https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Admin/Templates.php#L482

Once the initial modal form is submitted, trigger.js adds a cookie, if selected: https://github.com/PopupMaker/Popup-Maker/blob/master/assets/js/src/admin/popup-editor/plugins/triggers.js#L431

Then, calls triggers.template.form which will show the selected trigger's settings as defined in the tabs and fields keys when registering the trigger: https://github.com/PopupMaker/Popup-Maker/blob/master/assets/js/src/admin/popup-editor/plugins/triggers.js#L105

Once that trigger's settings form is submitted, trigger.js will add the new trigger in the triggers table where the data is attached to hidden inputs for saving:https://github.com/PopupMaker/Popup-Maker/blob/master/assets/js/src/admin/popup-editor/plugins/triggers.js#L67 which uses the template system with the individual row being defined here: https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Admin/Templates.php#L442

The triggers are updated during the normal post save which Popup Maker hooks into with the PUM_Admin_Popups::save method to save the settings including triggers: https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Admin/Popups.php#L272

Triggering a popup

All of the JS for the triggers are defined within the $.fn.popmake.triggers object where each key matches a registered trigger's id. The value assigned to the key is a function that accepts a settings parameter which are the settings edited in the popup editor when adding the trigger. Inside this function is where the JS for opening the popup occurs. For example, in the auto_open key, the function contains the setTimeout() code which includes a call to open the popup using $popup.popmake('open');.

The default object is defined here: https://github.com/PopupMaker/Popup-Maker/blob/master/assets/js/src/site/plugins/pum-triggers.js#L17

Upon the pumInit event, pum-triggers.js cycles over the loaded popups to identify which triggers have been added to the triggers: https://github.com/PopupMaker/Popup-Maker/blob/master/assets/js/src/site/plugins/pum-triggers.js#L150

For each trigger saved to a popup, it calls the addTrigger method which applies the trigger: https://github.com/PopupMaker/Popup-Maker/blob/master/assets/js/src/site/plugins/pum-triggers.js#L5

For example, if a popup only has an auto_open trigger, when pum-triggers.js cycles over the popup, it will only identify the auto_open trigger and call addTriggers for it. The addTriggers will validate the trigger and then apply it calling its function.