-
Notifications
You must be signed in to change notification settings - Fork 39
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:
- /classes/Triggers.php - Used to initialize and set up triggers
- /assets/js/src/admin/popup-editor/plugins/triggers.js - Used to handle adding triggers to a popup in the popup editor
- /assets/js/src/site/plugins/pum-triggers.js - Handles the actual triggering of a popup based on which triggers are used on the popup.
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
.
All trigger arrays will have the following keys:
-
id
- The unique identifier of the trigger. When passed throughadd_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 asgeneral
). Within each key should be array of PUM_Fields arrays.
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
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.