Frontend filters API
API for adding/modifying and removing front-end plugin filter boxes
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:
add_filter('asp_pre_get_front_filters', 'asp_change_a_filter', 10, 2);
function asp_change_a_filter($filters, $type) {
foreach ($filters as $k => &$filter) {
// To check some of the attributes:
// $filter->label
// $filter->display_mode
// $filter->position
// $filter->id
// $filter->type() >> returns the filter type
// $filter->field() >> field that is filtered (if applicable)
// do a var_dump($filter->data) -> to see the filter data
// Go through the filter items via a loop
foreach ($filter->get() as $kk => $item) {
// Changing a filter attribute: label, selected, value, default by array ID
$filter->attr($kk, 'label', 'New Label', true);
// Remove the current item by array ID
$filter->remove($kk, true);
}
// You can also change/remove items by key, without a loop
// ..for a category/term filter, use the term ID
$filter->attr(123, 'label', 'New Label');
$filter->remove(123);
// ..for a custom field filter, use the field value
$filter->attr('value', 'label', 'New Label');
$filter->remove('value');
// Remove values from a custom field filter
if ( $filter->type() == 'custom_field' && $filter->field() == 'my_field' ) {
$filter->remove(array('value1', 'value2'));
}
// Adding a new value to a custom field filter
if ( $filter->type() == 'custom_field' && $filter->field() == 'my_field' ) {
$filter->add(array(
'label' => 'Value label 1',
'selected' => false,
'value' => 'value1'
));
// The second function argument allows setting the value position
// Adding a value after the 2nd option
$filter->add(array(
'label' => 'Value label 2',
'selected' => false,
'value' => 'value2'
), 2);
// Adding a value to before the last option
$filter->add(array(
'label' => 'Value label 3',
'selected' => false,
'value' => 'value3'
), -1);
}
}
return $filters;
}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);
}
}Dropdown, checkbox and radio type custom field filters
// --------------------------------
// 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',
// allow match if this custom field is unset
)
);
$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);
}
}Last updated