Custom Content Mapping

Content mapping is key. It's how Algolia see's the Craft content.

We include a basic mapping as part of the base install, and that can be great for most use cases. If you've got a more specific requirement, you can add your own custom mappings too.

Adding a custom mapping lets you have complete control over how your content is exposed to Algolia, and do anything else you might want to the content before it's indexed by Algolia. This also affects how the content returns from Algolia later.

Adding a custom mapping with the hook #

Adding a custom mapping is done via a hook called searchPlus_addAlgoliaMapping.

searchPlus_addAlgoliaMapping

Allows developers to add their own custom mappings to Search Plus View specific hook usage and requirements

This hook has a few required return details. Check out the hook usage details for specifics

Formatting your mapping return #

The custom mapping needs to return a nicely formatted array of the content to be passed back to Algolia.

Mapping Return Array Format

objectID required

The unique id for this item. For most setups this can be just the elementId for the item. (Note the capitalisation of the param - Algolia requires it to be exact)

(any other keys) open ended

All other parameters for the item. This can be as simple as title, uri, to arrays for geocoded items like _geoloc, or can be nested sub-arrays.

Sample Return Array

You can return any array items you'd need, as long as you include the required objectID key.

For example :

{
  "objectID": 42,                 // record identifier
  "title": "Breaking Bad",        // string attribute
  "episodes": [                   // array of strings attribute
    "Crazy Handful of Nothin'",
    "Gray Matter"
  ],
  "like_count": 978,              // numerical attribute
  "avg_stuff": 1.23456,
  "actors": [                     // nested objects attribute
    {
      "name": "Walter White",
      "portrayed_by": "Bryan Cranston"
    },
    {
      "name": "Skyler White",
      "portrayed_by": "Anna Gunn"
    }
  ]
}

What the Basic Mapping does

For reference, the basic mapping returns in the following format :

{
    "objectID": 42,
    "title": "Breaking Bad",
    "id": 42,
    "locale": "en_us",
    "localeEnabled": 1,
    "uri": "shows/breaking-bad",
    "absoluteUri": "/shows/breaking-bad",
    "url": "http://example/shows/breaking-bad",
    "slug": "breaking-bad",
    "enabled": 1,
    "archived": 0,
    "sectionId": 1,
    "typeId": 1,
    "postDate: 1450788685,
    "dateUpdated": 1450788685,
    "authorId": 4,
    "authorName": "Vince Gilligan",

    // Custom fields
    "someField": "some content..",
    "matrixField": [
        {
            "matrixId": 43,
            "actorName": "Byran Cranston",
            "name": "Walter White"
        },
        {
            "matrixId": 44,
            "actorName": "Anna Gunn",
            "name": "Skyler White"
        }
    ],
    "moreFields": "Etc.." 
}

Testing the Mappings #

To help your setup and testing, you can directly test the output of any mapping from within the CP, without having to trigger a new population.

To test your mapping go to : Search Plus > Settings > Mappings and if you're using the add mapping hook correctly, your custom mapping will be listed there. You can test and review the exact output from the Test Mapping action.