Hooks & Events

The following hooks are available as part of Search Plus :

Allows developers to add their own custom content mappings
Allows developers to alter the basic mapping return

searchPlus_addAlgoliaMapping #

The add algolia mapping allows developers to add completely custom content mappings to Search Plus.


The add algolia mapping has no parameters.


The hook needs to return an array (or an array of arrays) holding the data about the custom mapping. The return array must have the following attributes : name, handle, description and method.

For example :

public function searchPlus_addAlgoliaMapping()
        $ret = [];
        $ret['name'] = 'Example Custom Mapping';
        $ret['handle'] = 'example_custom';
        $ret['description'] = 'A custom mapping for search plus';
        $ret['method'] = 'example.testMapping';
        return $ret;

Method naming is important The method name is made up of two parts - the plugin class, and the specific method name. eg. For a plugin service called ExampleService, and a method name of testMapping, our method name would be: example.testMapping


In addition to the actual hook, you must implement the method as you've set in your return. The methods are called with the element being mapped.

From the example above, in our ExampleService, and the method testMapping it'd look something like this :

public function testMapping($entry)
    $ret = [];

    $ret['objectID'] = $entry->id;
    $ret['title'] = $entry->title;
    $ret['activityId'] = $entry->id;
    $ret['id'] = $entry->id;
    $ret['slug'] = $entry->slug;
    $ret['url'] = $entry->url;
    $ret['uri'] = '/' . $entry->uri;
    $ret['somethingCustom'] = 'exampleOne';
    // .. More custom data ..

    return $ret;

Need to test the output You can see what the mappings will output at any time from the Search Plus > Settings > Mappings > Test Mapping area

searchPlus_alterBasicItemMapping #

The alter basic item mapping gives developers a quick way to alter the return from the basic mapping before it's passed to Algolia.

This can be very useful if the basic mapping is close to the required data format, and just needs some small tweaks for your specific front-end setup. A common setup for this might be to limit a loop of images to just the first featured asset.


The hook is called with two parameters, and expects an array returned.

mappedData array
The mapped data from the basic mapping in a clean array, just before it's about to be passed to Algolia.
originalElement element
The original element that has been used for the mapping. Useful if you need to extra any extra data from the element.


The hook needs to return the array of mapped data. This will be revalidated on return.


If we had an asset field called productImages and we want to have an attribute with just the first image from that loop, we'd do it like this :

public function searchPlus_alterBasicItemMapping($mappedData, $orginalElement)
    // Add a featured image marker
    if(isset($mappedData['productImages'][0])) {
        $mappedData['productImageFeatured'] = $mappedData['productImages'][0];
    return $mappedData;