Front-end filters API

API for adding/modifying and removing front-end plugin filter boxes

This section is intended for advanced users/developers. Before making any changes to any of your site files, please make sure to always have a back-up, just in case.

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..

wd_asp()->front_filters

..variable, or if you prefer your own, then:

$my_variable = WD_ASP_FrontFilters::getInstance();

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:

add_action('asp_post_parse_filters', 'asp_change_the_filters', 10, 2);
function asp_change_the_filters($search_id, $options) {
if ( $search_id == 1 ) {
// Change filter position to 1
wd_asp()->front_filters->set("Test drop", 'position', 1);
// Change filter label
wd_asp()->front_filters->set("Test drop", 'label', 'My test drop');
// Remove a filter by label
wd_asp()->front_filters->remove("Filter by Product categories");
}
}

Example of adding a custom taxonomy filter:

add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
function asp_add_my_own_filters($search_id, $options) {
if ( $search_id == 1 ) {
// Creating a new filter
$filter = wd_asp()->front_filters->create(
'taxonomy',
'My Taxonomy Filter',
'dropdown',
array(
'taxonomy' => 'category'
)
);
// Adding the select all option first
$filter->add(array(
'id' => 0,
'label' => 'Select all',
'default' => true,
'selected' => true
));
// Getting the terms to add
$terms = get_terms("category", array(
'hide_empty' => false,
'fields' => 'id=>name'
));
foreach( $terms as $id => $name ) {
// Add each taxonomy terms one by one
$filter->add(array(
'id' => $id,
'label' => $name,
'taxonomy' => 'category',
'default' => false,
'selected' => false
));
}
/**
* Make sure to change the filter options, if there was a
* redirection to the results page.
**/
$filter->selectByOptions($options);
/**
* Optionally, you can change the filter position as well, via:
* $filter->position = 1;
**/
// Finally, append the filter
wd_asp()->front_filters->add($filter);
}
}

For methods list and examples, please check below.

Methods list

create()

create(string $type, string $label = '', string $display_mode = '', array $data = array())

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()

add( aspFilter $filter )

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()

set( int|string $key, string $attribute, mixed $value )

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()

get( string $order = 'position', $type = false )

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()

remove( int|string $key )

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.

add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
function asp_add_my_own_filters($search_id, $options) {
if ( $search_id == 1 ) {
$filter = wd_asp()->front_filters->create(
'taxonomy', // Filter type
'My Product cat filter', // Filter box label
'checkboxes', // Display mode: checkboxes, dropdown, dropdownsearch, multisearch, radio
array(
'taxonomy' => 'category',
// allowing CPT results that does not match the terms from this taxonomy
'allow_empty' => false,
'logic' => 'or' // or, and
)
);
// The select all must have the ID = 0
$filter->add(array(
'id' => 0,
'label' => 'Select All',
'default' => true,
'selected' => true
));
$filter->add(array(
'id' => 81,
'label' => 'Clothing',
'taxonomy' => 'category',
'default' => true,
'selected' => true
));
$filter->add(array(
'id' => 84,
'label' => 'Posters',
'taxonomy' => 'category',
'default' => true,
'selected' => true
));
/**
Another variation, by adding all categories
$terms = get_terms("category", array(
'hide_empty' => false,
'fields' => 'id=>name'
));
foreach( $terms as $id => $name ) {
$filter->add(array(
'id' => $id,
'label' => $name,
'taxonomy' => 'category',
'default' => false,
'selected' => false
));
}
*/
$filter->selectByOptions($options);
wd_asp()->front_filters->add($filter);
}
}
// --------------------------------
// Drop down filter example - for WooCoomerce stock status
// --------------------------------
add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
function asp_add_my_own_filters($search_id, $options) {
if ( $search_id == 1 ) {
// Dropdown
$filter = wd_asp()->front_filters->create(
'custom_field',
'Dropdown stock test',
// Type: dropdown, dropdownsearch, multisearch or radio
'dropdown',
array(
'field' => '_stock_status',
/**
* Operators list:
* String
* like => string matching anywhere
* elike => string matching exactly
* Numeric
* eq => equals '='
* neq => not equal '<>'
* lt => less '<'
* let => less or equals '<='
* gt => greater '>'
* get => greater or equals '>='
*/
'operator' => 'like',
// only applies on 'dropdown' type (multiselect for dropdown)
'multiple' => true,
// or or and, only applies for 'multisearch' or 'dropdown' + multiple
'logic' => 'or'
)
);
$filter->add(array(
'label' => 'Any stock (empty val)',
'value' => '',
'selected' => true,
'default' => true
));
$filter->add(array(
'label' => 'Any stock (multi val)',
'value' => 'instock::outofstock',
'selected' => true,
'default' => true
));
$filter->add(array(
'label' => 'In Stock',
'value' => 'instock',
'selected' => true,
'default' => true
));
$filter->add(array(
'label' => 'Out of Stock',
'value' => 'outofstock',
'selected' => false,
'default' => false
));
$filter->selectByOptions($options);
wd_asp()->front_filters->add($filter);
}
}

Text and hidden type custom field filters

// --------------------------------
// Text or hidden filter example
// --------------------------------
add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
function asp_add_my_own_filters($search_id, $options) {
if ( $search_id == 1 ) {
$filter = wd_asp()->front_filters->create(
'custom_field',
'Text stock',
// text or hidden
'text',
array(
'field' => '_stock_status',
// See operator list on above example
'operator' => 'elike'
)
);
$filter->add(array(
'label' => 'Stock status',
'value' => 'instock',
'default' => 'instock'
));
$filter->selectByOptions($options);
wd_asp()->front_filters->add($filter);
}
}

Date type custom field filter

// --------------------------------
// Date filter example
// --------------------------------
add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
function asp_add_my_own_filters($search_id, $options) {
if ( $search_id == 1 ) {
$filter = wd_asp()->front_filters->create(
'custom_field',
'Date test',
'datepicker',
array(
'field' => '_date',
'placeholder' => '',
// The display date format
'date_format' => 'dd/mm/yy',
/**
* Date storage format (how the field contains the date)
* datetime => standard datetime format, ex.: 2001-03-10 17:16:18
* timestamp => timestamp format, ex.: 1561971794
* acf => custom ACF format (YYYYMMDD): 20191231
'date_store_format' => 'datetime'
)
);
$filter->add(array(
'label' => 'Date test',
/**
* Static values
* '31/07/2019' => use this format only, DD/MM/YYYY
* Relative values
* '' => no value displayed
* '+0' => current date
* '+3m +4d' => 3 months and 4 days from now
* '-2m -10d' => 2 months and 10 days before now
'value' => '',
'default' => ''
));
$filter->selectByOptions($options);
wd_asp()->front_filters->add($filter);
}
}

Slider and Range slider custom field filter

// --------------------------------
// Slider filter example
// --------------------------------
add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
function asp_add_my_own_filters($search_id, $options) {
if ( $search_id == 1 ) {
$filter = wd_asp()->front_filters->create(
'custom_field',
'Price slider <=',
'slider',
array(
'field' => '_price',
'slider_prefix' => '-,',
'slider_suffix' => '.',
'slider_step' => 1,
'slider_from' => 1,
'slider_to' => 1200,
'slider_decimals' => 0,
'slider_t_separator' => ' ',
/**
* Operators list:
* eq => equals '='
* neq => not equal '<>'
* lt => less '<'
* let => less or equals '<='
* gt => greater '>'
* get => greater or equals '>='
*/
'operator' => 'let'
)
);
$filter->add(array(
'value' => 300,
'default' => 300
));
$filter->selectByOptions($options);
wd_asp()->front_filters->add($filter);
}
}
// --------------------------------
// Range slider filter example
// --------------------------------
add_action('asp_pre_parse_filters', 'asp_add_my_own_filters', 10, 2);
function asp_add_my_own_filters($search_id, $options) {
if ( $search_id == 1 ) {
$filter = wd_asp()->front_filters->create(
'custom_field',
'Price range filter',
'range',
array(
'field' => '_price',
'range_prefix' => '-,',
'range_suffix' => '.',
'range_step' => 1,
'range_from' => 1,
'range_to' => 1200,
'range_decimals' => 0,
'range_t_separator' => ' '
)
);
$filter->add(array(
'label' => 'Clothing',
'value' => array(20, 1180),
'default' => array(20, 1180)
));
$filter->selectByOptions($options);
wd_asp()->front_filters->add($filter);
}
}