Develop using the Interface X Components library

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:

  • x-components library (@empathyco/x-components (opens new window)): Interface X Components Vue.js library to implement out-of-the-box search UI components in a couple of minutes.

  • x-adapter (@empathyco/x-adapter (opens new window)): A set of tools to build the connection to any API so that both the request and the responses can be transformed as needed.

  • x-platform-adapter@empathyco/x-platform-adapter (opens new window): A default implementation of the Empathy Search Adapter (x-adapter) that connects to different Empathy Platform services (Search service, Tagging service, etc.).

  • x-types (@empathyco/x-types (opens new window)): The data model used in the X Components to define types.

  • reflect-metadata: Polyfill that allows the internal decorators of X Components to be used. This is only required if you use the Empathy search adapter (x-adapter).

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 reflect-metadata

Configuring the search adapter

Next, construct the search adapter. You will need the search adapter in the xPlugin configuration.

Empathy Search Adapter is a library for making it easier to consume search APIs. The project contains two main parts: an implementation to consume the Empathy Search API, and an interface that you can use to build your own adapter for other APIs.

It contains a specific builder that helps you to configure the Empathy Search Adapter. If you are using Empathy Search API, you need to only configure the values for instance, language, scope, and endpoint properties in the empathy-adapter.config.ts file.

// Import the search adapter and metadata
import 'reflect-metadata';
import { EmpathyAdapterBuilder } from '@empathyco/x-adapter';
// Construct the EmpathyAdapterBuilder
export const adapter = new EmpathyAdapterBuilder()
  .withConfiguration({ instance: 'my-instance-id' })
  .setLang('es')
  .setScope('demo')
  .setFeatureConfig('search', { endpoint: 'http://my-search-API-url' })
  .build();

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 EmpathyAdapterBuilder to communicate specifically with the Empathy Search API. If you are not using the Empathy Search API, you need to build your own adapter. See Configuring the search adapter.

    coding tip

    When using your own adapter, remember to configure the instance, language, scope, and endpoint methods.

  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:




Watch how our frontend Team Lead, Iván Tajes (opens new window), integrates the Interface X Components in a project from scratch.

We are cookie-less

This is a cookie-free area. Who needs cookies when you can have trust? Feel free to browse our site and the only cookies you need to worry about are the edible kind.