backend_prod_filters

Adds custom products filtering options in the new interface (2.0). Each option can be applied either only once or in several instances, each with different filtering values specified by a user.

Shop-Script

Input (passed by reference)

$params['collection'] shopProductsCollection|null Instance of products collection class. Call public methods of this class; e.g., addWhere() or addJoin(), to apply additional filtering of products according to the set up rules available in the $params['filter']['rules'] parameter. This parameter may be empty when the app only needs to obtain the available list of filtering options without building a filtered product list.

$params['filter'] array|null Information about filters applied to obtain a product list. This parameter may be empty when the app only needs to obtain the available list of filtering options without building a filtered product list.

$params['filter']['rules'] array The list of all set up filtering rule groups, including the built-in ones of Shop-Script and those added by plugins.

$params['filter']['rules'][]['type'] string Filtering rule identifier. Can be used to determine whether a rule belongs to the current plugin and thus whether it needs to be processed.

$params['filter']['rules'][]['rules'] array Information about all filtering rule values specified by a user.

$params['filter']['rules'][]['rules'][]['rule_params'] string An individual rule value by which products have to be filtered.
… your plugin code …

Output

$return
The list of filtering options, added by a plugin, which must be available to a user. Each list item must be an array with the following keys:
- name Localized name visible in the available list of products filtering options.
- rule_type Filtering option identifier. Must begin with the plugin ID so that you can identify this option in the $params['filter']['rules'][]['type'] parameter value.
- replaces_previous Flag denoting whether the filtering option can be applied only once per product list. If the flag is not set then the filtering option can be applied several times, each time with a different value specified by a user. Each new instance of a filtering option adds another filtering limitation to the displayed product list.
- render_type Type of control used for the filtering option setup, from the following list: 'range' (2 text fields accepting a minimum and a maximum range values in an arbitrary text format), 'range.date' (2 fields allowing to specify a date range), 'radio' (list of radio buttons), 'checklist' (list of checkbox-like switches), 'custom' (custom user interface built with your own HTML code).
- options The list of values available to a user. For the types 'range' and 'range.date' specified in the 'render_type' field can be used an optional list of only 2 items to suggest a user default values of the beginning and the end of a data range. These default values can be modified by a user. Each list item must be an array with the following keys:
- options[]['value']: Value, which if selected by a user, will be available in the $params['filter']['rules'][]['rules'][]['rule_params'] parameter value.
- options[]['name']: Localized title of a value. Used only for the 'radio' and 'checklist' types.
- html: HTML code string to display a custom user interface for the selection of filtering values of a 'custom' type control. On the server will be available (as a string value of the $params['filter']['rules'][]['rules'][]['rule_params'] parameter) only the value of an HTML element with the name="rule_params" attribute. Therefore, if a user can edit multiple controls then use JavaScript to copy all their values to a single (usually hidden) field with that attribute. To combine several values into one, you may use the JSON format, for instance.
- dialog_url: URL from which an HTML code string must be downloaded for a 'custom' type control if no HTML code is specified for the 'html' key.
Shop-Script

Plugin code example

PHP

public function backendProdFilters(&$params)
{
    // process filters set up by a user
    if (!empty($params['filter']['rules'])) {
        /** @var shopProductsCollection $collection */
        $collection = $params['collection'];

        foreach ($params['filter']['rules'] as $rule) {
            if ($rule['type'] === 'myplugin_radio') {
                if ($rule['rules'][0]['rule_params'] === '100') {
                    $collection->addWhere('p.price > 100');
                }
            }
        }
    }

    // return available filtering options
    return [
        [
            'name' => _wp('Simple range filter'),
            'rule_type' => 'myplugin_range',
            'replaces_previous' => false,
            'render_type' => 'range',
            'options' => [
                ['value' => '1'],
                ['value' => '1000'],
            ],
        ],
        [
            'name' => _wp('Date range filter'),
            'rule_type' => 'myplugin_range_date',
            'replaces_previous' => true,
            'render_type' => 'range.date',
            'options' => [
                ['value' => '2022-11-11'],
                ['value' => '2023-11-11'],
            ],
        ],
        [
            'name' => _wp('Radio filter'),
            'rule_type' => 'myplugin_radio',
            'replaces_previous' => true,
            'render_type' => 'radio',
            'options' => [
                ['value' => '10', 'name' => _wp('over 10')],
                ['value' => '100', 'name' => _wp('over 100')],
                ['value' => '1000', 'name' => _wp('over 1000')],
            ],
        ],
        [
            'name' => _wp('Check list filter'),
            'rule_type' => 'myplugin_checklist',
            'replaces_previous' => true,
            'render_type' => 'checklist',
            'options' => [
                ['value' => 'one', 'name' => _wp('one')],
                ['value' => 'two', 'name' => _wp('two')],
                ['value' => 'three', 'name' => _wp('three')],
            ],
        ],
        [
            'name' => _wp('Custom dialog filter'),
            'rule_type' => 'myplugin_custom',
            'replaces_previous' => true,
            'render_type' => 'custom',
            // 'html' => 'custom HTML here if "dialog_url" field is not used',
            'dialog_url' => '?plugin=myplugin&module=products&action=filterDialog',
        ],
    ];
}