for

Instant search page

Customizing Algolia's instant search page


Algolia also ships with the possibility of enhancing your current search page with realtime search capabilities.

The instant search page is much more style and logic-intensive than the autocomplete, which is why you should expect the need to have a front-end developer available to work on integrating it.

Configuration

You have a few configuration options specific to the instant search page in the Configuration tab of the app.

Configuration options

The CSS selector is the selector used to target the current search block on the search page. The default value will most likely NOT match your theme.
Another option is to add the algolia-shopify-instantsearch class to the DOM element you want us to replace.

Enabling Algolia's search without as you type experience

Here are the steps to enable Algolia powered search on your Shopify application without the search as you type experience using Instant Search. Search will be performed only when the enter key is pressed.

  1. From the dashboard, make sure your theme has the Algolia plugin installed. Please make a duplicate version for testing/beta purposes.

  2. From the Search Options tab, click the InstantSearch checkbox to enable InstantSearch and hit save.

    Instant Search option

  3. Click on the "Open templates/search.liquid" button to see the code files.

  4. Under Assets category, open file "algolia_instant_search.js.liquid"

  5. Find the line containing SearchBox widget and add the following parameter "searchOnEnterKeyPressOnly: true", as shown below.

    Snippet algolia_instant_search.js.liquid

  6. Incorporate InstantSearch into your theme. Note that depending on how you’ve customized your theme, you may need to change some of the styling to play nicely with InstantSearch. See the Instant Search documentation for more details.

Files

If you're looking to change the behaviour of the search page, it's highly likely that the configuration options didn't match your needs.
You'll have to dive in the code instead.

The instant search page requires more logic than the autocomplete menu, here is the full list of files:

- assets/algolia_instant_search.js.liquid
- snippet/algolia_instant_search.css.hogan.liquid
- snippet/algolia_instant_search.hogan.liquid

- assets/algolia_sort_orders.js.liquid
- snippet/algolia_instant_search_stats.hogan.liquid

- assets/algolia_facets.js.liquid
- snippet/algolia_instant_search_facet_item.hogan.liquid
- snippet/algolia_instant_search_current_refined_values_item.hogan.liquid

- snippet/algolia_instant_search_product.hogan.liquid
- snippet/algolia_instant_search_no_result.hogan.liquid

Main files

assets/algolia_instant_search.js.liquid

This file is the main file of the instant search: it contains most of the front-end logic.
To learn more about the library we're using, you can check out two important resources:

In this file, we're defining all of the instantsearch.js widgets needed for our search.

snippet/algolia_instant_search.css.hogan.liquid

This file contains all the styling for the instant search page. If you're looking to modify the instant search dropdown, this is the probably the first file you'll want to open. The reason it is also a .hogan template is to be able to pass some configuration options from the JavaScript file to the stylesheet, like colors.

Passed object:

{
  colors: {     // Theme colors (configurable in the application)
    main,
    secondary,
    highlight
  },
  helpers
}

snippet/algolia_instant_search.hogan.liquid

Page layout template.

Passed object:

{
  facets,
  helpers,
  storeName
}

Search header

What we call header here is the small bar under the search input.

assets/algolia_sort_orders.js.liquid

Uses the app configuration and prepares the sort orders in a format expected by instantsearch.js's sortBySelector.

snippet/algolia_instant_search_stats.hogan.liquid

Template used with the stats widget.

{
  cssClasses,       // CSS classes used with the stats widget
  hasNoResults,
  hasOneResult,
  hasManyResults,
  helpers,
  hitsPerPage,      // Number of results per page
  nbHits,           // Total number of results
  nbPages,          // Total number of pages
  page,             // Current page
  processingTimeMS,
  processingTimeS,
  query,            // Current query
  start,            // Position of the first result of the page
  end               // Position of the last result of the page
}

Filtering

assets/algolia_facets.js.liquid

Uses the app configuration and prepares the sort orders in a format expected by instantsearch.js's faceting widgets.

snippet/algolia_instant_search_facet_item.hogan.liquid

Template used to represent each line of a refinementList widget.

Passed object:

{
  count,                  // Number of results matching this facet
  cssClasses,             // CSS classes used with the widget
  helpers,
  isExcluded,             // Is this facet excluded? (not used in our front-end, allows to exclude search results)
  isRefined,              // Is this facet used?
  name,                   // Facet value
  type: {                 // Convenience object to use within the template like so `[[# type.conjunctive ]]Only if the facet is conjunctive[[/ type.conjunctive ]]`
    <TYPE_NAME>: true
  }
  url                     // Search URL after the usage of the facet
}

snippet/algolia_instant_search_current_refined_values_item.hogan.liquid

Template used to represent each line of a currentRefinedValues widget.

Passed object:

{
  attributeName,        // Facet attribute
  count,                // Amount of results matching this facet
  cssClasses,           // CSS classes used by the widget
  exhaustive,           // Is the count exhaustive
  helpers,
  label,                // Facet name (title used in the facet header)
  name,                 // Facet value
  type                  // Type of facet: one of ['facet', 'exclude', 'disjunctive', 'hierarchical', 'numeric', 'tag']
}

Results templates

snippet/algolia_instant_search_product.hogan.liquid

Product's entry template. It receives the Algolia response record. It's the record with a few extra attributes.

Passed object:

{
  // ... product attributes
  can_order,                  // Can be added to cart
  helpers,
  // Algolia search result attributes
  // See https://www.algolia.com/doc/api-client/php/search#sample
  _highlightResult,           // For all attributes in the attributesToHighlight setting of the index
  _snippetResult              // For all attributes in the attributesToSnippet setting of the index
}

snippet/algolia_instant_search_no_result.hogan.liquid

Template used in case of no result.

Passed object:

{
  helpers,
  query         // Query used for the search
}

Customization

Displaying search results as a list by default

If you want to change the default display to the list style by default, you only need to do a very small change to snippets/algolia_instant_search.hogan.liquid:

@@ -24,15 +24,15 @@
     <div class="ais-search-header">
       <div class="ais-stats-container"></div>
       <div class="ais-change-display">
-        <span class="ais-change-display-block ais-change-display-selected"><i class="fa fa-th-large"></i></span>
-        <span class="ais-change-display-list"><i class="fa fa-th-list"></i></span>
+        <span class="ais-change-display-block"><i class="fa fa-th-large"></i></span>
+        <span class="ais-change-display-list ais-change-display-selected"><i class="fa fa-th-list"></i></span>
       </div>
       <div class="ais-sort">
         Sort by
         <span class="ais-sort-orders-container"></span>
       </div>
     </div>
-    <div class="ais-hits-container ais-results-as-block"></div>
+    <div class="ais-hits-container ais-results-as-list"></div>
   </div>
   <div class="ais-pagination-container"></div>
 </div>