[Settings] Edit Component

Edit Settings Component

To create a Settings Page, you need to create a React component that will display your plugin/theme options and update them. What this component will be is your own business. The framework only provides a set of methods that will simplify the creation of this component.

This component takes in parameters, called props (short for "properties"):

• id - this is the prefix you defined in your configuration
• wp - current version of WordPress (e.g. 5.4.4)
• info - object with plugin/theme data
• title - default Settings Page title (you can use it or not)
• options - plugin/theme options
• updateOptions - a method that changes plugin/theme options and syncs changes to the server
• ajaxAction - method for performing Ajax actions. You usually won't need it, since all actions are located in the sidebar and are called from there (Sidebar actions). But if you need to perform actions from the settings page, then the method is available
• noticeOperations - object that gives access to functions for creating notices in the Settings Page
• setUpdateHook - method for creating hooks on option update (see Option Hooks for details)

WordPress version

In rare cases, you need to implement different logic for earlier versions of WordPress and for the current one. Knowing the current version of WordPress will help you implement one and your component gets the version value as one of its props. To compare strings with versions, you can use the compareVersions(a, b) functions that are included in the framework's utils module. The function returns a number less than 0 if a < b, a number greater than zero if a > b and 0 if versions are equal.

// Zukit dependencies

const { compareVersions } = wp.zukit.utils;
const { toggleOption } = wp.zukit.render;

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

    const className = compareVersions(wp, '5.5.2') < 0 ? '__unsupported' : null;

    return (
        <PanelBody className={ className } title={ title }>
            { toggleOption(optionsData, options, updateOptions) }
        </PanelBody>
    );
};

Info

You usually don't need information from this object. For the most part, it will be displayed in the sidebar (see the Sidebar info for more details). But if you need to display some of this on the settings page, then below is the structure of this object:

    [
        'version'       => $this->version,
        // yes, I know that should not use a variable as a text string
        // 'Poedit' will pull these strings from the plugin description
        'title'         => __($this->data['Name'], $domain),
        'author'        => __($this->data['Author'], $domain),
        'link'          => __($link, $domain),
        'description'   => __($desc, $domain),
        'icon'          => $this->get('appearance.icon'),
        'colors'        => $this->get('appearance.colors'),
        'more'          => $this->extend_info(),
    ];

updateOptions

updateOptions(update, reset = false) - method that changes plugin/theme options.

The first argument is an object of key/value pairs. Each key can contain path (dots separated keys). If value is null then this key will be removed from options (that is, the method works like delete_option).

If the second argument is true then the update object will be used to reset the option values to those specified by this object. It is not recommended to use this argument, the sidebar already contains a Reset Plugin Options button that implements this functionality.

ajaxAction

As mentioned above, you probably won't need this method.

ajaxAction(params, callback) - method for performing some actions via Ajax.

The first argument can be a string, and then this is the name of the action to which your plugin should react in the ajax_more method. If this argument is an object, then there must be two keys: action and value. These are exactly the arguments that will be passed to your ajax_more method. action is a string that identifies your action and it will be sanitized in the framework. value is additional data that you can pass to your handler.

The second argument (optional) is a callback that will be called when a response is received from the server and to which the data element of Ajax response will be passed as an argument. It is recommended that you create a response with the helper method create_notice.

// in your JS code
ajaxAction({
    action: 'myplugin_update_stats',
    value: { id: selectedId, name: statsName },
},
    data => updatedStats(data)
);

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.

// in your PHP code
private function sanitize_stats($data) {
    return is_array($data) ? [
        'id'   => intval($data['id'] ?? 0),
        'name' => sanitize_text_field($data['name'] ?? ''),
    ] : null;
}

// if you just need to return data
public function ajax_more($action, $value) {
    if($action === 'myplugin_update_stats') {
        $sanitized_value = $this->sanitize_stats($value);
        $stats = $this->update_stats($sanitized_value);
        return $this->create_notice('data', null, $stats);
    }
    return null;
}

// if you need to return data and display an info message as notice
public function ajax_more($action, $value) {
    if($action === 'myplugin_update_stats') {
        $sanitized_value = $this->sanitize_stats($sanitized_value);
        $stats = $this->update_stats($sanitized_value);
        return $this->create_notice(
            // combine 'info' status with 'data'
            'infodata',
            'Plugin statistics updated',
            $stats
        );
    }
    return null;
}

For sidebar actions, see the appropriate section for more details.

noticeOperations

If you need to display notice on the Settings Page, you can do it as follows:

    const { createNotice } = noticeOperations;
    const noticeStatus = 'info';
    const noticeMessage = __('Plugin data updated', 'myplugin');

    createNotice({
        status: noticeStatus,           // Can be one of: 'success', 'info', 'warning', 'error'
        content: noticeMessage,         // Text string to display
        isDismissible: true,            // Whether the user can dismiss the
    });

You can read more about the functions available in noticeOperations in the Gutenberg documentation.