How to Embed the Stock Locator Tool

Modified on Mon, 06 Mar 2023 at 11:20 AM

Note: This guide assumes that you already have a Nexar account and application with a supply scope as well as a React project which you want to embed the tool into.

There are a couple of methods for embedding the tool the first of which is to drag and drop the component's folder from GitHub into your own project which will give you complete access to the code so that you can customize and adapt as you wish. Alternatively, the tool has been released as an NPM package that you can install.

Drag and Drop Method

To start you need to clone the GitHub repository by using the following command:

gh repo clone NexarDeveloper/nexar-gpa-tool

This repository includes an example Typescript React app that has the folder we need. Open up this repository in your favorite editor and look for the folder "react-app/src/nexar-stock-locator-tool". This contains all of the required files for the tool minus dependencies but including styling, custom hooks, and types.

Drag and drop this folder into your React project's "src" folder. Going into this folder inside of a fresh React project will result in a lot of missing dependency errors. To install them use the command below:

npm i --save-dev @types/styled-components @types/country-list @types/date-fns @types/react-highlight-words

Here are some links to each of these: styled-components, country-list, date-fns, and react-highlight-words.

This folder will export a React component "StockLocatorTool" which you can then import into any file you wish. Here's an example below that shows the most basic way to embed the tool.

import { StockLocatorTool } from "./nexar-stock-locator-tool/components/StockLocatorTool";

function App() {
  return (
    <StockLocatorTool
      searchParameters={{
        token:
          "Your Nexar access token here",
      }}
    />
  );
}

export default App;

NPM Package

To install the package into your project use the following command:

npm i @altiumnexar/stock-locator-tool

Once installed you can then import the component "StockLocatorTool" to the file you wish to.

import { StockLocatorTool } from "../node_modules/@altiumnexar/stock-locator-tool/dist";

function App() {
  return (
    <StockLocatorTool
      searchParameters={{
        token:
          "Your Nexar access token here",
      }}
    />
  );
}

export default App;

Access Token

Once you have got the tool imported into your file, to make it functional you will need to provide it with a Nexar access token. For development purposes you can generate one in the Nexar portal by going to Applications -> Details (for your app) -> Access Token -> Generate Token. Then you can paste that into the "token" sub-field of the "searchParameters" attribute. For production applications of the tool, tokens should be automatically fetched as needed. Access tokens are valid for 24 hours and should be cached accordingly.

In the GitHub repository the folder "express-app" contains an example that fetches tokens using the client credentials authorization flow and then provides them on localhost:4000. The folder "react-app" then fetches these tokens from localhost and uses them to query the API.