1. Setup

There are two available backends: Mongoid and Algolia.

Mongoid

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'

Algolia

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.

Pages

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
fields:
- 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">
</form>

4. Display the search results

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

{% if params.query == '' or params.query == nil %}

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

{% else %}

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

    {% if result.total_entries == 0 %}

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

    {% else %}

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

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

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

    {% endif %}

  {% endsearch_for %}

{% endif %}