Enhancing 404 Pages with Search in Umbraco

A well-designed 404 page enhances user experience when a requested page doesn’t exist. There are tons of examples of fun and creative error pages if you want to lighten up your user's mood. But you can also try to be helpful for users who just want to find the content they’re looking for.

404 errors can have many causes.

One common cause is a page being moved to a new URL. Luckily, Umbraco handles this automatically for us, creating the necessary redirects from the old url to the new one.

But they can also come from mistyped urls, or simply the user guessing the location of a page. This is where this idea comes in handy.

If you combine your error page, with search results based on the current context - in this example, the requested URL - the user might get lucky, and get pointed towards the content they were actually looking for.

Demo Time

To demonstrate for you, I've created a new site based on the infamous Umbraco Starter Kit, containing some demo content ready to get going.

Umbraco comes with Examine out of the box for searching the site content. And while that is often enough for most users, I can't resist using this opportunity to create some awareness for my package Full Text Search.

This package renders every page, and indexes all text content into Examine, including content referred from other pages or simply hardcoded into your templates. The result is a Google like index, where you can search for each and every word, the user sees on each page. It also makes more complex pages, like pages built with blocks in either Block List or Block Grid easier to search.

And it offers an easy API for creating the search, handling things like multi relevance, boosting, summarizing etc. for you without breaking a sweat.

Creating the 404 page

I created a document type to contain the page itself. To integrate with the starter kit, I added the existing Navigation Base composition. This is a composition content type found in the starter kit, that I use just to get the necessary properties needed to hide the page from the navigation. You can do what you need in your own project.

I also create a page in the Content Tree, for the 404 page, and to make it work as the actual 404 page, I add the necessary setup in my appsettings.json file.

{
  "Umbraco": {
    "CMS": {
      "Content": {
        "Error404Collection": [
          {
            "Culture": "en-US",
            "ContentKey": "4b7b8f17-9a64-4165-b753-9584ca36bc52"
          }
        ]
      }
    }
  }
}

Note, I don't think this way of adding 404 pages is very editor friendly. What if the editor deletes it and creates it over, then you have to change config of your site. Or what if you have multiple sites sharing the same language, then you can't configure 404 pages like this. I have a better way, which I might show in another blogpost.

Adding search results to 404 page

Instead of just showing an error, let’s make our 404 page actually useful — by adding smart search results!

In the template for the 404 page, I reused some HTML from existing templates to maintain consistency and reduce effort.. But instead of the content, I create a search result using Full Text Search.

To do this, I first need to inject in the Full Text Search helper using

@inject Our.Umbraco.FullTextSearch.Helpers.FullTextSearchHelper FullTextSearchHelper

and I can then go and create the search result using the helper.

To generate the search query, I extract the requested path and replace non-alphanumeric characters with spaces. For example, /this/path/does/not/exist becomes this path does not exist. I could also have looked at the referrer, or other data.

The search process is straightforward - simply passing the query to Full Text Search handles the rest. But there is several extra options, if you wish to configure it yourself.

If the search then returns any results, they get shown, leading the user to other related pages.

<section class="section">

    <div class="container">
        <div>
            <p>The page you were looking for, could not be found!</p>
            @{
                // generate search query from request path
                var query = Context.Request.Path.ToString().ReplaceNonAlphanumericChars(" ");

                // search for the generated query
                var search = FullTextSearchHelper.Search(query, Model.GetCultureFromDomains(), 1);

                @if (search.TotalResults > 0)
                {
                    <p>Maybe these pages can help you?</p>

                    <div class="blogposts">
                        @foreach (var result in search.Results)
                        {
                            <a href="@result.Content.Url()" class="blogpost">
                                <h3 class="blogpost-title">@result.Title</h3>
                                <div class="blogpost-excerpt">@result.Summary</div>
                            </a>
                        }
                    </div>
                }
            }
        </div>
    </div>

</section>

Conclusion

Now, if a user visits non-existing URLs like /produits, /products/unikorn, /blog/another, or /jan-skovgaard, they are guided toward relevant pages instead of encountering a dead end.

You can try this yourself! The source code, including uSync files, is available on GitHub for easy download and experimentation.