Create custom components

This is for:

Developer

When using the Coveo JavaScript Search Framework, you will sometimes want to add your own custom components.

The term Component, in the context of the Coveo JavaScript Search Framework, relies on a few principles.

A component:

  • Must possess an ID property (a string that uniquely identifies the component and is closely linked to the CSS class that the framework will scan and recognize as a piece of markup which will contain logic and operate inside the framework).

  • Must register itself to the Coveo JavaScript Search Framework, using the utility function Initialization.registerAutoCreateComponent (see Initialization - registerAutoCreateComponent).

  • Must try to interact with the rest of the framework by binding handlers to Events.

  • Can possess an options property, which allows the component to be customized through data- HTML attributes (see ComponentOptions).

  • Should not, generally speaking, presume the existence of other components, as each component can be added in or removed from a given page.

TypeScript versus JavaScript

You can create your custom component using JavaScript or TypeScript.

While both methods are legitimate and will continue to always be supported, you’re encouraged to use TypeScript over JavaScript.

There are many advantages to using TypeScript:

  • TypeScript is a compiled language, meaning that common JavaScript issues will be caught by the compiler before arriving on your search page.

  • TypeScript is typed and object-oriented, making it friendlier than JavaScript for more developers.

  • The Coveo JavaScript Search Framework is already built using TypeScript.

  • You have access to the Coveo JavaScript Search Framework definition files, so you can get autocompletion as you code.

  • You can run the Coveo JavaScript Search Framework unit tests on your component, so you can confirm that you’re using the leading practices when coding.

  • TypeScript compiles into JavaScript, so you can easily reference it in your search page.

  • Once you have finished your component, if it’s already in TypeScript, you can easily do a pull request in the coveo-search-ui project to have your component be part of the product.

Component example

The following boilerplate gives you a basic custom component that’s correctly initialized by the Coveo JavaScript Search Framework, but doesn’t do anything.

For an example of a working custom component, see Introduction to JSUI Custom Components Tutorial: Recorded webinar.

Custom Component in TypeScript

import {
  Component,
  ComponentOptions,
  IComponentBindings,
  Initialization
} from 'coveo-search-ui';

export interface ICustomComponentOptions {
}

export class CustomComponent extends Component {
  static ID = 'CustomComponent';

  static options: ICustomComponentOptions = {
  };

  constructor(public element: HTMLElement, public options: ICustomComponentOptions, public bindings: IComponentBindings) {
    super(element, CustomComponent.ID, bindings);
    this.options = ComponentOptions.initComponentOptions(element, CustomComponent, options);
  }
}

Initialization.registerAutoCreateComponent(CustomComponent);

Custom Component in JavaScript

const CustomComponent = (function(_super) {
  __extends(CustomComponent, Coveo.Component);
  function CustomComponent(element, options, bindings) {
    _super.call(this, element, CustomComponent.ID, bindings);
    this.type = 'CustomComponent';
    Coveo.Component.bindComponentToElement(element, this);
    this.element = element;
    this.options = options;
    this.bindings = bindings;
  }

  CustomComponent.ID = 'CustomComponent';
  Coveo.Initialization.registerAutoCreateComponent(CustomComponent);
})(Coveo.Component);

To learn how to create your custom component, see Implement a custom component in JavaScript.