Result Layouts

The Coveo JavaScript Search Framework supports three different search result layouts: List, Card, and Table.

  • List Layout

  • Card Layout

Coveo JavaScript Search Framework 1.2126.4 (February 2017)

  • Table Layout

Coveo JavaScript Search Framework 2.2900.23 (July 2017)

Enabling Many Result Layouts

Coveo JavaScript Search Framework 2.3826.10 (February 2017)

It is possible to include many result layouts in your search page, for instance if you want to allow your end users to switch to the format they are most comfortable with.

Step 1 - Add Distinct ResultList Components

For each search result layout you want to activate in your search interface, include a distinct ResultList component in your page and set its layout option to the desired value (either list, card, or table).

To activate the List, Card, and Table search result layouts in your search interface, you must include three distinct ResultList components in the markup of your page:

<body id="search" class="CoveoSearchInterface">
  ...
  <div class="coveo-main-section">
    ...
    <div class="coveo-results-column">
      ...
      <div class="CoveoResultList" data-layout="list"></div>
      <div class="CoveoResultList" data-layout="card"></div>
      <div class="CoveoResultList" data-layout="table"></div>
      ...
  </div>
</body>

You can embed result templates within any of your ResultList components (see Using Result Templates). A given result template can only be evaluated when its parent ResultList is being displayed in the search interface.

Step 2 - Add a ResultLayoutSelector Component to Your Page

Before the February 2018 Release (v2.3826.10), the ResultLayoutSelector component was named ResultLayout.

While the old component name is still supported, it is considered a good practice to use the new one.

To be able to switch between your many ResultList components, you must add a ResultLayoutSelector component to your page. This component displays a result layout selector in your search interface, which your end users can use to select their preferred viewing method.

You must place your ResultLayoutSelector component in the coveo-result-layout-section element, which you can find in the coveo-results-header element, present in the default search page.

For best results, place the ResultLayoutSelector component between the coveo-summary-section and the coveo-sort-section:

<body id="search" class="CoveoSearchInterface">
  ...
  <div class="coveo-main-section">
    ...
    <div class="coveo-results-column">
      ...
      <div class="coveo-results-header">
        <div class="coveo-summary-section">
          ...
        </div>
        <div class="coveo-result-layout-section">
          <span class="CoveoResultLayoutSelector"></span>
        </div>
        <div class="coveo-sort-section">
          ...
        </div>
      </div>
    </div>
    ...
  </div>
</body>

The ResultLayoutSelector component populates itself automatically using all ResultList components that have a valid data-layout attribute.

If you followed the previous steps carefully, you should now see a result layout selector in the result header of your search page:

If you remove one of the ResultList components from your page markup (e.g., the ResultLayoutSelector whose layout option is set to table), the result layout selector only displays the remaining available result layouts:

You can interact with the result layout selector to switch between available layouts. If you do not embed your own result templates in the ResultList components, the default templates apply.

Setting the Default Layout for Tabs

You can use the layout option of the Tab component to specify which result layout should apply by default when a user selects a specific tab in your search interface.

The default value of the layout option is list.

You want to apply the Card result layout whenever a user selects the tab whose data-id is People. Assuming that the Card result layout is available in your search interface, you modify your tabs as such:

<body id="search" class="CoveoSearchInterface">
  <div class="coveo-tab-section">
    <a class="CoveoTab" data-id="People" data-caption="People" data-expression="@objecttype==user" data-layout="card"></a>
    <a class="CoveoTab" data-id="All" data-caption="All"></a>
  ...
</body>

In the example above, the layout value of the tab whose data-id is All defaults to list.

If you do not wish to include Tab components in your search page, you can instead use the changeLayout method of the ResultLayoutSelector component in an afterInitialization event handler to select a specific “default” result layout programmatically (see Events):

const root = Coveo.$$(document).find('#search');
Coveo.$$(root).on('afterInitialization', () => {
  Coveo.get(Coveo.$$(root).find('.CoveoResultLayoutSelector')).changeLayout('card');
});
Coveo.init(root);