How to Embed the Stock Locator Tool

Modified on Wed, 03 May 2023 at 05:00 PM

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;

Parameters

searchParameters is a mandatory attribute for the tool and includes your preferences for the tools search functionality as well as the access token. The only mandatory field here is the token, as without it the tool won't be functional. Listed below are the fields:

Parameter	Type	Description	Default	Required?
token	string	Access token for Nexar API	N/A	mandatory
authorizedOnly	boolean	Whether to only return offers from authorized dealers	false	optional
country	string	Your user's ISO-3166-1 alpha-2 country code	US	optional
currency	string	Your user's ISO-4217 currency code	USD	optional
disableSearch	boolean	Whether to hide the search form	false	optional
enableManufacturerLink	boolean	Whether to enable direct-to-manufacturer links for parts in search results	false	optional
expandOfferTable	boolean	Whether to expand the offer table by default	false	optional
inStockOnly	boolean	Whether to only return parts that have stock available	false	optional
limit	number	How many parts to return in search results	10	optional
q	string	Default query to search for on page load	N/A	optional

Note: for the parameter "enableManufacturerLink", if true and there is a direct-to-manufacturer pdp link in the part data, the manufacturer name and mpn will link directly to the manufacturer pdp. If true and there is NO direct-to-manufacturer pdp link, the manufacturer name, and mpn will not link anywhere. If false, manufacturer name and mpn will link directly to Octopart pdp.

searchParameters = {{
    token: string,
    authorizedOnly?: boolean,
    country?: string,
    currency?: string,
    disableSearch?: boolean,
    enableManufacturerLink?: boolean,
    expandOfferTable?: boolean,
    inStockOnly?: boolean,
    limit?: number,
    q?: string,
}}

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.