Change the Storefront Search Filters UI
Invariably, through the course of developing the Storefront, your designer will design aspects of the site differently than what the platform supplies out of the box. To handle these changes a developer will need to override views, Stylesheet and JavaScript files from the platform into their application in order to make the necessary customizations. Additional changes may be made to helpers or view models used for the simplification of the views themselves.
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.
File Overview
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 mobile-filters
and result-filters
component blocks, with the elements of the latter being housed within each facet partial.
Helpers
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:
app/helpers/workarea/facets_helper.rb
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:
app/helpers/workarea/storefront/facets_helper.rb
Please note that helpers cannot be decorated, but they can be customized.
Stylesheets
The styling for the mobile-filters
and 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
The 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.
JavaScript
Naturally JavaScript is used to handle the mobile-filter
button user experience. There is one module which handles its functionality:
app/javascripts/workarea/storefront/modules/mobile_filter_buttons.js
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.
System Tests
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!