Create a Facet

IntroductionIntroduction

A facet allows you to filter, load, sort, or reset content. A facet is always attached to a grid, template, or third-party content because a page/post can contain several filterable contents. It can be rendered on a page without the presence of a grid. In this guide, we will detail all settings available for facets.

Facet ActionFacet Action

At first you need to select which kind of action your facet will apply on your grid:

  • Filter Content: Refine displayed content by selecting specific criteria like categories or tags.
  • Sort Content: Arrange content by criteria such as date or price for easier navigation.
  • Load Content: Dynamically load content without refreshing the page.
  • Reset Filters: Revert the content to its default state, clearing applied filters.
  • Apply Filters: Apply filters by clicking a submit button or redirecting to a filtered page.
Facet Settings - Action
Facet – Action

Filter FacetFilter Facet

Data SourceData Source

If you set Filter Content as Facet Action, you need to set the Data Source of your filter. It means that you need to set which kind of data from WordPress will be used to filter your grid content. You can filter by:

  • Taxonomy terms (categories, tags, product attributes, etc.)
  • WordPress field (title, date, author, etc.)
  • Custom field
Facet - Data source
Facet – Data source

First of all, you need to set the Content Type to Filter. This is the content type used for the grid or query of the third-party content to be filtered. If you’re querying and displaying Posts in the content to be filtered, select Posts; likewise, this applies for Terms and Users.

After selecting the content type to filter, you can choose the specific criteria for filtering. Depending on the content type selected, various options become available, such as filtering by taxonomies (categories, tags, etc.), WordPress fields (title, author, date, etc.), or custom fields.

OptionDescription
Content Type to FilterType of content used for the grid query/content to be filtered
Filter Content ByData used to filter content (WordPress field, taxonomy or custom field)
Include TermsSpecify terms to retrieve
Exclude TermsSpecify terms not to retrieve
Term DepthDepth level of terms to be retrieves
Child OfParent term to retrieve child terms of
Parent TermParent term to retrieve direct-child terms of
Include ChoicesSpecify choices to retrieve
Exlude ChoicesSpecify Choices not to retrieve

Order & NumberOrder & Number

In this section, you can configure the order and number of choices displayed in the facet.

Facet - Order & Number
Facet – Order & Number

You can order choices in the facet depending on several factors:

  • Choice Count: Number of matching posts, terms or users
  • Choice Name: Name / label of the choice displayed in the facet
  • Choice Value: Value used in URL parameters
  • Term Order: Custom order set to a taxonomy term

You can use a plugin to order terms as you wish and use this order in the facet. Once terms have been ordered, you need to re-index the facet to reflect the changes.

Depending on the filter type, you also have the option to limit the number of choices shown initially using the Limit Choices Number setting. If Limit Choices Number is less than the number of choices you have defined, a toggle button will appear at the bottom of the facet. This button allows users to show more or fewer choices with a single click

OptionDescription
Order ByDisplay order of choices in the facet
OrderAscending or descending order of the order by parameter
NumberTotal number of choices to display in the facet
Limit Choices NumberDisplay a toggle button if the limit is lower than the Number option
Expand Button LabelButton label used for expand state
Collapse Button LabelButton label used for collapse state

CheckboxCheckbox

Checkbox Facet
Checkbox Facet

The checkbox facet enables users to filter content using predefined options represented by checkboxes. Users can select multiple checkboxes, applying either AND or OR logic between their choices. AND logic displays content that satisfies all selected checkboxes, while OR logic shows content matching any of the selected checkboxes.

OptionDescription
Logic Between ChoicesApply AND or OR logic between selected choices
Show Empty ChoicesShow choices that match no results when filtered
Show Choice CountShow the number of results matching each choice
Show Current TermsShow current archive page terms (taxonomy only)
Show ChildrenShow child terms of the selected taxonomy (taxonomy only)
HierarchicalDisplay taxonomy terms in hierarchical list (taxonomy only)
Navigation TreeviewDisplay toggle buttons on parent terms to reveal/hide children

RadioRadio

Radio Facet
Radio Facet

Unlike the checkbox facet, which allows users to make multiple selections with the option of applying AND/OR logic, the radio facet restricts users to selecting only one option at a time, offering a more singular and focused filtering experience.

OptionDescription
All Button LabelLabel used for All button (unfiltered state)
Show Empty ChoicesShow choices that match no results when filtered
Show Choice CountShow the number of results matching each choice
Show Current TermsShow current archive page terms (taxonomy only)
Show ChildrenShow child terms of the selected taxonomy (taxonomy only)

DropdownDropdown

Dropdown Facet
Dropdown Facet

The dropdown facet offers versatile functionality. When the Multiple Selection option is disabled, it functions similarly to radio facet, allowing users to make only one selection at a time. However, when Multiple Selection is enabled, it behaves like checkboxes, offering both AND/OR logic for multiple selections.

OptionDescription
Logic Between ChoicesApply AND or OR logic between selected choices
Multiple SelectionAllows selection of several choices
PlaceholderText displayed when no choices are selected
Show Empty ChoicesShow choices that match no results when filtered
Show Choice CountShow the number of results matching each choice
Show Current TermsShow current archive page terms (taxonomy only)
Show ChildrenShow child terms of the selected taxonomy (taxonomy only)

Furthermore, it features a Combobox option with Asynchronous Search (Searchable List) capabilities, dynamically displaying choices as users type. This enhances usability by providing instant feedback and streamlining the selection process. Moreover, it enables you to manage thousands of choices seamlessly, without encountering performance or display issues.

OptionDescription
ComboboxReplace native select element with a JavaScript-driven dropdown list
Clearable ListAdd a delete button to erase user selection
Searchable ListAdd a search input to search for choices
Asynchronous SearchSearch for choices asynchronously while typing
No Results MessageMessage displayed when no results match a search
Loading MessageMessage displayed while choices are loading (Asynchronous Search)
Search MessageMessage displayed in the menu before a search (Asynchronous Search)

ButtonButton

Button Facet
Button Facet

The Button facet presents a distinct interface that can emulate both radio buttons and checkboxes. Users can choose between single or multiple selections, with each option displayed as a separate button. This design provides clear and intuitive interaction options, enhancing user experience during content filtering.

OptionDescription
Logic Between ChoicesApply AND or OR logic between selected choices
All Button LabelAdd “All” button for unfiltered state (optional)
Multiple SelectionAllows selection of several choices
Show Empty ChoicesShow choices that match no results when filtered
Show Choice CountShow the number of results matching each choice
Show Current TermsShow current archive page terms (taxonomy only)
Show ChildrenShow child terms of the selected taxonomy (taxonomy only)

HierarchyHierarchy

Hierarchy Facet
Hierarchy Facet

The Hierarchy facet allows for the management of large hierarchical taxonomies. Its asynchronous functionality facilitates seamless navigation through extensive taxonomy structures. By dynamically displaying choices from the selected term’s depth, users can efficiently explore and select options, irrespective of the taxonomy’s size. This feature ensures a smooth and intuitive browsing experience, even when dealing with complex and extensive taxonomies.

OptionDescription
All Button LabelLabel used for All button (unfiltered state)
Show Choice CountShow the number of results matching each choice

Number FieldsNumber Fields

Number Fields Facet
Number Fields Facet

The Number Fields facet enables filtering by numeric value(s). You can filter by a range of minimum and maximum values or by a single value (minimum, maximum, or exact value). When filtering by a range, you can compare the data source to the selected range values in various ways.

OptionDescription
Fields to ShowDisplay min and/or max inputs or exact input
Compare TypeCompares the values of the data source to the range of selected values
Min PlaceholderPlaceholder displayed in Min input
Max PlaceholderPlaceholder displayed in Max input
Input PlaceholderPlaceholder displayed in Exact input
Min LabelLabel displayed in Min input
Max LabelLabel displayed in Max input
Input LabelLabel displayed in Exact input
Submit Button LabelLabel displayed in submit button (optional)
Display LabelsDisplay label above the inputs

The Comparison Type option offers three possibilities:

  • Inside: The data source values must fall within the selected range slider values.
    Example: If a product is priced from $60 to $90, it falls inside the selected range of $50 to $100.
  • Arround: The data source values must surround the selected range slider values.
    Example: If a product is priced from $40 to $110, it’s considered “around” the selected range of $50 to $100 because it’s close to the upper limit but still outside it.
  • Intersect: The data source values must intersect the selected range
    Example: If a product is priced from $80 to $110, it intersects with the selected range of $50 to $100 because it partially overlaps with it.

In addition, you’ll discover settings to format the values that users can input into the fields.

OptionDescription
Value PrefixPrefix added to the input placeholder
Value SuffixSuffix added to the input placeholder
Step IntervalStepping interval for increasing or decreasing values
Thousands SeparatorFormats numbers by adding separators for thousands
Decimal SeparatorSymbol for separating integer and fractional parts
Decimal PlacesSpecifies the number of digits after the decimal point

Range SliderRange Slider

Range Slider Facet
Range Slider Facet

The Range Slider facet enables visual filtering by numeric values. You can establish a range of minimum and maximum values and select from various comparison types to compare the data source with the chosen range values in multiple ways.

OptionDescription
Compare TypeCompares the values of the data source to the range of selected values
Reset LabelLabel used for the reset button (optional)

The Comparison Type option offers three possibilities: Inside, Around, and Intersect. Please refer to the Number Fields facet for more details.

In addition, you’ll discover settings to format the values that users can input into the fields.

OptionDescription
Value PrefixPrefix added to the values
Value SuffixSuffix added to the values
Step IntervalStepping interval for increasing or decreasing values
Thousands SeparatorFormats numbers by adding separators for thousands
Decimal SeparatorSymbol for separating integer and fractional parts
Decimal PlacesSpecifies the number of digits after the decimal point

Date PickerDate Picker

Date Picker Facet
Date Picker Facet

The Date Picker facet simplifies date selection for filtering, utilizing a calendar interface. Users can easily choose specific date or a range of dates, enhancing usability and functionality.

OptionDescription
Date TypeWhether to filter by a single date or a range of dates
Compare TypeCompares the values of the data source to the range of selected values
Date FormatDate format displayed in input after selection
Input PlaceholderPlaceholder displayed in the input if empty

The Comparison Type option offers three possibilities:

  • Inside: The data source values must fall within the selected range slider values.
    Example: If an event occurs from January 15th to January 25th, it falls inside the selected range of January 10th to January 30th.
  • Arround: The data source values must surround the selected range slider values.
    Example: If an event occurs from January 5th to February 5th, it’s considered “around” the selected range of January 10th to January 30th because it’s close to the limits but still outside them.
  • Intersect: The data source values must intersect the selected range
    Example: If an event occurs from January 25th to February 5th, it intersects with the selected range of January 10th to January 30th because it partially overlaps with it.

Rating PickerRating Picker

Rating Picker Facet
Rating Picker Facet

The Rating Picker facet simplifies rating selection for filtering, utilizing a star-based interface. Users can select a rating from 1 to 5 stars, dynamically filtering data based on the chosen rating value and higher, providing a flexible and intuitive filtering experience

OptionDescription
All Button LabelLabel used for All button
Show Empty ChoicesShow choices that match no results when filtered
Show Choice CountShow the number of results matching each choice
Show ChildrenShow child terms of the selected taxonomy (taxonomy only)

Color PickerColor Picker

Color Picker Facet
Color Picker Facet

The Color Picker facet simplifies color selection for filtering, employing a visual interface with color swatches. Users can easily choose specific colors, enhancing ease of use and functionality in filtering data.

OptionDescription
Logic Between ChoicesApply AND or OR logic between selected choices
Multiple SelectionAllows selection of several choices
All Button LabelLabel used for All button
Show Empty ChoicesShow choices that match no results when filtered
Show Choice CountShow the number of results matching each choice
Show Current TermsShow current archive page terms (taxonomy only)
Show ChildrenShow child terms of the selected taxonomy (taxonomy only)

The Color Picker facet offers settings to customize both the background of color swatches and choice labels. WP Grid Builder attempts to automatically detect colors from the data source. If the choice value doesn’t correspond to a valid CSS color, you can manually assign a background by entering the corresponding value. This value, found in the URL when filtering, helps identify the correct choice to assign a custom background and label.

A-Z IndexA-Z Index

A-Z Index Facet
A-Z Index Facet

The A-Z index facet arranges content alphabetically, providing clickable letters or numbers for quick navigation. Users can select a letter or number to promptly access content starting with that character, making navigation easier within large datasets.

OptionDescription
Logic Between ChoicesApply AND or OR logic between selected choices
Multiple SelectionAllows selection of several choices
All Button LabelLabel used for All button
Alphabetical IndexComma separated list of letters used to filter
Numeric IndexComma separated list of numbers used to filter
Show Empty ChoicesShow choices that match no results when filtered
Show Choice CountShow the number of results matching each choice
Show ChildrenShow child terms of the selected taxonomy (taxonomy only)

Search FieldSearch Field

Search Field Facet
Search Field Facet

The Search Field facet allows users to input search queries to filter data. It enhances filtering capabilities by dynamically displaying results that match the search criteria, enabling users to quickly find relevant information.

The default search utilizes WordPress search engine, searching within post titles and content. To expand search functionality, plugins like SearchWP or Relevanssi can be used to extend the capabilities of the WordPress search engine.

OptionDescription
Search PlaceholderText displayed when no choices are selected
Search EngineSearch engine defaults to searching within WordPress post titles and conten
Search NumberNumber of results to search for
Search RelevancyKeep search order relevance
Instant SearchUpdate results and facets while typing.

Auto-completeAuto-complete

Auto-complete Facet
Auto-complete Facet

The Auto-complete facet is a type of search field that offers suggestions or completions for search queries derived from a single data source. Unlike the Search Field facet, which typically scans through post titles and content, the Auto-complete facet specializes in providing search suggestions from a specific dataset.

OptionDescription
Search PlaceholderText displayed when no choices are selected
Min CharactersMinimum number of characters to trigger a search
Sort by RelevanceSort suggested choices by relevance
Auto FocusAutomatically focus first suggestion in the list
HighlightHighlight matched string in suggestion
Highlight All MatchesHighlights all matching strings in suggestion
Show Empty ChoicesShow choices that match no results when filtered
Show Choice CountShow the number of results matching each choice
Show Current TermsShow current archive page terms (taxonomy only)
Show ChildrenShow child terms of the selected taxonomy (taxonomy only)

User SelectionUser Selection

User Selection Facet
User Selection Facet

This facet enables the display of user selections across all selected filter facets. It also provides the option to unset each selected choice to revert the filtering.

Load FacetLoad Facet

When setting the facet action to Load Content, you will discover four new types of facets designed to interact with content loading.

PaginationPagination

Pagination Facet
Pagination Facet

This facet enables the display of pagination for easy navigation through content.

OptionDescription
Pagination TypePagination type (numbers or prev/next buttons)
Prev Button LabelLabel displayed in previous button
Next Button LabelLabel displayed in next button
Dots Page LabelLabel displayed for the page dots
Middle Pages SizeHow many numbers appear on each side of the current page
End Pages SizeHow many numbers on either the start and the end pagination edges
All Page NumbersShow all of the pages instead of a short list of the pages
Scroll to TopScroll to the top of the content when paging
Scroll OffsetScroll offset from the content (accepts negative values)

Load MoreLoad More

Load More Facet
Load More Facet

The Load More facet allows users to dynamically load additional content without reloading the entire page. It’s a convenient way to access more items within a dataset, enhancing user engagement and navigation.

OptionDescription
Number to Load MoreNumber of posts, terms or users to load more
Trigger Loading onLoad more on click or scroll
Button LabelLabel displayed in the load more label
Loading MessageMessage displayed when loading more content
Show Remaining ResultsDisplays the number of remaining results in the load more button.

Per PagePer Page

Per Page Facet
Per Page Facet

Display a list of options for the number of posts per page to load in the filtered content.

OptionDescription
Per Page OptionsComma-separated list of options for the number of items per page.

This facet also includes a Combobox feature that enhances navigation.

OptionDescription
ComboboxReplace native select element with a JavaScript-driven dropdown list
Clearable ListAdd a delete button to erase user selection
Searchable ListAdd a search input to search for choices
No Results MessageMessage displayed when no results match a search

Result CountsResult Counts

Result Counts Facet
Result Counts Facet

The Results Counts facet displays both the current number of items and the total number found, offering users a comprehensive overview of the displayed results.

OptionDescription
Singular MessageMessage displayed when there is only one result
Plural MessageMessage displayed when there are several results

Sort ContentSort Content

Sort Facet
Sort Facet

WP Grid Builder offers the possibility to sort content using a dropdown list with various criteria, including WordPress fields (title, date, author, etc.) and custom fields.

The Sort facet provides settings to add multiple sorting options for organizing content based on various criteria. The first sort option in the settings serves as a placeholder, corresponding to the default order set for your grid or content to be filtered. This placeholder represents the unsorted state, used when the page initially loads.

Just like with the Dropdown facet, you have the option to use a Combobox as a replacement for the native select element.

Reset FiltersReset Filters

Reset Facet
Reset Facet

A reset facet allows users to revert a facet’s selection back to its default state, clearing any filters or modifications applied to it. It’s a convenient way to quickly reset all facets and start fresh when refining search results or navigating content.

OptionDescription
Button LabelLabel displayed in the reset button
Reset FacetsInclude facets to be reset (all by default)

Apply FiltersApply Filters

Apply Facet
Apply Facet

The Apply facet serves two different purposes. Firstly, it can function as a button to apply selected choices from the user. This means that instead of filtering automatically when a choice changes, it will only filter when the user presses the Apply button. Secondly, it can also redirect to a filtered page instead of filtering the current page when the Apply button is pressed.

When using the Apply facet to redirect to a results page, you may not have a grid or content to attach to it on the same page. However, you must always attach a grid to the Apply facet or any other facets on the page in order to query them. So, if you don’t have content on the page, you need to set up a grid query and use it for your facets. It’s not necessary to add the grid to the page to render facets on the page. The grid, in this case, will only be used to query facets.

OptionDescription
Action on ClickApply selected filters or redirect to a filtered page
Button LabelLabel displayed in the apply button
Exclude FacetsFacets to exclude from the filter to apply
Redirect URLRedirect URL for the filtered results page
Browser’s HistoryAllow history navigation by pushing facet parameters in url when filtering

ConditionsConditions

Because conditions are processed on the backend and impact the frontend, to ensure proper functionality, it’s recommended not to use a caching solution. Otherwise, you may cache certain conditions and render them incorrectly.

Facets can be conditionally revealed, hidden, enabled, or disabled. This means that you can create interactions between facets and the content or several other criteria while filtering. Conditions are set at the facet level and will be applied across the entire site. However, you can also set conditions based on the URL, allowing you to have different behaviors for the same facet on different pages.

The conditional action will be executed when all conditions are met. This means that if, for example, you want to reveal a facet, it will be hidden until all conditions are met. Once met, the facet will appear. Moreover, you can combine conditions. This means that you can, at the same time, reveal a facet if it meets several conditions and keep it disabled (not selectable) until it meets other conditions.

Facet - Conditions
Facet – Conditions

Every condition consists of the following three properties:

  • Data (post ID, user role, date, dynamic data, etc.)
  • Compare with (==, !=, >, <, >=, <=, in, not in, contains, before, after, etc.)
  • Value (numeric, text, checkbox, option(s), etc.)

A condition can also include additional fields, for example, to select a facet to compare with a value.

Conditions accept both AND and OR logic to create advanced relationships between clauses. Within a set of conditions, an AND relation is applied, while between sets of conditions, an OR relation exists. This means that the facet is rendered if at least one set of conditions is met.

AdvancedAdvanced

In this settings panel, you will be able to set the facet slug and title. The facet slug must be unique and correspond to the parameter key added in the URL when filtering. This allows for the identification of the facet in order to filter content from the values passed in the URL.

Facet - Advanced
Facet – Advanced
OptionDescription
Facet SlugA unique identifier for the facet used to filter content from a URL
Facet TitleDisplay a title above the facet (optional)

Index FacetIndex Facet

In order to efficiently filter content, each filter facet (excluding search and user selection facets) are indexed in an custom index table. It means, that everytime you create a facet, the plugin automatically queries and stores all facet values according to your facet settings. This process is called indexing and simply allows to “prefetch” results and to store them in a simple and indexed table.

Sometime, you may need to manually re-index your facets. You can re-index each facet independently in facet settings page or in facets overview page:

Facet Settings - Re-index
Facet Settings – Re-index
Facets Overview - Re-index
Facets Overview – Re-index

At any time, you can also start or stop the indexer or clear the index table in the plugin dashboard.

Dashboard - Indexer
Dashboard – Indexer