Filters

Developer documentation for the Ajax Load More Filters add-on.


Filter Hooks

The following filter hooks are available when using this add-on:

alm_filters_{id}_{key}

This filters provides developers a method of customizing the returned filter selections of a specific filter by key.

  • id: The unique filter ID
  • key: The target query parameter
    When filtering by custom field or taxonomy, the key parameter must be the meta_key or taxonomy slug value.
The code snippet above returns custom filter values ordered by name in ascending order for the category query of the blog filter.

Note: When using this filter you must return both a label and value in the array.

alm_filters_{id}_{key}_title

This filter will set the title text of a specific filter block.

  • id: The unique filter ID
  • key: The target query parameter
    When filtering by custom field or taxonomy, the key parameter must be the meta_key or taxonomy slug value.
The code snippet above will set Categories as the title text for the category filter group.

Note: This filter is useful on multilingual sites built with WPML or Polylang where titles are required to be localized across languages. 

alm_filters_{id}_{key}_default

This filter will set a default fallback value for a filter block.

  • id: The unique filter ID
  • key: The target query parameter
    When filtering by custom field or taxonomy, the key parameter must be the meta_key or taxonomy slug value.
The code snippet above will set work and post as fallback post_type value when zero items are selected.

Note: Return values in this hook should (in most cases) directly relate to values already set in the core Ajax Load More shortcode.

alm_filters_{id}_{key}_selected

This filter will set a default pre-selected value for a filter block and is available for the radio, checkbox and select field types only.

  • id: The unique filter ID.
  • key: The target query parameter (key).
    When filtering by custom field or taxonomy, the key parameter must be the meta_key or taxonomy slug value.
The code snippet above will set design as the pre-selected category value of the portfolio filter group.

Note: When using this filter you must also set this value in your core Ajax Load More shortcode.

alm_filters_select_class

Adds custom classes to select element wrappers. This is useful for users who are using select replacement techniques.

alm_filters_button_text

Set a default value of submit button label.

alm_filters_title_element

Update the default HTML of each filter title element.

alm_filters_edit

Disable the filter edit button for logged in (admin) users.


Term Ordering

By default, taxonomy terms and author filters are returned and displayed in alphabetical order.

Use the following filter hooks to modify the arguments ( order, orderby, hide_empty etc.) of an author, category, tag or taxonomy term listing query.

Author: alm_filters_{id}_author_args

This filter will adjust the arguments of an author query.

  • id: The unique filter ID
The code snippet above will order an author filter listing by login in ascending order.

Note: The author query uses the WordPress core get_users function – all accepted arguments can be used in this filter.

Category: alm_filters_{id}_category_args

This filter will adjust the arguments of a category query.

  • id: The unique filter ID

The following snippet will order a category filter listing by count in ascending order and render empty categories.

Note: The category query uses the core WordPress function get_terms – all accepted arguments can be used in this filter.

Tag: alm_filters_{id}_tag_args

This filter will adjust the arguments of a tag query.

  • id: The unique filter ID
The code snippet above will order a tag filter listing in ascending order.

Note: The tag query uses the core WordPress function get_terms – all accepted arguments can be used in this filter.

Taxonomy: alm_filters_{id}_{key}_args

This filter will adjust the arguments of a custom taxonomy query.

  • id: The unique filter ID
  • key: The target query parameter
    When filtering by taxonomy, the key parameter must be the taxonomy slug value.
The code snippet above will order the actor taxonomy term listing in ascending order by URL slug.

Note: The taxonomy query uses the core WordPress function get_terms – all accepted arguments can be used in this filter.


Callback Functions

Each Javascript callback function is dispatched directly from core Ajax Load More Filters and allow you to trigger custom functions based on events during the filter process – to utilize the following callback functions, copy and paste a code example below into your sites JavaScript file.

almFiltersActive

The almFiltersActive() function is dispatched after a filter submit action and returns an object containing the key/value pair combinations of active filters.

almFiltersChange()

The almFiltersChange() function is dispatched when a filter change event is triggered.

almFiltersComplete()

The almFiltersComplete() function is dispatched after the filter process has completed.

almFiltersURLUpdate()

The almFiltersURLUpdate() function is dispatched after the browser URL has been updated.


Public JavaScript Functions

The following JavaScript functions are available when using this add-on:

almfilters.start()

The almfilters.start() function will initiate an Ajax Load More filter instance.

Note: start() is useful if filters have been loaded via Ajax or another non server-side render method.

almfilters.reset()

The almfilters.reset() function will clear and reset an entire Ajax Load More filter instance.

almfilters.resetFilter()

The almfilters.resetFilter() function will clear and reset a specific filter group.

Note: resetFilter is useful if you want to clear a specific filter while performing a specific task.


FAQs

Below are common questions regarding the Filters add-on. If you have a question and don’t see an answer here, please visit the support page and submit your request.

What form field types are currently supported?

Filters can be rendered to screen using any of the following form element styles:

  • Checkbox
  • Radio
  • Select & Multi-Select
  • Text Input
  • Date Picker

What type of content can I build filters for?

You can create filters based on any of the following WordPress query parameters:

  • Post Type
  • Category
  • Tags
  • Taxonomy
  • Ordering (order, orderby, sort)
  • Search
  • Custom Fields (Meta Query)
  • Authors
  • Date (year, month, day)

Note: Each supported query parameter directly relates to an Ajax Load More shortcode parameter.

How are filters saved in the WordPress admin?

When a filter is saved or modified it is stored as an option in the WordPress Options table.

Can a deleted filter be recovered?

No, once a filter has been deleted it is gone for good.

Select2 change events are not working on select elements, how can I fix this?

If you are using Select2 on elements inside filters you will need to manually dispatch change events so the Filters add-on can respond to the event.

How can I adjust the order of terms returned with Filters?

To adjust the order of terms you can use the available ordering hooks or create your own term listing using the alm_filters{id}_{key} hook.


« Back to Add-ons