[Settings] Sidebar

Sidebar info

The "Plugin info" section displays information about the plugin version and its author. Additional information can be added there. To do this, you need to override the extend_info method in which to return an array, each element of the array describes a information string: label and value.

If you also specify the depends key, then when you change the value of this option, additional information will be re-requested from the server via AJAX (this is needed when some information depends on the options configuration). The value on the depends key can be a string (when depending on one option) or an array of strings (when depending on several options). Can use path as key for the depends array.

If you add a link key, the information will be displayed as a external link, where the link value will be used for the href attribute and value for the link content. Also, if value is null, then the information string will be skipped when displayed:

protected function extend_info() {
    return [
        'images'        => [
                'label'		=> __('Images', 'myplugin'),
                'value'		=> count($this->get_attachments()),
        ],
        'galleries'     => [
                'label'		=> __('Galleries', 'myplugin'),
                'value'		=> empty($this->galleries) ? null : count($this->galleries),
                'depends' 	=> 'galleries',
        ],
        'zukit_link'	=> [
                'label'		=> __('Contributors', 'myplugin'),
                'value'		=> __('Zukit Framework', 'myplugin'),
                'link'		=> 'https://github.com/picasso/zukit.git',
        ],
        'memory'        => [
                'label'		=> __('Cached Data', 'myplugin'),
                'value'		=> $this->get_cached_memory(),
                'depends' 	=> ['galleries', 'disable_cache'],
        ],
    ];
}

Sometimes difficult situations arise when data for information is formed in an add-on, the creation of which, in turn, depends on some option. In this case, in order for the information to be re-requested from the server when this option value is changed, you can use a trick with a fake info row that will never be shown but will depend on the option we need:

// $this->stats is add-on which depends on 'use_stats' option
protected function extend_info() {
    return array_merge(
        $this->stats ? $this->stats->stats_info() : [],
        // we use a fake element that will never be displayed since the 'value' is null
        // but will cause the hook to fire when the value of the 'use_stats' option changes
        ['fake' => ['value' => null, 'depends' => 'use_stats']]
    );
}

Sidebar actions

You can define some actions that will be executed from the Settings Page via AJAX. To do this, you need to override the extend_actions method in which to return an array describing the actions that should be displayed in the sidebar. The value key is the name of the action that will be called by AJAX when the button is clicked - this is the $action argument which you must check in the ajax_more method (see below).

The depends key determines as usual whether the button is shown or not, depending on the value of the given option. The value on the depends key can be a string (when depending on one option) or an array of strings (when depending on several options). Can use path as key for the depends array. If you specify the option name with an exclamation mark at the beginning (!option), the button will be displayed when option value is false and will be hidden if true. If depends is false then the button will not be displayed. If you are using an array for the depends key, then you can specify a comparison operation for the option values - the first element of the array determines what the logical operator will be (comparison by AND or OR). If the first element is not equal to && or ||, then the comparison will be by OR:

protected function extend_actions() {
    return [
        [
            'label'     => __('Update Galleries', 'myplugin'),
            'value'     => 'myplugin_update_galleries',
            'icon'      => 'admin-customizer',
            'color'     => 'gold',
            'help'      => __('Galleries will be updated for all images', 'myplugin'),
        ],
        [
            'label'     => __('Convert Galleries', 'myplugin'),
            'value'     => 'myplugin_convert_galleries',
            'color'     => 'green',
            'depends'   => $this->is_convertible() ? 'galleries' : false,
        ],
        [
            'label'     => __('Clean All Cached Data', 'myplugin'),
            'value'     => 'myplugin_reset_cached',
            'icon'      => 'dismiss',
            'color'     => 'magenta',
            'help'      => __('Clear all cached data referenced to galleries', 'myplugin'),
            'depends'   => ['&&', 'cached_galleries', '!disable_cache'],
        ],
    ];
}

You must also define the response to AJAX requests for these actions. This is done by overriding the ajax_more method. You need to check the $action (action name) and perform the necessary actions. If this given $action is not processed, then null must be returned from this method.

Please note that, unlike $action, the $value parameter is not sanitized in the framework and this is entirely your responsibility and must be done in your code.

To form data for the response from the action, you can use the helper method create_notice:

public function ajax_more($action, $value) {
    if($action === 'myplugin_reset_cached') return $this->reset_cached();
    else if($action === 'myplugin_convert_galleries') return $this->convert_galleries();
    else if($action === 'myplugin_update_galleries') return $this->update(sanitize_text_field($value));
    else return null;
}

public function reset_cached() {
    $this->delete_cached('attachments');
    $this->delete_cached('galleries');
    return $this->create_notice('success', __('All cached data were cleared.', 'myplugin'));
}

Sidebar "MoreActions" Slot

Sometimes you need to embed your code in the actions panel, which gives you complete freedom both in displaying the component and in interacting with the server. In this case, you can use the MoreActions slot that is built into the action panel. Anything you put inside <ZukitSidebar.MoreActions> will go to the action panel. If you are not familiar with the SlotFill concept, you can read more in Block Editor Handbook.

// WordPress dependencies

const { __ } = wp.i18n;
const { PanelBody } = wp.components;

// Zukit dependencies

const { toggleOption, renderPage } = wp.zukit.render;
const { ZukitSidebar } = wp.zukit.components;

// Internal dependencies

import { complexProcessing, buttonIcon } from './utils.js';

const EditMySettings = ({
    title,
    options,
    updateOptions,
}) => {

    return (
       <PanelBody title={ title }>
           { toggleOption(optionsData, options, updateOptions) }
       </PanelBody>
       <ZukitSidebar.MoreActions>
           <h3>{ __('Very complex and flexible action', 'myplugin') }</h3>
           <Button
               isPrimary
               className="__run"
               icon={ buttonIcon }
               onClick={ complexProcessing }
           >
               { __('Click to run', 'myplugin') }
           </Button>
       </ZukitSidebar.MoreActions>       
    );
};

renderPage('myplugin', {
    edit: EditMySettings,
});

In order for your component to be displayed in the action panel, you also need to add a special element with the hasMoreActions key in the array, which is returned by the extend_actions method:

protected function extend_actions() {
    return [
        [
            // an indication that we will use the slot for 'MoreActions'
            'hasMoreActions'	=> true,
        ],
        [
            'label'     => __('Revoke Cookie', 'myplugin'),
            'value'     => 'myplugin_revoke_cookie',
            'icon'      => 'food',
            'color'     => 'gold',
            'help'      => __('Set "expires" value on cookie for 1970 which leads to cookie **deleting**.', 'myplugin'),
            'depends'   => 'cookie_notice',
        ],
    ];
}

If you want your component (button) in the action panel to look consistent with other actions (buttons), then you can use the ZukitSidebar.ActionButton framework component:

// Zukit dependencies

const { ZukitSidebar } = wp.zukit.components;

const MyComplexAction = ({
    label,
    help,
    onAction,
}) => {
    return (
       <ZukitSidebar.MoreActions>
           <ZukitSidebar.ActionButton
               color="green"
               icon="welcome-widgets-menus"
               label={ label }
               help={ help }
               onClick={ onAction }
           />
       </ZukitSidebar.MoreActions>       
    );
};

export default MyComplexAction;