Custom Operator Tools

Operators can be managed through the back-end section of VikBooking, and they can be given access to several different "tools", such as "Tableaux" or "Finance". Operators have always been used for a large variety of purposes, from housekeeping functionalities to co-hosting needs.

If you need to give your operators some custom tools to perform specific operations, or to consult specific data, then you can use the below described hooks to implement your own operator tools with related permissions that can change from one operator to another.

Such hooks should be either defined in your Theme's functions.php file, or, better, they can be placed inside a dedicated PHP file that will be installed and published on your WordPress website. Using a custom WordPress plugin is the best way to safely survive to any future update, either of VikBooking or WordPress itself.

<?php
/*
Plugin Name:  VikBooking Custom Operator Tools
Plugin URI:   https://vikwp.com/plugin/vikbooking
Description:  Custom operator tools for VikBooking.
Author:       E4J s.r.l.
Author URI:   https://vikwp.com
License:      GPL2
License URI:  https://www.gnu.org/licenses/gpl-2.0.html
*/

// no direct access
defined('ABSPATH') or die('No script kiddies please!');

/**
 * Register callback to filter "vikbooking_load_operator_tool_permission_types".
 * Fires when VikBooking loads the operator tools and related permission settings.
 * 
 * @param   array|null  $return     The currently registered custom operator tools.
 * 
 * @return  array       Associative list of operator-tool associative arrays|objects.
 */
add_filter('vikbooking_load_operator_tool_permission_types', function($return)
{
    if (!$return)
    {
        // ensure the value is an array
        $return = [];
    }

    /**
     * Since multiple plugins could add their own custom operator tools, it
     * is necessary to always merge the types of tool permissions of this plugin
     * to any previous tool that may have already been defined by other plugins.
     * 
     * In this example, we are telling VikBooking to load two custom operator tools
     * with related permission types. This way, you will be able to configure the
     * settings for each operator to access your tools in a different way.
     * 
     * Permissions for each tool must be defined, either as an empty array, or as
     * an associative list of permission objects. Available field types are:
     * 
     * - "select"       A drop-down menu with a list of options.
     * - "number"       An input field of type number.
     * - "text"         An input field of type text.
     * - "textarea"     A text-area field.
     * - "checkbox"     An input field of type checkbox.
     * - "password"     An input field of type password.
     * 
     * You can eventually pass along additionally properties to your custom permissions.
     * 
     * @see     VBOParamsRendering
     */
    return array_merge($return, [
        // first custom operator tool
        'custom_name' => [
            'name'        => __('Custom Name'),
            // list of the permission fields to define the tool settings
            'permissions' => [
                'perm_one' => [
                    'type'    => 'select',
                    'label'   => __('Sample one'),
                    'options' => [
                        1 => __('Yes'),
                        0 => __('No'),
                    ],
                ],
                'perm_two' => [
                    'type'  => 'number',
                    'label' => __('How many?'),
                    'min'   => 0,
                    'max'   => 10,
                ],
            ],
        ],
        // second custom operator tool
        'custom_two' => [
            'name'        => __('Custom Two'),
            // list of the permission fields to define the tool settings
            'permissions' => [
                'perm_one' => [
                    'type'  => 'text',
                    'label' => __('Some text'),
                    'help'  => __('Some help text'),
                ],
                'perm_two' => [
                    'type'  => 'number',
                    'label' => __('Just a number'),
                    'min'   => 0,
                    'max'   => 100,
                ],
            ],
        ],
    ]);
});

/**
 * Triggers an action to let third-party plugins register the rendering method for a custom operator tool.
 * Hook name is built as "vikbooking_render_operator_tool_" + "tool identifier string".
 * 
 * @param   string  $tool           The tool identifier string.
 * @param   array   $operator       The operator record accessing the current tool.
 * @param   object  $permissions    Registry (VikWPObject) to quickly access the operator tool permission values.
 * @param   string  $tool_uri       The routed URI pointing to this tool (useful for form actions or base link URIs).
 */
add_action('vikbooking_render_operator_tool_custom_name', function($tool, $operator, $permissions, $tool_uri)
{
    echo sprintf(
        'Hi %s, you\'ve got %d as an example permission value.',
        $operator['first_name'],
        $permissions->get('perm_two', 0)
    );
}, 10, 4);

/**
 * Triggers an action to let third-party plugins register the rendering method for a custom operator tool.
 * Hook name is built as "vikbooking_render_operator_tool_" + "tool identifier string".
 * 
 * @param   string  $tool           The tool identifier string.
 * @param   array   $operator       The operator record accessing the current tool.
 * @param   object  $permissions    Registry (VikWPObject) to quickly access the operator tool permission values.
 * @param   string  $tool_uri       The routed URI pointing to this tool (useful for form actions or base link URIs).
 */
add_action('vikbooking_render_operator_tool_custom_two', function($tool, $operator, $permissions, $tool_uri)
{
    echo sprintf(
        'Hi %s, you\'ve got the following text value assigned for this tool: %s',
        $operator['first_name'],
        $permissions->get('perm_one', '')
    );
}, 10, 4);

This is how with a simple plugin you can define unlimited custom operator tools and related permissions. You can look at the existing operator tools to get some inspiration about the usefulness of the permissions for each tool that can change from one operator to another.

By packing the above code snippet into a single PHP file, you will have created your own custom WordPress plugin to extend the operator tools functionalities of VikBooking. This PHP file could be given a name similar to vbo_custom_operator_tools.php and you can upload it manually onto the WordPress installation directory, onto /wp-content/plugins/. The last step will be making sure the plugin is active in the WordPress plugins list page.