Implement search

November 11, 2013: we've just released this new and powerful Search feature that we use on this Documentation website. We would love to hear your feedback.

1. Setup

You can skip this step if you host your site in our hosting solution.

There are two available backends: Mongoid and Algolia.


For the mongoid backend, you just need to specify it in the require part of the Gemfile line:

gem 'locomotivecms-search', '>= 0.3.5', require: 'locomotive/search/mongoid'


Agolia is a very powerful new search engine. Our hosting platform uses it as the search backend.

In order to use it as backend, you have to specify it in the Gemfile like this:

gem 'locomotivecms-search', '>= 0.3.5', require: 'locomotive/search/algolia'

In addition to that, you also need to configure the algolia client. You can do it easiliy in a search.rb initializer:

require "activesearch/algolia/client"
ActiveSearch::Algolia::Client.configure("api_key", "app_id", "index_name")

If you develop your LocomotiveCMS sites with Wagon, you will have to install the following gem in the Gemfile of your site:

gem 'locomotivecms-search-wagon', '~> 0.3.5'

2. Mark your site content as searchable

Pages and content entries are searchable.

It's important to note that content entries and pages that were already on the database won't be indexed. They are indexed when saved.
Note: If you call the method reindex() on a content type, all entries older than the model definition will be reindexed.
Note: If you are adding the search gem in after having created content, you will need to create the indexes. From root path of your Locomotive engine: `rake db:mongoid:create_indexes`


By default, all the pages are searchable, except the 404 (page not found) one. However, you can mark any page as not searchable in Wagon:

title: This page won't show up in the search results
searchable: false
listed: true
This text won't show up neither.

or directly in the back-office from the edit page form.

Content entries

Any custom field of a model can be marked as "searchable". Thus, all the content entries of a model with a "searchable" field will be indexed and searchable.

It can done in Wagon like this:

name: Articles
description: Just a simple blog module
order_by: posted_at
order_direction: desc
slug: articles
label_field_name: title
- title:
    label: Title
    type: string
    hint: The title of the article
    searchable: true
- body:
    type: text
    searchable: true

It can also be done when editing any content type the LocomotiveCMS admin UI. You just have to unfold the extended options of any custom field.

3. Add the search form

Anywhere on your site you can add a simple form to fire a search. This could be done on the homepage, on a page you are inheriting from, on even on a snippet. Just add this code:

<form action="{% path_to search %}" method="GET">
  <label for="search">Search</label>
  <input type="text" name="search" id="search">
  <input type="submit" value="Search">

The important part is the action parameter, since it must point to the slug of your search results page.

4. Display the search results

Create a new page that will display your search results. Its code might be something like this:

This new page used to display the results should have search as the handle attribute, in order to work with the previous html form.
{% if params.query == '' or params.query == nil %}

  <p>Sorry, no results were found.</p>

{% else %}

  {% search_for params.query, per_page: 10, page: %}

    {% if result.total_entries == 0 %}

      <p>Sorry, no results were found.</p>

    {% else %}

      <p>{{ search.total_entries }} elements found.</p>

      {% for result in search.results %}
            # if the entry is a page or a content type with a title attribute
            <a href="/{{result.fullpath}}">{{ result.title }}</a>
            {{ result.highlighted.searchable_content }}
      {% endfor %}

      {% if search.total_pages > %}
          <a href="?page={{ | plus: 1 }}&query={{ params.query }}">Next page</a>
      {% endif %}

    {% endif %}

  {% endsearch_for %}

{% endif %}
© 2024 LocomotiveCMS Terms of use Privacy Policy
Back to top