How to Customize the Extension

Algolia is a powerful tool that opens the door to a variety of search features. While you may want to customize your front-end integration, or maybe extend the back end features, modifications to the extension files are lost every time you update the extension.

In this guide you’ll learn how to create your own custom Magento module to customize your store the right way.

Before starting, please make sure you have the Algolia extension installed into your Magento Shop.

Introducing the CustomAlgolia extension

The best way to modify an extension is to override it. If you need to modify a template, for instance, you don’t modify it directly, but you create a new one and tell Magento to use your file instead of the original one. This new file will sit in a custom extension.

In order to avoid the boilerplate of creating a custom extension, we made one for you: CustomAlgolia extension.

It ships with a few code samples to help you.

Understanding the directory structure

To keep it simple, we’ll use the same data structure as seen in the Algolia extension.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
├── app
│   ├── code
│   │   └── local
│   │       └── Algolia
│   │           └── CustomAlgolia
│   │               ├── Model
│   │               │   └── Observer.php       <-- where you handle custom events
│   │               └── etc
│   │                   └── config.xml
│   ├── design
│   │   └── frontend
│   │       └── base
│   │           └── default
│   │               ├── layout
│   │               │   └── customalgolia.xml   <-- most important config file
│   │               └── template
│   │                   └── customalgolia       <-- where you override templates
│   │                       └── autocomplete
│   │                           └── page.phtml
│   └── etc
│       └── modules
│           └── Algolia_CustomAlgolia.xml
├── js
│   └── customalgolia                           <-- where you override JavaScript
│       └── autocomplete.js
├── skin
│   └── frontend
│       └── base
│           └── default
│               └── customalgolia
│                   └── customalgolia.css

Overriding a template

For this example we’re going to override the template named page.phtml used for autocomplete. This template is used to display the CMS pages matching the query.

Step 1: Create your new template

Copy the chosen template app/design/frontend/base/default/template/algoliasearch/autocomplete/page.phtml to app/design/frontend/base/default/template/customalgolia/autocomplete/page.phtml. You can now modify the new file according to your needs.

Step 2: Let Magento know about it

Open up the configuration file customalgolia.xml and add the following code block. It will tell Magento to use your new template whenever it requires the template named “algolia-autocomplete-page”.

1
2
3
4
5
<reference name="algolia-autocomplete-page">
    <action method="setTemplate">
        <template>customalgolia/autocomplete/page.phtml</template>
    </action>
</reference>

The important part here is that you reference the correct name of the template. The template name can be found in the extension configuration file. For our current example, we’ll find this code block:

1
<block type="core/template" template="algoliasearch/autocomplete/page.phtml" name="algolia-autocomplete-page"/>

Adding a new JavaScript file

Via the custom extension you can add a new JavaScript file to your store. In this file you can define custom methods, which can be used to modify instant search or autocomplete functionality.

Step 1: Create your new file

Create a new file js/customalgolia/custom_js.js. You can now modify the new file according to your needs.

Step 2: Let Magento know about it

Open up the configuration file customalgolia.xml and add the following code block. It will register the new file.

1
2
3
4
5
6
7
8
9
10
11
<layout>
    <algolia_search_handle>
        <reference name="head">
            <!-- [...] -->
            <action method="addJs">
                <script>customalgolia/custom_js.js</script>
            </action>
        </reference>
    </algolia_search_handle>
</layout>

Adding a new JS file and using the front-end custom events is preferred way to modify the front-end functionality before overriding JS files.

Overriding a JavaScript file

Overriding JavaScript works very much the same way as overriding a template.

In this example we’re going to override the instantsearch.js file which declares widgets and deals with the configuration of the instant results page. See the Instant search page customization for further details.

Step 1: Create your new file

Copy the original file js/algoliasearch/instantsearch.js to js/customalgolia/instantsearch.js. You can now modify the new file according to your needs.

Step 2: Let Magento know about it

Open up the configuration file customalgolia.xml and add the following code block. It will de-register the original file and register yours.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<layout>
    <algolia_search_handle>
        <reference name="head">
            <!-- [...] -->
            <action method="removeItem">
                <type>js</type>
                <name>algoliasearch/instantsearch.js</name>
            </action>
            <action method="addJs">
                <script>customalgolia/instantsearch.js</script>
            </action>
        </reference>
    </algolia_search_handle>
</layout>

Staying up to date

If you override a file, you won’t get new bug fixes or features as you upgrade the extension. You should have a look at the changelog of each release and see if there was anything to change in your custom file.