Change the Storefront Search Filters UI
Types of Customizations
Based on the design and user-experience processes a developer may need to customize this UI to best suit the needs of the user and the aesthetic of the brand.
Some common customizations include
- using the jQuery UI Accordion widget to compress the list of filters
- move filters into a custom overlay or drop-down
- change the look and feel of the filter's selected state
- apply a faux checkbox UI to filter links
- break out the list of selected filters from the list unselected filters
As with all other aspects of Storefront development, this UI is built mobile-first. The presentation of the Search Filters UI, on mobile, is hidden behind a button click. When clicked, the button triggers the display of a drawer-like UI which contains the Search Filters UI.
Views & View Partials
The markup for the Search Filters UI is provided by the following views:
app/views/workarea/storefront: categories: show.html.haml searches: show.html.haml
These views reference a variety of partials, named after the type of facet by which a user would filter their results. Consider this an incomplete list, as plugins may also register their own facet partials. The facet partials that the platform provides out of the box are:
app/views/workarea/storefront/facets: _range.html.haml _terms.html.haml
The category and search views define the key and expiry duration for the fragment cache that wraps the UI.
These views also define the
result-filters component blocks, with the elements of the latter being housed within each facet partial.
The facet's path, price range link text, and associated hidden inputs that are output on the page are generated by the
Workarea::FacetsHelper located in:
This helper is shared between the Storefront and Admin engines, which is why it is located in the Core engine. Be aware that changes made to this file will impact both Storefront and Admin engines in tandem.
If you need to add an additional method to this helper that was used for output on the Storefront only, you would simply create a new helper
Workarea::Storefront::FacetsHelper and place it in:
Please note that helpers cannot be decorated, but they can be customized.
The styling for the
result-filters components are supplied by the following Stylesheets:
app/assets/stylesheets/workarea/storefront/components: _mobile_filters.scss _mobile_filters_nav.scss _result_filters.scss
mobile-filters are comprised of element classes used for styling a hidden checkbox used for handling the button's change state, a clickable trigger, and a block of content that will toggle based on the state of the aforementioned checkbox.
As for the
result-filters, by default each section of the UI provides element classes for styling a list of facets, a selected state modifier, and the number of results that match the current facet. The latter toggles into a prompt to remove the facet once it has been selected by the user.
mobile-filter button user experience. There is one module which handles its functionality:
On initialization, this module binds two events, one to an element with a
data-mobile-filter-click attribute and one to the document's
body. The first triggers the building, injection, activation and ultimate display of the mobile filters with the second responsible for the removal of the UI from view.
Due to the simplicity of the markup wrapping the
mobile-filters-nav component there is no associated JST template to accompany this UI; it is simply built within the module itself.
As with almost all other interactive aspects of the Storefront, modifying the Search Filters UI may cause its associated system tests to fail. After considerable modification to this UI you should review and run the following tests to make sure that they are still relevant and that the changes you have made have not caused them to fail:
test/system/workarea/storefront: categories_system_test.rb search_system_test.rb
Help Us Improve this Doc
Was this helpful? Open a GitHub issue to report a problem with this doc, suggest an improvement, or otherwise provide feedback. Thanks!