Start your content search
3 min read

Develop using the Interface X Components library

In this tutorial, you’ll learn the basics to integrate the Interface X Components library in your own project to craft enticing Vue search experiences for your commerce store in a matter of minutes.

interact

If you are looking to use the ready-to-go project Interface X Archetype as your starting point, see Develop using Interface X Archetype.

For this tutorial, the Empathy Search API is used, but you can use any search API. This step-by-step guide requires a knowledge of JavaScript and Vue.js.

You can find the X Components library in the Interface X open source project in GitHub (opens new window).

Before you begin

To integrate the X Components in a frontend UI, you need:

  • Empathy Search API to retrieve search data (or any other search API)
  • A search adapter to communicate with the search API.
  • Your commerce store built on a Vue project, or on a React project using the React Wrapper (opens new window).
Steps to integrate the X Components in your project:
  1. Install project dependencies.
  2. Configure the search adapter.
  3. Configure the xPlugin.
  4. Install and initialize the xPlugin.

Installing the dependencies

To build your search and discovery UI, the following project dependencies are required:

Install the project dependencies via npm as follows:

//Install the dependencies via npm.
npm install --save @empathyco/x-components @empathyco/x-types @empathyco/x-adapter-platform

Configuring the search adapter

You will need the search adapter in the xPlugin configuration.

There are two libraries for making it easier to consume search APIs. The @empathyco/x-adapter (opens new window), which is the interface you can use to build your own adapter for other APIs, and the @empathyco/x-adapter-platform (opens new window), which is the implementation to consume the Empathy Search Platform API, and it can be extended in case your search API is similar to it.

warning

If you do not use the Empathy Search API, you need to build your own adapter.

For more information, see the Empathy Search Adapter (opens new window) and Empathy Platform Search Adapter (opens new window) libraries.

Configuring the plugin

Plugins are self-contained code that usually add global-level functionality to Vue projects. They’re specifically objects that expose an install method, allowing you to keep your components clear and small.

The xPlugin is designed to connect the X Components to the Vue components in your project.

Import the xPlugin in your Vue instance.

import Vue from 'vue';
import { xPlugin } from '@empathyco/x-components';
import { adapter } from './my-adapter';
import { store } from './my-store';

Then, configure the xPlugin. It has two key options you need to configure:

  1. Adapter: A search adapter is required to connect and communicate with the search API. Here you’re using the XAdapterPlatform to communicate specifically with the Empathy Search Platform API. If you are not using the Empathy Search Platform API, you need to build your own adapter. See Configure the search adapter.

  2. Store: The Vuex store. If you use a store for Vuex, you need to provide the store you’re currently using for your project to the Vue instance.

    warning

    If you don’t provide any parameters for the store, a default store is created automatically. Leave the store blank only if you’re not using any store for Vuex.

Installing and initializing the plugin

Finally, the last step is to install and initialize the xPlugin. You need to do this in the main.ts or main.js file of the project.

//Initialize the plugin. Pass the search adapter and the store you use as parameters.
Vue.use(xPlugin, { adapter, store });

Next steps

Once you have integrated the Interface X Components in your project, you're ready to start building your search and discovery UI:

Cookie-Less