Customize Templates

Add custom templates for WP Search with Algolia into your theme.

Introduction

The WP Search with Algolia plugin provides users with a default look & feel for the 2 main features of the plugin which are the Autocomplete drop-down and the Instantsearch powered search page. However, as a theme author you might want to customize the appearance of the search experiences so that they fit into your theme.

To do so, you can add template files to your theme as explained in:

• Customization of the Autocomplete dropdown
• Customization of the Instantsearch page

---

If you are not the author of the theme you are using, we recommend you create a child theme so that you don't loose your changes after updating the theme.

---

Default location of template files via theme folder

By default, the plugin will look for the template files in your theme in different locations by order of priority:

1. In the root folder of your theme, e.g. wp-content/themes/yourtheme/autocomplete.php
2. In a folder named algolia, e.g. wp-content/themes/yourtheme/algolia/autocomplete.php
3. In a custom defined directory as explained in the Customize template folder name section
4. At custom locations as explained in Customize template names and location
5. In the plugin's templates folder if none of the preceeding matched.

All of these will still search relative to your active theme location.

---

The first matching template found will be used. Even if you defined a custom directory as is explained in the next section, if a template is found in wp-content/themes/yourtheme/algolia/*, then the later template would be used.

Customize templates folder name

The plugin provides a filter called algolia_templates_path which allows you to customize the name of the folder where the plugin will look for templates.

Here is an example that lets you place your template files for customizing the Algolia Search experiences in a folder named partials/ instead of algolia/.

<?php
// functions.php in your theme's root directory.
function my_theme_custom_template_path() {
    return 'partials/';
}
add_filter( 'algolia_templates_path', 'my_theme_custom_template_path' );

---

Be sure you don't omit the trailing slash.

---

You can now place your algolia template inside of the partials folder.

The plugin will try to load:

• wp-content/themes/yourtheme/partials/autocomplete.php
• wp-content/themes/yourtheme/partials/instantsearch.php

---

If one of the template is not present in the folder, it will fallback to the template shipped with the plugin only for that omitted template, still loading your custom version for the other.

---

Customize template names and location

In the previous section you learned how to customize the folder where the plugin will try to load the templates from.

As a theme author, maybe you are respecting some kind of naming convention, and would also like to change the template names in addition to their location.

The plugin provides a filter hook called algolia_template_locations that allows you to suggest the plugin additional locations to look at when loading templates.

In the next example, we make it so that the templates will be loaded from:

• wp-content/themes/yourtheme/search/algolia-autocomplete.php
• wp-content/themes/yourtheme/search/algolia-instantsearch.php

<?php

/**
 * @param array  $locations
 * @param string $file
 *
 * @return array
 */
function my_algolia_template_locations( array $locations, $file ) {
    if ( $file === 'autocomplete.php' ) {
        $locations[] = 'search/algolia-autocomplete.php';
    } elseif ( $file === 'instantsearch.php' ) {
        $locations[] = 'search/algolia-instantsearch.php';
    }

    return $locations;
}

// functions.php in your theme's root directory.
add_filter( 'algolia_template_locations', 'my_algolia_template_locations', 10, 2 );

---

Please note that templates found in the templates directory we customized in the previous section will always take preceedence.

---

Custom location outside of theme folder

Valid for version 2.5.0+

If you would like to bundle template files in a location away from your active theme, you can make use of the algolia_custom_template_location filter. The filter passes a null value and the name of the file being requested. To provide a file away from the theme folder, return the server path, including the filename. Return a null value back to have WP Search with Algolia continue with the locations above and the theme folder.

Imagine you're wanting to have the customized template files as part of a custom plugin that's not tied to the theme. You could load them similar to the code below. This is assumed to be in the root directory for the plugin, and in the main plugin file.

if ( ! defined( 'ALGOLIA_MY_PATH' ) ) {
    define(
        'ALGOLIA_MY_PATH',
        __DIR__ . '/'
    );
}

if ( ! defined( 'ALGOLIA_MY_PATH_TEMPLATE_PATH' ) ) {
    define(
        'ALGOLIA_MY_PATH_TEMPLATE_PATH',
        ALGOLIA_MY_PATH . 'templates/'
    );
}

function load_autocomplete_template( $location, $file ) {
    if ( ! in_array( $file, [ 'autocomplete.php', 'instantsearch.php' ] ) ) {
        return $location;
    }

    return ALGOLIA_MY_PATH_TEMPLATE_PATH . $file;
}
add_filter( 'algolia_custom_template_location', 'load_autocomplete_template', 11, 2 );