PHP Hooks
The PHP hooks are implemented using the standard WordPress functionality of apply_filters. This allows different priorities to be set for the filters. Therefore it’s possible to override the internal handlers if any.
All hooks start with acsell_pf – i.e. Acsell Product Filters.
The word hook is used to avoid confusion with the product name and function.
Filter Settings
Override filtering – acsell_pf_filtering_enabled
The plugin uses its own logic to determine if filtering is enabled for a page. This includes WooCommerce settings for whether products or sub-categories are displayed, as well as the settings in Filters for Pages.
This hook can be used to enable or disable the Acsell Product Filters on any page. The parameter is the plugin’s determination of whether filtering is enabled. Return boolean true to enable or false to disable the filter.
/**
* Determines if filtering is enabled on the page.
*
* This can override WooCommerce sub-section only display or setting of “None” via admin interface
*
* @param boolean $filtering_enabled
*/
$filtering_enabled = apply_filters( ‘acsell_pf_filtering_enabled’, $filtering_enabled );
Note that the plugin code handles the hook acsell_pf_is_filtering_enabled_for_page which can be used from theme compatibility files to determine if filtering is enabled. For example, this is used within the internal Woodmart theme compatibility file to determine if the pagination setting should be overridden:
// Set the woodmart to use pagination to avoid infinit scroll
add_filter( 'option_xts-woodmart-options', array( $this, 'woodmart_pagination_fix' ) );
/**
* Filter woodmart theme shop pagination option.
*
* @param array $value current woodmart options.
*
* @return array $value updated woodmart options.
*/
public function woodmart_pagination_fix( $value ) {
$filtering_enabled = apply_filters('acsell_pf_is_filtering_enabled_for_page', false);
if ( $filtering_enabled ) {
$value['shop_pagination'] = 'pagination';
}
return $value;
}
Override Filter Set – acsell_pf_filter_group_id
If filtering is enabled for a page, the plugin has to determine the filters to use. In the UI this is called the Filter Set, and internally it is called a Filter Group with post type of filter_group.
This hook can be used to override the filter group on any page. The parameter is the current filter group post ID. Return a new value to change the filter group in use.
If the returned post ID is not of type filter_group then no filtering will be applied.
/**
* Override the filter group (AKA filter set) ID used for the page. Use 'none' or empty string for no filtering
*
* @param string $filter_id
*/
$filter_id = apply_filters( 'acsell_pf_filter_group_id', $filter_id );
Change filter set settings – acsell_pf_filter_group_data
When the settings for a filter set (group) have been loaded, this hook can be used to tweak them.
The parameter is the current group data, an array with a fixed set of keys. Inspect the code in class Filter_Groups_Data to determine the keys.
/**
* Change the filter group settings.
*
* @param array $group_data
*/
$group_data = apply_filters( 'acsell_pf_filter_group_data', $group_data );
For example, to change the Clear All text in all pages, add this action in the child theme functions.php:
// tweak filters
add_action( 'acsell_pf_filter_group_data', 'acsell_pf_filter_group_data' );
function acsell_pf_filter_group_data( $group_data ) {
$group_data[ 'clear_all_text' ] = 'Reset';
return $group_data;
}
Component Settings – acsell_pf_filter_component_settings
Internally, a single Filter in a Filter Set/Group (e.g. brand, colour) is called a Filter Component.
This hook is called multiple times for each component of the current filter set. It allows the settings for the component to be adjusted e.g. to change the title or CSS. This also includes the HTML for the component so that could be edited.
/**
* Change the settings for this filter component
*
* @param array $components
*/
$components = apply_filters( 'acsell_pf_filter_component_settings', $components );
Filter Settings – acsell_pf_filter_settings
This hook is called after setting up each individual component, and includes some additional information for the Filter Set/Group.
/**
* Change the settings for this filter group (aka filter set)
*
* @param array $data
*/
$data = apply_filters( 'acsell_pf_filter_settings', $data );
Product Load Settings – acsell_pf_product_load_settings
This hook is used to intercept and modify the Product Load settings (from the Settings page). You may want to change it for specific pages.
/**
* Change the settings for loading products
*
* @param array $product_load_settings
*/
$this->page_settings = apply_filters( 'acsell_pf_product_load_settings', $product_load_settings );
Filter Data
The settings information is used along with a few other items to create the filter data embedded in the page HTML.
These hooks can be used to change the data.
Product List – acsell_pf_product_list
The Acsell Product Filters plugin piggy-backs on the main WP_query to determine the products that would be loaded in the page. The query clauses (WHERE, ORDER BY) are used to select the custom product information that is maintained in the acsell_product_data table.
This information is sent to the browser, and in addition is used for pre-calculating counts in the server. The order of products in the list is used to determine the order of products displayed in the page.
This hook can be used to change this product list. The information is highly technical so should only be modified if you know exactly what you are doing. However, the overall list of products could be changed e.g. if the list selected by the main WP_Query doesn’t match the products normally shown in the page.
/**
* Change the loaded product information used for server counting and placed into page for filtering
*
* @param array $product_list
*/
$product_list = apply_filters( 'acsell_pf_product_list', $product_list );
Note that $product_list is an array of arrays, being mutiple rows of product data. The first field in each row is the product ID. In version 1.0.3 the indexes are:
define( 'acsell_PRODUCT_index_ID', 0 );
define( 'acsell_PRODUCT_index_attributes', 1 );
define( 'acsell_PRODUCT_index_stock', 2 );
define( 'acsell_PRODUCT_index_on_sale', 3 );
define( 'acsell_PRODUCT_index_price', 4 );
define( 'acsell_PRODUCT_index_max_price', 5 );
define( 'acsell_PRODUCT_index_variations', 6 );
define( 'acsell_PRODUCT_index_product_version', 7 );
Show More button HTML – acsell_pf_product_load_more_html
This hook can be used to override the Show More button.
/**
* Change the HTML used for the load more button
*
* @param string $show_more_string - product load more HTML
*/
$show_more_string = apply_filters( 'acsell_pf_product_load_more_html', $show_more_string );
Placeholder Product HTML – acsell_pf_placeholder_product_html
This hook can be used to override the placeholder product HTML.
Typically this would be used to match the placeholder to the product display. It’s important to make the placeholders the same height as the normal products in a page as they can appear before as well as after the current visible product if returning to a page that had been scrolled.
/**
* Change the HTML used for placeholders
*
* @param string $placeholder_product_html
*/
$placeholder_product_html = apply_filters( 'acsell_pf_placeholder_product_html', $placeholder_product_html );
Products per row – wc_get_default_products_per_row
This hook can be used to change the number of products per row. This may be theme-specific. Note that some themes provide a facility to change this in the browser, and the JavaScript hooks allow that functionality to be provided in the plugin’s own display of products.
/**
* Get theme specific number of columns per row in grid
*
* Most of the themes use woocommerce settings wc_get_default_products_per_row() to set number of products per row
* But it can be varied based on theme settings.
*
* @param integer
*/
$per_row = apply_filters('acsell_pf_get_products_per_row', wc_get_default_products_per_row());
Filter Parameters embedded in page – acsell_pf_filter_params
This hook allows any of the parameters send to the browser JavaScript to be changed.
This includes details like the brackets used around the counts. This can be changed to any HTML allowing the counts to be highlighted etc.
Many of the values here can be tweaked using other hooks.
/**
* Get the filter parameters
*
* The filter parameters are embedded in the page. The values can be changed, or additional values can be inserted
*
* @param array $filter_params - default filter parameters
*/
$filter_params = apply_filters( 'acsell_pf_filter_params', array(...) );
Widget HTML
The widget HTML is passed through a hook for general purpose modification.
Note that two separate HTML blocks are generated depending on whether the browsing device is a mobile or not.
Mobile widget HTML – acsell_pf_mobile_widget_html
This hook is used to change the mobile widget HTML.
/**
* Update the mobile HTML for the widget
*
* @param string $html
*/
$html = apply_filters( 'acsell_pf_mobile_widget_html', $html );
Desktop Widget HTML – acsell_pf_desktop_widget_html
This hook is used to change the desktop widget HTML.
/**
* Update the desktop HTML for the widget
*
* @param string $html
*/
$html = apply_filters( 'acsell_pf_desktop_widget_html', $html );
Theme Settings
Internally within the plugin there are a number of theme compatibility files. The PHP files are loaded and used to override some of the functionality using some of the hooks documented here.
In addition, JavaScript and CSS files are loaded into the browser based on the current theme. The theme slug is used to select the appropriate file.
It’s possible that the theme you are using has not been tested, therefore no theme file will be loaded. In that case you will need to override the hooks both in the PHP and JS to ensure correct operation.
Include theme-specific JavaScript file – acsell_pf_include_theme_js_file
If you have customised a theme, the JS supplied by the plugin may not give optimal functionality. To avoid having to override the JS supplied by the plugin it’s possible to suppress the JS files completely.
Returning false from this hook will prevent the theme-specific JavaScript file being loaded. If you do this then you will have to ensure that the required theme functionality is provided elsewhere.
/**
* Include the theme-specific js file
*
* This contains default handlers for theme customisation, for the given theme.
* If not included, you will have to provide handlers for all JS events required for theme customisation.
*
* @returns boolean true to include the file
*/
$include_theme_js_file = apply_filters( 'acsell_pf_include_theme_js_file', true );
Include theme-specific CSS file – acsell_pf_include_theme_css_file’
If you have customised a theme, the CSS supplied by the plugin may not give optimal functionality. To avoid having to override the CSS supplied by the plugin it’s possible to suppress the CSS files completely.
Returning false from this hook will prevent the theme-specific JavaScript file being loaded. If you do this then you will have to ensure that the required theme functionality is provided elsewhere.
/**
* Include the theme-specific css file
*
* This contains default CSS for theme customisation, for the given theme.
* If not included you will have to provide CSS for theme customisation.
*
* @returns boolean true to include the file
*/
$include_theme_css_file = apply_filters( 'acsell_pf_include_theme_css_file', true );
Embed a custom ID in the page – acsell_pf_get_theme_setting_id
In some cases it may be necessary to put custom information in the page. This is used internally for at least one theme where individual pages can be set up differently. This numeric ID is requested with this filter, and is then sent back to the server when requesting product HTML.
/**
* Get the theme-specific ID
*
* This is stored in the data embedded in the page then sent back in the Ajax request for products.
* The filter acsell_pf_load_ajax_products_setup is called prior to loading products with this ID.
*
* @param integer 0 - default theme setting ID
*/
$theme_setting_id = apply_filters( 'acsell_pf_get_theme_setting_id', 0 );
Product HTML Loading
The HTML for products may be requested from the server.
Internally the plugin handles these calls by setting up a WP_query object and iterating through them, calling the standard product rendering. However, for some themes this may have to be overridden, or the initialisation of the loop changed. Hooks are provided for this.
Loop setup – acsell_pf_load_ajax_products_setup
Prior to starting the loop or querying the products, this hook is passed the theme setting ID embedded in the page, allowing appropriate initialisation of the theme.
/**
* Prepare for loading products via Ajax
*
* The parameter is the result of the call to acsell_pf_get_theme_setting_id when setting up the page.
*
* @param integer theme setting ID
*/
apply_filters( 'acsell_pf_load_ajax_products_setup', $theme_setting_id );
Query Arguments – acsell_pf_load_ajax_products_query_args
This hook can be used to change the query arguments. The default arguments include the product IDs passed from the browser JS.
/**
* Modify the query arguments for loading Ajax products
*
* The parameter is the default args.
*
* @param array $query_args query arguments
*/
$query_args = apply_filters( 'acsell_pf_load_ajax_products_query_args', $query_args );
Echo the Ajax Product HTML – acsell_pf_load_ajax_products
This hook is used if the internal product loop is inappropriate and has to be completely overriden. The product HTML should be echoed like the standard loop, and then die or exit called.
/**
* echo the products into the output.
*
* If using this hook it's necessary to die or exit when finished;
* otherwise the standard product loop is also called.
*
* @param array $query_args query arguments
*/
do_action('acsell_pf_load_ajax_products', $query_args);
Start the shop loop – acsell_pf_load_ajax_products_should_start_shop_loop
This hook controls whether the wc_set_loop_prop and wc_get_template functions are called when starting the product loop. The full code is given below.
/**
* Whether the shop look should be started or not
*
* Required for some themes
*
* @param boolean whether to start the loop, default false
*/
if ( apply_filters( 'acsell_pf_load_ajax_products_should_start_shop_loop', false ) ) {
ob_start();
wc_set_loop_prop( 'loop', 0 );
wc_get_template( 'loop/loop-start.php' );
ob_clean();
}