Advanced Filtering Module

Advanced Filtering is a great looking and powerful faceted filtering solution for your site with instant page updates and a mobile slideout panel.

Overview

To implement advanced filtering you will be using the provided Joomla modules and WordPress widgets:

  • JReviews Listings Advanced Filtering
  • JReviews Reviews Advanced Filtering

These include settings for:

  • Standard filters - categories, listing types, user & editor ratings

  • Theme customizations - allows adding custom fields filters through shortcode tags

  • Mobile view settings for slideout panel

  • Live updates - to show results without reoloads on same page

    For a better user experience with the filtering module we also recommend enabling Ajax Pagination in the Configuration → Theme & Navigation tab.

Getting Started

  1. Publish to an existing position

    Find the module or widget you want to setup (listings filtering or reviews filtering) and publish it to an existing position.

    The only custom template positions where filters can be published when live updates enabled are jr-review-filters and jr-listpage-below-pagetitle. Use the first one for review filtering in the listing detail pages. The second one shows in list pages and can be used for listings filtering. You can also use any Joomla template position or WordPress theme widget position that's available to you.

  2. Adjust basic display and filter settings

    Toggle the standard filters you'd like to use, and make other basic display changes. We recommend making the least amount of changes when first trying this out. You can always fine-tune them later.

  3. Add custom field filters

    The easiest way to start using the filter shortcode tags is through the THEME CUSTOMIZATION setting. Toggle Enable Module Theme to enable it, then use the textarea below it to add the filter shortcodes.

    You can choose one of your custom fields and use the most basic shortcode format:

    [filter name="jr_state"]

  4. Menu & page assignment

    Create a JReviews Advanced Search menu if you don't already have one. When someone first uses Advanced Filtering they will be taken to the advanced results page and this is the only way to ensure that users can continue using the filters there.

    In Joomla, the module assignment needs to include this page.

This should give working filters in the front-end and a taste of what you can do with them. There's a lot more, so do continue reading the next sections and learn about using shortcodes attributes to get the most of your filters.

Standard Fields

Standard filter fields that can be quickly toggled via settings include:

  • Categories
  • Listing Types
  • Keywords
  • User Rating
  • Editor Rating

If you need to show standard fields in a specific order, or want to use the available attributes to customzize the display options, you can disable them, and use the shortcode syntax.

[filter name="categories" label="Categories" display_as="link" split_list="0"]

[filter name="listing_types" label="Listing Types" display_as="link" split_list="1"]

[filter name="keywords" label="Keywords"]

[filter name="rating" type="user" label="User Rating"]

[filter name="rating" type="editor" label="Editor Rating"]

Custom Fields

Create filters for custom fields by adding the custom field name to the name attribute:

[filter name="jr_state"]

Shortcode attributes allow you to customize the label and other display options:

[filter name="jr_state" label="State" display_as="link" show_all="1" option_search="1"]

Author Field

To include a listing author filter use author for the name attribute. For this filter to work, listing owner searches must also be enabled in Configuration → Search → Allow searching by listing owner setting.

[filter name="author" label="Author"]

Basic Filters & Autodetect

Different combinations of settings will result in slightly different behavior of the filters:

  • Auto-detect enabled

    Auto-detect filters results based on the current page and this works will in category and detail pages. For directory pages it would filter by directory initially.

    When enabling auto-detect, disable the category and listing type filters.

  • Auto-detect disabled, basic filters used, category and listing type lists hidden

    The basic filters are added as hidden inputs. They are checked in this order: category, listing type, directory and only the first one that is not empty is used for filtering.

  • Auto-detect disabled, basic filters used, category or listing type lists shown

    Automatically limits options shown in the category and listing type lists based on the selected values in basic filters.

  • To limit category list options, use the directory and category filters

  • To limit listing type list options, use the listing type filter

    It's difficult to limit categories based on listing type because there can be many top level categories without a listing type.

  • Category and listing type filters should not be used together because selecting a listing type will not change the values of the category list.

Shortcode Attributes

Attribute Description Values Default value
name Name of the custom field - required attribute i.e. jr_address
label Title of the filter. Set to 0 to hide the label 0, text The custom field title
placeholder Placeholder text, used only for text inputs any custom text
display_as How the field will be displayed checkbox, select, link or linkboxed checkbox
auto_open Automatically toggles open the filter on page load to display the input or search options 0 or 1 0
show_cat The filter will be displayed only if specified categories are detected Comma separated list of category IDs
show_dir The filter will be displayed only if specified directories are detected Comma separated list of directory IDs
show_listing_type The filter will be displayed only if specified listing types are detected Comma separated list of listing type IDs
hide_cat The filter will be hidden when the specified categories are detected Comma separated list of category IDs
hide_dir The filter will be hidden when the specified directories are detected Comma separated list of directory IDs
hide_listing_type The filter will be hidden when the specified listing types are detected Comma separated list of listing type IDs
match_type Specifies the default query type for multiple select and checkbox custom fields all, any all
match_switch Enables the toggle switch for the match type for multiple select and checkbox custom fields 0 or 1 1
split_list Selected filter options are moved to the top of the list. 0 or 1 1
split_option_limit The split_list feature will only become active if the number of options for the field is higher than the specified limit. integer 10
show_all Limits the number of options shown in a checkbox or link list with a 'Show all' link at the bottom to expand the list 0 or 1 0
show_limit Sets the number of options shown when the show_all attribute is enabled integer 5
option_dialog When clicking the 'show all' link additional options are shown in a dialog, instead of inline 0 or 1 1
option_search Enables a search input within the individual checkbox, link, category, listing type filter 0 or 1 0
width Allows specifying a fixed width in pixels for an input in horizontal filtering integer na
preview Shows a preview of the selected options below the filter title, even when the filter is closed 0 or 1 1
slideout Enables the slide effect for the filter when the label is clicked 0 or 1 1
reset Adds a 'clear' link above the filter input to allow for quickly resetting all selected values for that filter 0 or 1 0
radius_min Minimum radius for proximity filter. Only works on the proximity search field. integer 10
radius_max Maximum radius for proximity filter. Only works on the proximity search field. integer 50
radius_step Radius step for proximity filter slider. Only works on the proximity search field. integer 10
radius_default Default radius for proximity filter. Only works on the proximity search field. integer 10

Grouping Shortcodes

A filtergroup shortcode can be used to group individual filters. This is convenience method that allows applying conditional display attributes so it's not necessary to do it for each field. For example, it's possible to group together all restaurant filters and use the show_listing_type attribute to show them only when a restaurant listing type is detected:

[filtergroup name="Restaurants" show_listing_type="3"]

	[filter name="jr_cuisine" label="Cuisine" display_as="checkbox"]

	[filter name="jr_mealsserved" label="Meals Served"]

	[filter name="jr_restaurantpricerange" label="Price Range" display_as="linkboxed"]

[/filtergroup]

Reset Filter Values

Enable the Clear all link setting if you want to provide a quick way to reset all filter selections. You can also add the feature to the theme using the reset shortcode:

[reset]

To customize the text, use the label attribute. It's also possible to convert the link to a button with the display_as attribute:

[reset label="Clear filter values" display_as="button"]

If you have a category or listing type list in the form these will not be cleared because they are necessary to maintain the context for the site visitor.

Mobile Slideout Panel

In mobile devices the filters output is hidden and a Filters button is shown in the list page header to trigger a slideout panel with the filters.

Use the settings to choose when to convert the regular output into the slideout panel:

  • Convert to mobile view

    Select the breakpoint when to convert the module to slideout panel

  • Module container class

    Specify the CSS class used by the module container so it can be hidden in mobile view. In other words, when the screen meets the mobile size requirements, we want to hide the module and to do that we need to know the class of the parent container for that module. For example, on our iReview template the module HTML markup looks like this:

    <div class="moduleid-192 mod-container clearfix">
    <div class="mod-inner ">
        <h3 class="mod-title">Advanced Filtering</h3>
            <div class="mod-content"><div class="jr-page jrPage jr-filters-module jrFiltersModule jrForm">

    So we use the mod-container class by default.

  • Module title class

    Specify the CSS class used by the module title so it can be shown in the slideout panel. Similar to the previous setting, we use this setting to copy the module title to the mobile filtering panel. In our iReview template the module title class is '''mod-title''' so we use that as the default.

Vertical & Horizontal Layouts

It's possible to change the layout of filters from vertical to horizontal via settings. The vertical layout is most useful when showing the filters in a sidebar.

Range Slider Add-on

The Range Slider Add-on converts numeric custom field inputs into a slider inteface in advanced filter forms. It allows setting up any number of fields with different display options.

Range Slider configuration options
Range Slider configuration options

It's a free add-on that can be installed directly through the JReviews App Store.

Limitations

Custom fields inside a controlled field group cannot be used as filters. For example, if you have a field group in the field groups manager that is controlled by one or more field options, any custom fields inside that field group cannot be used as Filters.

Example Template

Below is an extended example you can use as reference. We are using a version of this on our demo site. Using filter groups and using display conditionals show_dir and show_listing_type allows having using a single module/widget throughout the site with dynamic output that changes the filters shown depending on the page in which it's being displayed.

<!-- Places -->

[filter label="Proximity search" name="jr_address" placeholder="City, address, postal code" show_dir="2,10" radius_min="10" radius_max="100" radius_step="5" radius_default="30"]

[filter name="jr_state" label="" display_as="checkbox" show_dir="2,10"]

[filter name="jr_city" label="City" display_as="checkbox" show_dir="2,10"]

<!-- Businesses -->

[filter name="jr_services" label="" show_listing_type="1" show_cat="91"]

<!-- Hotels -->

[filtergroup name="Hotels" show_listing_type="2"]

	[filter name="jr_hotelamenities" display_as="checkbox"]

	[filter name="jr_hotelpricerange" display_as="linkboxed"]

[/filtergroup]

<!-- Restaurants -->

[filtergroup name="Restaurants" show_listing_type="3"]

	[filter name="jr_cuisine" label="Cuisine" display_as="checkbox"]

	[filter name="jr_mealsserved" label=""]

	[filter name="jr_restaurantpricerange" label=""]

[/filtergroup]

<!-- Bars -->

[filtergroup name="Bars" show_listing_type="4"]

	[filter name="jr_drinkoffering" label=""]

	[filter name="jr_barmusic" label=""]

	[filter name="jr_outdoorseating" label="Outdoor Seating"]

[/filtergroup]

<!-- Products -->

[filtergroup name="Products" show_listing_type="8" show_dir="3"]

	[filter name="jr_productprice" label="Price"]

	[filter name="jr_brand" label="Brand" display_as="checkbox"]

[/filtergroup]

<!-- Movies -->

[filtergroup name="Movies" show_dir="5"]

	[filter name="jr_directedby" label="Director"]

	[filter name="jr_writtenby" label="Writer"]

	[filter name="jr_actors" label="Actors"]

	[filter name="jr_year" label="Year"]

	[filter name="jr_mpaarating" label="MPAA Rating" display_as="linkboxed"]

[/filtergroup]

<!-- Games -->

[filtergroup name="Games" show_dir="6"]

	[filter name="jr_publishedby" label="Publisher"]

	[filter name="jr_gamegenre" label="Genre"]

	[filter name="jr_gamereleasedate" label="Release Year"]

[/filtergroup]

<!-- Real Estate -->

[filtergroup name="Real Estate" show_listing_type="13" show_cat="61"]

	[filter name="jr_realestateprice"]

	[filter name="jr_rooms"]

	[filter name="jr_bathrooms"]

[/filtergroup]

<!-- Events -->

[filtergroup name="Events" show_dir="10"]

	[filter name="jr_venue" placeholder="Venue name"]

	[filter name="jr_eventdate"]

[/filtergroup]

<!-- Cars -->

[filtergroup name="Cars" show_listing_type="14" show_cat="65"]

	[filter name="jr_carprice"]

	[filter name="jr_carmake"]

	[filter name="jr_carmodel"]

	[filter name="jr_caryear"]

[/filtergroup]

<!-- Recipes -->

[filtergroup name="Recipes" show_dir="12"]

	[filter name="jr_recipetags"]

	[filter name="jr_servings"]

	[filter name="jr_totaltime"]

[/filtergroup]

<!-- Software -->

[filtergroup name="Software" show_dir="8"]

	[filter name="jr_developer"]

	[filter name="jr_os"]

[/filtergroup]

Customizations

If template customizations is your thing, then shortcode tags can also be added directly to the module/widget template file. Just copy the module/widget template to your custom theme, and consider using a theme suffix if you want to have different filtering forms.

Joomla

templates/
`-- jreviews_overrides/
    `-- views/
        `-- themes/
            `-- mysite/
                `-- modules
                    `-- filters.thtml

WordPress

jreviews_overrides/
`-- views/
    `-- themes/
        `-- mysite/
            `-- modules
                `-- filters.thtml

For the review filters, use reviews_filters.thtml instead of filters.thtml which is used for listings filters.