Create custom components

This is for:

Developer System Administrator
Warning
Legacy feature

This article pertains to the Coveo Hive framework which is now in maintenance mode.

Choose one of Coveo’s more modern, lightweight, and responsive libraries for any future search interface development. See the search interface Implementation guide for more details.

Coveo Hive components contain most, if not all, the search interface building blocks required for your implementation. However, you might come upon situations where you feel none of the default Coveo Hive components deliver the functionality you need, no matter the data source settings available for the component. You might then consider going outside the box and create a component of your own.

Before opting for this elaborate route, you should ensure that you don’t overlook simple alternatives and, if all else fails, that you get a clear understanding of the task you’re about to undertake.

To Create or Not to Create a Custom Component

You should only decide to create a custom Coveo Hive component after all existing alternatives have been exhausted. The following table lists a few common use cases where very simple alternatives to creating custom components are available.

Use Case Alternative Solution Documentation Article

Changing CSS applied to Coveo for Sitecore components

Use the Custom CSS classes data source field on the Coveo Search Interface component and define the style in the search interface layout file.

Applying a Coveo JavaScript Search Framework component option not available in the data source settings

Use the Additional Data Attributes data source field.

Pass Non-Fronted JavaScript Framework Properties to Hive Components

Leveraging a Coveo JavaScript Search Framework component option, property or method

Use the Initialization File Name data source field on the Coveo Search Interface component and create a custom initialization script.

Use Custom Initialization Scripts

Only changing the HTML of a Coveo for Sitecore component (no changes to the model are required)

Duplicate the Coveo for Sitecore component and edit the HTML of the duplicate .cshtml view file.

Duplicate a Coveo for Sitecore Component to Modify Its HTML

To summarize, use the following flowchart to determine your implementation method.

CustomComponentFlowchart

Custom Component Creation Process

You have a need for a search interface functionality where you have no choice but to create a custom component which interacts with Coveo for Sitecore components. Where do you go from here?

To be recognized and instantiated like native Coveo components are, your custom component needs to be registered to the Coveo JavaScript Search Framework. This involves writing some JavaScript code in a custom Coveo for Sitecore rendering view file. You can refer to the following Coveo JavaScript Search Framework documentation articles for help in writing this code:

Once you’ve created a custom component, you want to integrate it in the same way as a Coveo Hive component. Additionally, genuine Coveo Hive components are configurable through their related data source item. To be equally configurable, your custom component model needs to retrieve its settings the same way. As a result, a Coveo Hive component typically includes all the following parts:

  • a template item used for the component data sources

  • a ModelProperties class

  • a model

  • a rendering view file

  • a rendering item

Learn how to create template items, renderings, and models in Sitecore so you can use them in a Coveo Search Interface (see Integrate a custom component in Sitecore using the Coveo Hive framework).

Warning
WARNING

Don’t edit Coveo for Sitecore package items directly, as your modifications will be overwritten when upgrading Coveo for Sitecore. Instead, create all aforementioned parts in folders outside Coveo Hive folders. The custom Multi-Sort tutorial demonstrates this good practice (see Custom Multi-Sort Tutorial - Prepare the Ground).

Once all your custom component parts are created, you’re ready to insert your component in an existing search interface, either through a Coveo for Sitecore Placeholder Section or by creating a Coveo Hive Placeholder Extender item (see Insert Custom Components in an Existing Search Interface).

This section contains a tutorial on how to create all the aforementioned Coveo for Sitecore component parts for an example Multi-Sort custom component (see Create a Custom Coveo Hive Component - Multi-Sort Tutorial).

Finally, solutions to advanced component option fetching and setting scenarios are presented (see Reuse Properties From Another Existing Component).