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