Algolia Search is a hosted full-text, numerical, and faceted search engine capable of delivering realtime results from the first keystroke.
This plugin replaces the default search of Wordpress with an Algolia realtime search. It has been designed to support plugins like WooCommerce in addition to the standard blog system.
- Create an Algolia account
- Once logged in, go to the Credentials section and get your Application ID & API keys
- Install Algolia Wordpress Plugin in your Wordpress dashboard
- Activate the plugin through the Plugins menu in Wordpress
- Go to the Algolia Search left menu configuration page and fill the your API keys
- Configure the way Algolia is indexing your objects.
In this section you configure two things:
- Your Application ID & API keys (credentials):
You need to choose which api keys to use. You can go https://www.algolia.com/licensing
- Your index names prefix:
The plugin will create several indices:
* 1 index for the instant search
* 1 index for each section of the auto-completion menu
* 1 (slave) index for each sort order you enable
- Search Bar
To be able to trigger the search at each keystroke on your site you need to specify where the plugin is supposed to find the search input. You do that by specifying a jQuery/DOM selector.
In Wordpress's default theme it is: [name='s']
- Search Experience
The plugin let you choose between two different experiences: an autocompletion menu and/or an instant search results page.
* **Autocompletion menu**
This experience adds an autocompletion menu to your search bar. In this menu you will have a section for each type & taxonomy you enable (page, post, category, tag...).
You need to specify the maximum number of result you want to display in each section.
* **Instant search**
This experience refreshes the whole results page as you type. At each keystroke, the plugin refreshes your whole search results page: including hits, facets & pagination.
You need to indicate the jQuery/DOM selector specifying where the plugin is supposed to inject your results.
You can also configure the number of results you want by page.
The plugin supports themes which allows you to customize the way your results are displayed. You can choose one of the 2 sample themes or build your own.
The theme is totally independent from the Wordpress theme. The default themes handle both Autocompletion AND Instant-search results page.
You can choose the Wordpress types you want to index. By default, only post
and page
are configured. If one of your extensions (WooCommerce for instance) creates new types you will see them in this list.
You can order them to change the order of each section of the autocompletion menu. In autocompletion menu mode you can also specify the label used for each type to display the title of search section.
You can configure additional attributes or taxonomies you want to index. If you use Wordpress as a blog you shouldn't have to change anything. When using Wordpress with plugins like WooCommerce this should be very useful as you probably want to index the price
or the total_sales
attributes as well.
When you enable an attribute, the plugin will add this attribute to the record but it will NOT be searchable UNLESS you enable it in the Search Configuration tab.
When you make an attribute facetable AND if you are in Instant Search Results Page mode you will see a faceting/filtering bloc appears in which you can filter your results easily.
There is two facet types you can choose:
-
Conjunctive
Your refinements are ANDed. Think about a post having the tags
lifestyle
ANDmood
. -
Disjunctive
Your refinements are ORed. Think about a products search with:
4
OR5
stars. -
Custom: slider, tag clouds, ...
A theme can declare new facet types. The default one is adding the "slider" type.
You can add a label to each enabled facet to display the Facet bloc title. You can also order the facet blocs ordering the attributes.
For each attribute you enable, you can decide to make it searchable. You can also choose if you want the attribute to be consider ordered or not:
-
Ordered
Matches at the beginning of an attribute will be considered more important than matches at the end. This setting is recommended for short attributes like
title
. -
Unordered
Matches at the beginning of the list will not be considered more important than matches at the end. This setting is recommended for long attribute like content
.
Notes: If an attribute does not appear in this tab, be sure that you first enabled it on the Attributes tab.
For each attribute you enable, you can make them part of your custom ranking formula.
Notes: Attributes that you enable here NEED to be numerical attributes.
For each attribute or taxonomy you enable you can select the ones you want to sort with.
Notes: Adding a new sort order will create a slave index with the exact same settings except the ranking formula will have the use the attribute you enable as the first ranking criterion. You can choose a label which will be displayed on the instant search result page.
You can build your own search theme to make the search results look exactly like your current Wordpress theme. The simplest way to do that is to copy one of the two default themes and work from there. In most cases the only thing you will need to do is modify the templates.php
file so that you can put you own DOM/CSS elements to the template.
Notes: Remember: there is no link between the Wordpress theme and the plugin theme.
A theme is composed by several MANDATORY files:
-
config.php
It should look like
<?php return array( 'name' => 'Woo Default', 'screenshot' => 'screenshot.png', 'screenshot-autocomplete' => 'screenshot-autocomplete.png' 'facet_types' => array() );
The
name
will be displayed on the UI Page: it's your theme's name. And the screenshot and screenshot-autocomplete is the path of your instant search AND autocompletion menu screenshots (relative to your theme root directory). -
styles.css
This file contains every CSS rules used by the theme.
-
templates.php
This file contains all the HTML (we use Hogan.js) templates you need. The mandory content are:
<script type="text/template" id="autocomplete-template"> /* Your autocomplete Hogan template HERE */ </script> <script type="text/template" id="instant-content-template"> /* Your instant search results Hogan template HERE */ </script> <script type="text/template" id="instant-facets-template"> /* Your facets template HERE */ </script> <script type="text/template" id="instant-pagination-template"> /* Your Pagination template HERE */ </script>
-
theme.js
This file includes all the JavaScript logic.
You have access to the following things:
This global JS variable contains every settings coming from the Wordpress back-end. It is defined on the AlgoliaPlugin.php as follow:
$algoliaSettings = array(
'app_id' => $this->algolia_registry->app_id,
'search_key' => $this->algolia_registry->search_key,
'indexes' => $indexes,
'sorting_indexes' => $sorting_indexes,
'index_name' => $this->algolia_registry->index_name,
'type_of_search' => $this->algolia_registry->type_of_search,
'instant_jquery_selector' => str_replace("\\", "", $this->algolia_registry->instant_jquery_selector),
'facets' => $facets,
'number_by_type' => $this->algolia_registry->number_by_type,
'number_by_page' => $this->algolia_registry->number_by_page,
'search_input_selector' => str_replace("\\", "", $this->algolia_registry->search_input_selector),
'facetsLabels' => $facetsLabels,
"plugin_url" => plugin_dir_url(__FILE__)
);
You will have access to every function and attribute define in the front/main.js
. You use the functions in this variable as a starting point to make your own or you can use it directly. Those function are the following:
setHelper: To use the engine you should set the AlgoliaSearchHelper at the beginning of your code
updateUrl: Save the refinements to the url
getRefinementsFromUrl: Load the refinements from the url and make a query with those refinements
getFacets: Make an object you can use to render your facets template
getPages: Make an object you can use to render your page template
getHtmlForPagination: Return the rendered hogan template for pagination
getHtmlForResults: Return the rendered hogan template for results
getHtmlForFacets: Return the rendered hogan template for facets
gotoPage: Set the current page when your are in instant search mode
getDate: A function that allow you to get a readable date from timestamp you can use like that in your hogan theme:
{{#getDate}}{{date}}{{/getDate}}
sortSelected: A function that return "selected" if the parameter is equals to the current sort. You can use in that way in your hogan theme :
<input {{#sortSelected}}name_of_the_index{{/sortSelected}} />
It depends :) The plugin handles every other plugins that uses the post
and meta
tables of Wordpress. If a plugin creates its own tablem the plugin will not be able to see it.
If you want to integrate a plugin that is not handled out of the box, you will need to dive into the plugin source code since there is no way to handle it in a generic way.
In the algolia.php
file in the root directory of the plugin you can change the following two lines:
$attributesToSnippet = array("content");
For the attributes to snippet you can add a length EXCEPT for "content" which is set from the params in UI integration. If you add an attribute it should look like
$attributesToSnippet = array("description:30");
The plugin tries to merge the settings that have been modified from the Algolia dashboard and the one generated from your plugin configuration. In every case the following settings will be erased:
- For the autocompletion-menu
attributesToIndex
attributesToHighlight
attributesToSnippet
- For the instant search results page
attributesToIndex
attributesForFaceting
attributesToSnippet
customRanking
slaves
ranking
(only for the sorting (slaves) indexes)
In your theme theme.js
file in the root directory of the plugin you may want to add those attributes to this line:
window.facetsLabels = {
'post': 'Article',
'page': 'Page'
};
For example if you want to replace "product" by "Products" in the facets elements, it will look like this:
window.facetsLabels = {
'post': 'Article',
'page': 'Page',
'product': 'Product'
};
This works for any other facet but the Type one is the most likely to have non wanted formating.
When you change a setting that impacts the index you may want to use the Re-index data button to reflect your changes in your Algolia index.