Frontend filters API

Changing filter values within a filter box
To access and change the values of filter items use the asp_pre_get_front_filters hook, as following:
1
add_filter('asp_pre_get_front_filters', 'asp_change_a_filter', 10, 2);
2
function asp_change_a_filter($filters, $type) {
3
  foreach ($filters as $k => &$filter) {
4
    // To check some of the attributes:
5
    // $filter->label
6
    // $filter->display_mode
7
    // $filter->position
8
    // $filter->id
9
    // $filter->type() >> returns the filter type
10
    // $filter->field() >> field that is filtered (if applicable)
11
    // do a var_dump($filter->data) -> to see the filter data
12
    
13
    // Go through the filter items via a loop
14
    foreach ($filter->get() as $kk => $item) {
15
      // Changing a filter attribute: label, selected, value, default by array ID
16
      $filter->attr($kk, 'label', 'New Label', true);
17
​
18
      // Remove the current item by array ID
19
      $filter->remove($kk, true);
20
    }
21
    
22
    // You can also change/remove items by key, without a loop
23
    // ..for a category/term filter, use the term ID
24
    $filter->attr(123, 'label', 'New Label');
25
    $filter->remove(123);
26
    // ..for a custom field filter, use the field value
27
    $filter->attr('value', 'label', 'New Label');
28
    $filter->remove('value'); 
29
​
30
    // Remove values from a custom field filter
31
    if ( $filter->type() == 'custom_field' && $filter->field() == 'my_field' ) {
32
      $filter->remove(array('value1', 'value2'));
33
    }    
34
    // Adding a new value to a custom field filter
35
    if ( $filter->type() == 'custom_field' && $filter->field() == 'my_field' ) {
36
      $filter->add(array(
37
        'label' => 'Value label 1',
38
        'selected' => false,
39
        'value' => 'value1'
40
      ));
41
      
42
      // The second function argument allows setting the value position
43
      // Adding a value after the 2nd option
44
      $filter->add(array(
45
        'label' => 'Value label 2',
46
        'selected' => false,
47
        'value' => 'value2'
48
      ), 2);
49
      
50
      // Adding a value to before the last option
51
      $filter->add(array(
52
        'label' => 'Value label 3',
53
        'selected' => false,
54
        'value' => 'value3'
55
      ), -1);
56
    }    
57
  }
58
  return $filters;
59
}
Copied!
The WD_ASP_FrontFilters singleton class
This API should be used to manage the front-end filter boxes. The class methods can be used to add/remove/modify/find any front-end filter box.
Source
File: wp-content/plugins/ajax-search-pro/includes/classes/core/class-asp-frontfilters.php
The front-end filter management is encapsulated within the WD_ASP_FrontFilters class, and it's instance can be accessed via the..
1
wd_asp()->front_filters
Copied!
..variable, or if you prefer your own, then:
1
$my_variable = WD_ASP_FrontFilters::getInstance();
Copied!
Usage
For usage examples, please see the chapter below.
Filters should be added, changed and removed exlusively within the asp_pre_parse_filters and asp_post_parse_filters action hooks. Using any other hooks may result in a malfunction.
Example of changing and removing certain filters by their labels:
1
add_action('asp_post_parse_filters', 'asp_change_the_filters', 10, 2);
2
function asp_change_the_filters($search_id, $options) {
3
    if ( $search_id == 1 ) {
4
        // Change filter position to 1
5
        wd_asp()->front_filters->set("Test drop", 'position', 1);
6
        // Change filter label
7
        wd_asp()->front_filters->set("Test drop", 'label', 'My test drop');
8
        // Remove a filter by label
9
        wd_asp()->front_filters->remove("Filter by Product categories");
10
    }
11
}
Copied!
Example of adding a custom taxonomy filter:
1
add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
2
function asp_add_my_own_filters($search_id, $options) {
3
    if ( $search_id == 1 ) {
4
        // Creating a new filter
5
        $filter = wd_asp()->front_filters->create(
6
            'taxonomy',
7
            'My Taxonomy Filter',
8
            'dropdown',
9
            array(
10
                'taxonomy' => 'category'
11
            )
12
        );
13
        // Adding the select all option first
14
        $filter->add(array(
15
            'id' => 0,
16
            'label' => 'Select all',
17
            'default' => true,
18
            'selected' => true
19
        ));
20
        // Getting the terms to add
21
        $terms = get_terms("category", array(
22
            'hide_empty' => false,
23
            'fields' => 'id=>name'
24
        ));
25
        foreach( $terms as $id => $name ) {
26
            // Add each taxonomy terms one by one
27
            $filter->add(array(
28
                'id' => $id,
29
                'label' => $name,
30
                'taxonomy' => 'category',
31
                'default' => false,
32
                'selected' => false
33
            ));
34
        }
35
        /**
36
         * Make sure to change the filter options, if there was a
37
         * redirection to the results page.
38
         **/ 
39
        $filter->selectByOptions($options);
40
        /**
41
         * Optionally, you can change the filter position as well, via:
42
         * $filter->position = 1;
43
         **/
44
        // Finally, append the filter
45
        wd_asp()->front_filters->add($filter);
46
    }
47
}
Copied!
For methods list and examples, please check below.
Methods list
create()
1
create(string $type, string $label = '', string $display_mode = '', array $data = array())
Copied!
Creates and returns a new filter object, depending on the $type variable. This will not add the filter automatically to the filters list, only creates a new object. The filter has to be added via the add($filter) method after.
Parameters
$type (string) - The filter type, can be: taxonomy
$label (string) (optional) - The filter box header label
$display_mode (string) (optional) - The display mode of the filter values: checkboxes, input, slider, range, dropdown, radio, dropdownsearch, multisearch
$data (array) (optional) - Additional data, that may be required within the template for this filter depending on the $type and $display_mode
Check the examples below for the usage.
Return values
(aspFilter | aspCfFilter | aspTaxFilter) The new filter object
add()
1
add( aspFilter $filter )
Copied!
Adds the final $filter object to the front-end filters list.
Parameters
(aspFilter) $filter - The filter object to add to the front-end filters list
Return values
(aspFilter | aspCfFilter | aspTaxFilter) The new filter object
set()
1
set( int|string $key, string $attribute, mixed $value )
Copied!
Finds a filter by title or ID ($key) and changes it's attribute.
Parameteres
$key (int|string) - Filter ID or filter label text
$attribute (string) - Filter attribute: label, display_mode, data, position
$value (mixed) - Value to change the attribute to
Return values
(bool) true|false - True, when the change was successful, false otherwise.
get()
1
get( string $order = 'position', $type = false )
Copied!
Gets the registered filters by the given order and the given type
Parameteres
$order (string)(optional) - position or added
$type (bool | string)(optional) - filter type: taxonomy, custom_field or boolean false for everything
Return values
array - Array of front-end filters
remove()
1
remove( int|string $key )
Copied!
Removes a filter from the front-end filters list, based on the ID or filter label.
Parameters
$key (int|string) - Filter ID or filter label text
Return values
(bool) true|false - True, when the removal was successful, false otherwise.
Examples
Adding custom taxonomy filter
The example below displays adding a custom taxonomy filter, with a select all option. The commented sections contain the possible parameters for this type of filter.
1
add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
2
function asp_add_my_own_filters($search_id, $options) {
3
    if ( $search_id == 1 ) {
4
        $filter = wd_asp()->front_filters->create(
5
            'taxonomy',                // Filter type
6
            'My Product cat filter',   // Filter box label 
7
            'checkboxes',              // Display mode: checkboxes, dropdown, dropdownsearch, multisearch, radio
8
            array(
9
                'taxonomy' => 'category',
10
                // allowing CPT results that does not match the terms from this taxonomy
11
                'allow_empty' => false, 
12
                'logic' => 'or' // or, and,
13
            )
14
        );
15
        // The select all must have the ID = 0
16
        $filter->add(array(
17
            'id' => 0,
18
            'label' => 'Select All',
19
            'default' => true,
20
            'selected' => true
21
        ));
22
        $filter->add(array(
23
            'id' => 81,
24
            'label' => 'Clothing',
25
            'taxonomy' => 'category',
26
            'default' => true,
27
            'selected' => true
28
        ));
29
        $filter->add(array(
30
            'id' => 84,
31
            'label' => 'Posters',
32
            'taxonomy' => 'category',
33
            'default' => true,
34
            'selected' => true
35
        ));
36
        /**
37
         Another variation, by adding all categories
38
            $terms = get_terms("category", array(
39
                'hide_empty' => false,
40
                'fields' => 'id=>name'
41
            ));
42
            foreach( $terms as $id => $name ) {
43
                $filter->add(array(
44
                    'id' => $id,
45
                    'label' => $name,
46
                    'taxonomy' => 'category',
47
                    'default' => false,
48
                    'selected' => false
49
                ));
50
            }
51
        */    
52
    
53
        $filter->selectByOptions($options);
54
        wd_asp()->front_filters->add($filter);
55
    }
56
}
Copied!
Dropdown, checkbox and radio type custom field filters
1
// --------------------------------
2
// Drop down filter example - for WooCoomerce stock status
3
// --------------------------------
4
add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
5
function asp_add_my_own_filters($search_id, $options) {
6
    if ( $search_id == 1 ) {
7
        // Dropdown
8
        $filter = wd_asp()->front_filters->create(
9
            'custom_field',
10
            'Dropdown stock test',
11
            // Type: dropdown, dropdownsearch, multisearch or radio
12
            'dropdown',
13
            array(
14
                'field' => '_stock_status',
15
                /**
16
                 * Operators list:
17
                 *  String
18
                 *     like  => string matching anywhere
19
                 *     elike => string matching exactly
20
                 *  Numeric
21
                 *     eq   => equals '='
22
                 *     neq  => not equal '<>'
23
                 *     lt   => less '<'
24
                 *     let  => less or equals '<='
25
                 *     gt   => greater '>'
26
                 *     get  => greater or equals '>='
27
                 */
28
                'operator' => 'like',
29
                // only applies on 'dropdown' type (multiselect for dropdown)
30
                'multiple' => true,
31
                // or or and, only applies for 'multisearch' or 'dropdown' + multiple
32
                'logic' => 'or',
33
                // allow match if this custom field is unset
34
            )
35
        );
36
        $filter->add(array(
37
            'label' => 'Any stock (empty val)',
38
            'value' => '',
39
            'selected' => true,
40
            'default' => true
41
        ));
42
        $filter->add(array(
43
            'label' => 'Any stock (multi val)',
44
            'value' => 'instock::outofstock',
45
            'selected' => true,
46
            'default' => true
47
        ));
48
        $filter->add(array(
49
            'label' => 'In Stock',
50
            'value' => 'instock',
51
            'selected' => true,
52
            'default' => true
53
        ));
54
        $filter->add(array(
55
            'label' => 'Out of Stock',
56
            'value' => 'outofstock',
57
            'selected' => false,
58
            'default' => false
59
        ));
60
        $filter->selectByOptions($options);
61
        wd_asp()->front_filters->add($filter);
62
    }
63
}
Copied!
Text and hidden type custom field filters
1
// --------------------------------
2
// Text or hidden filter example
3
// --------------------------------
4
add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
5
function asp_add_my_own_filters($search_id, $options) {
6
    if ( $search_id == 1 ) {
7
        $filter = wd_asp()->front_filters->create(
8
            'custom_field',
9
            'Text stock',
10
            // text or hidden
11
            'text',
12
            array(
13
                'field' => '_stock_status',
14
                // See operator list on above example
15
                'operator' => 'elike'
16
            )
17
        );
18
        $filter->add(array(
19
            'label' => 'Stock status',
20
            'value' => 'instock',
21
            'default' => 'instock'
22
        ));
23
        $filter->selectByOptions($options);
24
        wd_asp()->front_filters->add($filter);
25
    }
26
}
Copied!
Date type custom field filter
1
// --------------------------------
2
// Date filter example
3
// --------------------------------
4
add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
5
function asp_add_my_own_filters($search_id, $options) {
6
    if ( $search_id == 1 ) {
7
        $filter = wd_asp()->front_filters->create(
8
            'custom_field',
9
            'Date test',
10
            'datepicker',
11
            array(
12
                'field' => '_date',
13
                'placeholder' => '',
14
                // The display date format
15
                'date_format' => 'dd/mm/yy',
16
                /**
17
                 * Date storage format (how the field contains the date)
18
                 *  datetime  => standard datetime format, ex.: 2001-03-10 17:16:18
19
                 *  timestamp => timestamp format, ex.: 1561971794
20
                 *  acf       => custom ACF format (YYYYMMDD): 20191231
21
                'date_store_format' => 'datetime'
22
            )
23
        );
24
        $filter->add(array(
25
            'label' => 'Date test',
26
            /**
27
             * Static values
28
             * '31/07/2019' => use this format only, DD/MM/YYYY
29
             * Relative values
30
             * ''         => no value displayed
31
             * '+0'       => current date
32
             * '+3m +4d'  => 3 months and 4 days from now
33
             * '-2m -10d' => 2 months and 10 days before now
34
            'value' => '',
35
            'default' => ''
36
        ));
37
        $filter->selectByOptions($options);
38
        wd_asp()->front_filters->add($filter);
39
    }
40
}
Copied!
Slider and Range slider custom field filter
1
// --------------------------------
2
// Slider filter example
3
// --------------------------------
4
add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
5
function asp_add_my_own_filters($search_id, $options) {
6
    if ( $search_id == 1 ) {
7
        $filter = wd_asp()->front_filters->create(
8
            'custom_field',
9
            'Price slider <=',
10
            'slider',
11
            array(
12
                'field' => '_price',
13
                'slider_prefix' => '-,',
14
                'slider_suffix' => '.',
15
                'slider_step' => 1,
16
                'slider_from' => 1,
17
                'slider_to'   => 1200,
18
                'slider_decimals' => 0,
19
                'slider_t_separator' => ' ',
20
                /**
21
                 * Operators list:
22
                 * eq   => equals '='
23
                 * neq  => not equal '<>'
24
                 * lt   => less '<'
25
                 * let  => less or equals '<='
26
                 * gt   => greater '>'
27
                 * get  => greater or equals '>='
28
                 */
29
                'operator' => 'let'
30
            )
31
        );
32
        $filter->add(array(
33
            'value' => 300,
34
            'default' => 300
35
        ));
36
        $filter->selectByOptions($options);
37
        wd_asp()->front_filters->add($filter);
38
    }
39
}
40
​
41
// --------------------------------
42
// Range slider filter example
43
// --------------------------------
44
add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
45
function asp_add_my_own_filters($search_id, $options) {
46
    if ( $search_id == 1 ) {
47
        $filter = wd_asp()->front_filters->create(
48
            'custom_field',
49
            'Price range filter',
50
            'range',
51
            array(
52
                'field' => '_price',
53
                'range_prefix' => '-,',
54
                'range_suffix' => '.',
55
                'range_step' => 1,
56
                'range_from' => 1,
57
                'range_to'   => 1200,
58
                'range_decimals' => 0,
59
                'range_t_separator' => ' '
60
            )
61
        );
62
        $filter->add(array(
63
            'label' => 'Clothing',
64
            'value' => array(20, 1180),
65
            'default' => array(20, 1180)
66
        ));
67
        $filter->selectByOptions($options);
68
        wd_asp()->front_filters->add($filter);
69
    }
70
}
Copied!
​
How to automatically check/select filter values based on the archive page?
Next - Tips & Miscellaneous
Tutorials
Last modified 1yr ago
Copy link
Contents
Changing filter values within a filter box
The WD_ASP_FrontFilters singleton class