How to Create a Speedy Site Search Worth Celebrating With Algolia

Eric Dugre — Mar 29, 2022

As an Xperience user, you may already be familiar with our Smart Search and Azure Search options, but perhaps you’re looking for something different. We’re happy to announce that we’re expanding our robust search functionality by adding Algolia to the family! This sleek search service has been climbing the ranks as one of the top search APIs in the world, and you can now easily create and configure Algolia search indexes in your Xperience websites!

Why Algolia?

If you’re not familiar with Algolia, you may be wondering why we’re integrating with Algolia when we already have Azure Search in Xperience. While they are both cloud services which offer similar features like analytics, one of Algolia’s stand out differences is its ease-of-use. With their simple, intuitive UI you can easily create and manage your indexes in record time. You get access to valuable analytics right out-of-the-box like “Top searches” and “Searches without results” so that you can immediately react to your customers’ search habits and improve their browsing experience.

While we’re talking about ease-of-use, I’d recommend checking out their GitHub page and the multitude of API clients they’ve provided. Whether you’re developing your applications with JavaScript, C#, Ruby, or on mobile devices, there’s an API for you to use. If you’re looking to add search functionality to your site, but you don’t want to spend countless hours writing code, Algolia is certainly the way to go. With their InstantSearch.js library, you can create a fully-functional, customizable search interface with hardly any code at all!

Something that I’m sure you’ll be happy to hear is that Algolia’s generally cheaper to use as well. With their pay-as-you-go pricing, you’re only charged for what you use. This means that starting your search implementation is incredibly easily as you don’t need to fork over large sums of money when you sign up, and for smaller websites you will notice much less strain on your bank account.

How the Xperience Algolia integration works

With this new integration, we’ve followed a code-first approach to ensure it’s as easy as possible for your developers to create and maintain Algolia indexes and search functionality. Unlike Smart Search and Azure Search, Algolia indexes are not created in the Xperience administration. In fact, while we do offer an optional Xperience module that provides useful information about your indexes, you don’t need to access the administration interface at all while creating Algolia indexes or developing your search functionality.

A single Algolia index, its indexed attributes, and their configuration are all stored in a single code file. When this code file is referenced by the Xperience project and your live-site project, the index is automatically created in Algolia and pages from your content tree are indexed as they are modified. On the live site, your developers use this class to retrieve strongly-typed objects within search results, making the display logic intuitive and easy to read.

Since your indexes are defined by code files, your developers can take advantage of source control services like GitHub to track versions of your indexes and restore previous versions as needed. Let’s say you recently modified several attributes in your Algolia index and using their insightful “Click position” analytics, you’ve found that the average visitor is now clicking on a search result that appears on the second page, rather than the first. The change you made seems to have affected the search result relevance negatively, but not to worry- just roll back to the previous version and it’s fixed!

Sounds amazing, how do I get started?

You’ll find everything you need to install the integration, create your indexes, and design your search functionality in our Algolia GitHub repository. Don’t feel like following our guide for creating faceted search, sending Personalization events, or anything else? No problem! Once your Algolia indexes are created, you can develop your search functionality any way you’d like using the Algolia documentation.

For now, let’s take a closer look at what an Algolia search model looks like. To start creating your index, you create a new class which inherits our AlgoliaSearchModel class, contains the RegisterAlgoliaIndex attribute, and an index code name:

[assembly: RegisterAlgoliaIndex(typeof(ArticleIndex), ArticleIndex.IndexName)]
namespace MySite
{
    public class ArticleIndex : AlgoliaSearchModel
    {
        public const string IndexName = "MySite-Articles";
    }
}

The AlgoliaSearchModel class adds some attributes to your Algolia index that are necessary for standard Xperience search functionality, such your page’s ClassName (page type) and the live site Url for the page. Now it’s time to start adding your own attributes to the index! Simply add as many properties to this class as you’d like, where the name of the property matches a standard page field or custom page type field. For example, in an index that stores articles, you may want the following attributes:

[assembly: RegisterAlgoliaIndex(typeof(ArticleIndex), ArticleIndex.IndexName)]
namespace MySite
{
    public class ArticleIndex : AlgoliaSearchModel
    {
        public const string IndexName = "MySite-Articles";

	    public string ArticleTitle { get; set; }

	    public string ArticleText { get; set; }

	    public string ArticleThumbnail { get; set; }

	    public DateTime ArticlePostDate { get; set; }

	    public int ArticlePostedBy { get; set; }
    }
}

When you create a new article in Xperience, the content of these fields will automatically be indexed in Algolia. To get the best search results, there are many things that should be configured in your Algolia index such as searchable attributes. You can do that directly from your code file using a variety of custom attributes!

The most important ones to define starting out are which fields will be searchable and retrievable, and whether certain attributes need to be converted into a URL when indexed. In the example we’re using, the ArticleThumbnail is a page attachment and so the indexed value of that attribute will be a GUID- not very useful. The Url attribute will automatically convert the attachment GUID into a live site URL when indexed, allowing you to display the image in Algolia using Display Preferences, and your developers don’t need to do any extra work when displaying the search results.

After configuring our attributes, the example above might look like this:

[assembly: RegisterAlgoliaIndex(typeof(ArticleIndex), ArticleIndex.IndexName)]
namespace MySite
{
    public class ArticleIndex : AlgoliaSearchModel
    {
        public const string IndexName = "MySite-Articles";

	[Searchable, Retrievable]
	public string ArticleTitle { get; set; }

	[Searchable]
	public string ArticleText { get; set; }

	[Retrievable, Url]
	public string ArticleThumbnail { get; set; }

	[Retrievable]
	public DateTime ArticlePostDate { get; set; }

	[Retrievable]
	public int ArticlePostedBy { get; set; }
    }
}

The final piece of the puzzle is telling Xperience which pages to include in your Algolia index. To do that, add one or more IncludedPath attributes to your search model as described in this section. Each attribute you add defines a section of your content tree to index, as well as the page types and cultures. Let’s say you have two sections for articles: “Product updates” and “Company updates.” To include articles from each section in one Algolia index, add two IncludedPath attributes:

[assembly: RegisterAlgoliaIndex(typeof(ArticleIndex), ArticleIndex.IndexName)]
namespace MySite
{
    [IncludedPath("/Product-Updates/%", new string[] { ProductArticle.CLASS_NAME })]
    [IncludedPath("/Company-Updates/%", new string[] { CompanyArticle.CLASS_NAME })]
    public class ArticleIndex : AlgoliaSearchModel
    {
        public const string IndexName = "MySite-Articles";

	[Searchable, Retrievable]
	public string ArticleTitle { get; set; }

	[Searchable]
	public string ArticleText { get; set; }

	[Retrievable, Url]
	public string ArticleThumbnail { get; set; }

	[Retrievable]
	public DateTime ArticlePostDate { get; set; }

	[Retrievable]
	public int ArticlePostedBy { get; set; }
    }
}

Searching your Algolia index

In the previous section we created a fully-functional Algolia index that contains two searchable attributes, a thumbnail image, and some other relevant data. Once you’ve created a few articles in Xperience, it’s time to start searching your articles! As I mentioned previously, there are many ways to create a search interface, including the simple, all-in-one InstantSearch.js library. For this example, we’ll show you just how easy it is to implement search in a .NET Core application.

To search an Algolia index, you need to use the SearchClient to obtain an instance of SearchIndex. You can easily gain access to the client in your Controllers by adding the following to your application startup logic:

public void ConfigureServices(IServiceCollection services)
{
    services.AddAlgolia(Configuration);
}

In your search Controller, inject Algolia’s SearchClient:

private readonly ISearchClient _searchClient;

public SearchController(ISearchClient searchClient)
{
    _searchClient = searchClient;
}

In your search action, get the SearchIndex by referencing your Algolia index name, which we’ve conveniently stored in our search model. Then, create a new Query containing your search term and search the index:

var searchIndex = _searchClient.InitIndex(ArticleIndex.IndexName);
var query = new Query(searchText);
var results = searchIndex.Search<ArticleIndex>(query);

The Hits of your search results will be objects of the ArticleIndex type, so it will be a breeze to display! Pass the Hits to your view, then loop through them to render a display template:

foreach (var item in Model.Hits)
{
    @Html.DisplayFor(m => item, nameof(ArticleIndex))
}

In the ArticleIndex.cshtml display template, you can now reference the properties you defined in ArticleIndex to display the results from Algolia:

@model MySite.ArticleIndex
@{
	var articleAuthor = UserInfo.Provider.Get(Model.ArticlePostedBy).FullName;
}
<div class="row search-tile">
    <div class="col-md-4 col-lg-3">
        @if (!String.IsNullOrEmpty(Model.ArticleThumbnail))
        {
            <a href="@Model.Url" title="@Model.ArticleTitle">
                <img src="@Model.ArticleThumbnail" alt="@Model.ArticleTitle" title="@Model.ArticleTitle" class="img-responsive" />
            </a>
        }
    </div>
    <div class="col-md-8 col-lg-9 search-tile-content">
        <h3 class="h4 search-tile-title">
            <a href="@Model.Url">@Model.ArticleTitle</a>
        </h3>
        <div class="search-tile-author">By @articleAuthor</div>
        <div class="search-tile-date">@Model.ArticlePostDate.ToShortDateString()</div>
    </div>
</div>

That’s all you need to start displaying results from Algolia! Of course, there’s lots of other cool things you can do with Algolia such as faceted search and logging events, so head over to the GitHub repository for further instructions. If you find something in the integration that you think we can improve on, please leave a GitHub issue for us!

Share this article on Twitter Facebook LinkedIn