[Addons] Helpers

Addons Helpers

Most of the methods that the add-on class contains are just a binding to plugin methods, they just pass parameters to similar plugin functions:

• sprintf_dir(...$params)
• sprintf_uri(...$params)
• ajax_error($error, $params = null)
• check_error($error, $ajax = false, &$report = null)
• ajax_nonce($create = false)
• ajax_send($result)
• create_notice($status, $message, $actions = [])
• log_error($error, $context = null)
• snippets(...$params)

Actions

Your add-on does not need to add action to the init and admin_init events - you just need to override the methods with such names and perform the necessary initializations in them. The clean method will be called when the plugin's clean_addons method is called.

• init()
• admin_init()
• clean()

Options

To work with the add-on options, it is recommended to use your add-on class methods. These methods allow you to get, set and delete only add-on options and the methods themselves take care of updating plugin options as needed. Using the is_plugin_option method, you can check the option value of the plugin that owns this add-on.

• get_option($key, $default = '')
• is_option($key, $check_value = true)
• set_option($key, $value, $rewrite_array = false)
• del_option($key)
• is_plugin_option($key, $check_value = true)

Scripts and styles

The methods for enqueuing scripts/styles are also just bindings to plugin methods, but they automatically add the plugin/theme prefix to the filename passed in. To avoid this behavior, simply pass the 'add_prefix' set to false as one of the params. If you need to load add-on script/styles only for the Settings Page - use the ends_with_slug method.

• enqueue_style($file, $params = [])
• enqueue_script($file, $params = [])
• admin_enqueue_style($file, $params = [])
• admin_enqueue_script($file, $params = [])
• ends_with_slug($hook, $slug = null)

public function admin_enqueue($hook) {
    if(in_array($hook, ['customize.php', 'widgets.php'])) {
        $this->admin_enqueue_script('widgets', [
            'bottom' => false,
            'deps'   => [
                'plupload',
                'jquery-ui-draggable',
                'jquery-ui-droppable',
            ],
        ]);
        // prefix will be added to script name automatically
        $this->admin_enqueue_style('widgets');
    }
    // add styles only for Settings Page (needed for Preview)
    if($this->ends_with_slug($hook)) $this->admin_enqueue_style('widgets');
}

Ajax

If the add-on should respond to Sidebar actions from the Settings Page, then you need to override the ajax method. You should 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. To form data for the response from the action, you can use the helper method create_notice.

public function ajax($action, $value) {
    if($action === 'mycolors_update') {
        $colors_count = $this->update_all_colors($value);
        $message = sprintf('%s color(s) were updated', $colors_count);
        return $this->create_notice('info', $message);
    }
    return null;
}

Miscellaneous

The get method works the same as in the plugin, with the only difference that the second argument is $from_plugin and if it is true then the method will return the plugin configuration value instead of add-on configuration value.

The behavior of the prefix_it method is also slightly different - if the $str argument starts with '!', then the prefix will not be added.

The call method is common interface to plugin methods with availability check (only public functions can be called with this helper).

• get($key, $from_plugin = false, $default_value = null)
• prefix_it($str, $divider = '-')
• call($func, ...$params)