Create Custom Components

Coveo for Sitecore 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 for Sitecore 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 for Sitecore 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.

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 have created a custom component, you want to integrate it in the same way as a Coveo for Sitecore Hive component. Additionally, genuine Coveo for Sitecore 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 for Sitecore 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 Coveo for Sitecore Hive Framework).

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 for Sitecore Hive Component - Multi-Sort Tutorial).

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

What's Next for Me?