Alerts

Popup Maker has its own alert system which is a wrapper for admin notices within the WordPress admin area. For most alerts, they are kept within Popup Maker admin pages instead of being listed on all admin pages.

The alert system has built-in features that enable:

1. Alerts to be added just by adding an array.
2. Alerts to be dismissed by the user.
3. HTML to be displayed within the alert.
4. Buttons to be displayed.
5. Passing which action the user took back to the code.

Looking to just add an alert? Refer to our Adding An Alert page.

How the system works

Alerts are a filterable array that then gets parsed and displayed within the admin notice areas. If dismissible, a dismiss icon will also be present. Once dismissed, the alert will either: Be gone indefinitely or return after X time has passed depending on what values are passed to the array.

Alerts.php contains the PUM_Utils_Alerts class which controls the alerts system and can be found here: https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Utils/Alerts.php

Within, there is the pum_alert_list which filters an array: https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Utils/Alerts.php#L424

The admin_notices method then shows any alerts that need to be shown: https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Utils/Alerts.php#L303

As long as the user is using JavaScript and there are no errors, the alerts.js tracks actions taken and send them to the ajax_handler method: https://github.com/PopupMaker/Popup-Maker/blob/master/assets/js/src/admin/general/plugins/alerts.js and https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Utils/Alerts.php#L458, respectively.

If JavaScript is not working, then it works via page reload and falls back on the php_handler method: https://github.com/PopupMaker/Popup-Maker/blob/master/classes/Utils/Alerts.php#L482

Both of these continue to the action_handler method. If the action was to dismiss the alert, the value for when the alert should return, if ever, is stored in the user meta key _pum_dismissed_alerts. This method then fires off the pum_alert_dismissed hook which contains the code for the alert and the action taken by the user.

The alert array

Within an alert array, there are several keys that you should always use:

1. code - The identifier for the alert. For example, pum_telemetry_notice.
2. type - This relates to the design of the alert. Options are info, success, warning, and error.
3. dismissible - If the alert should never return once dismissed, set this to true. If it is not dismissible, set this to false. Lastly, if the alert should return after some time, enter in a time string such as 2 weeks.
4. global - If set to true, this will make the alert appear across the entire WordPress admin. Almost always, this should be set to false.
5. priority - If there are multiple alerts shown, this will decide the order. Lower priority causes the alert to be higher in the list.

In addition to main keys, there are several optional keys that handle the actual content of the alert:

1. message - The main message of the alert. Will be placed within a <p> element.
2. html - Alternative to the message key. If you need to have more control over the message, you can use HTML within this key.
3. actions - If the alert requires an action from the user or provides a link, use this key as defined below.

The action array

If using the actions key, you will pass an array for each action that the user can take using these keys:

1. primary - Set this to true for the main action you want the user to take. Set it to false for any other actions.
2. type - Set this to action for this to be recorded and sent back to functions. Set this to link for this to just be a link.
3. action - The identifier for the action. Set to dismiss if this action should dismiss the alert. Leave blank if type is set to link.
4. text - The text that will be displayed for the user to click for this action.
5. href - If type is link, pass the URL in this key.

Example alert array

$alerts[] = array(
    'code'        => 'pum_example_alert',
    'type'        => 'info',
    'message'     => "Allow us to do awesome stuff?",
    'priority'    => 10,
    'dismissible' => true,
    'global'      => false,
    'actions'     => array(
        array(
            'primary' => true,
            'type'    => 'action',
            'action'  => 'pum_allow',
            'text'    => __( 'Allow', 'popup-maker' ),
        ),
        array(
            'primary' => false,
            'type'    => 'action',
            'action'  => 'pum_not_allow',
            'text'    => __( 'Do not allow', 'popup-maker' ),
        ),
        array(
            'primary' => false,
            'type'    => 'link',
            'action'  => '',
            'text'    => 'Learn more',
            'href'    => 'https://google.com'
        ),
    ),
);