The Client Graphene Helpers library is a wrapper around the advancedcommerce library GrapheneHC to provide type safety, consistency and readability when implementing.

Install

Install with npm:

npm install --save-dev @webselect/client-graphene-helpers

Get Started

Check out advancedcommerce's documentation for information on the library.

[!NOTE] You will need a login which can be sourced from the vault.

Functions

• Track
• initLoad
• initFetch
• loadNewPage
• initAutocomplete

| Property | Type | Description | | --- | --- | --- | | requestId (optional) | String | Number | This is an optional value you that provide to the API. The API will return this value back with the response. | | scope | String | Defines the type of tracking event being recorded. The allowed values are: view, basket, order | | action | String | A string that defines the type of tracking event being recorded. The allowed values are dependent on the event:basket: add, removeorder: add, cancel, return | | data | Object | An object which contains information specific to the current event. The allowed values are dependent on the event:basket: TrackingEventDataFor<'basket'>order: TrackingEventDataFor<'order'> |

Example

Below is an example of the view tracking event that would be fired on page load to send the product ID of the viewed product.

NOTE: It is important to state that the product ID should be the ID that is used within Graphene, and not the SelectCommerce ID.

import { track } from '@webselect/client-graphene-helpers';

track({
    scope: 'view',
    action: 'add',
    data: {
        product_id: <graphene-product-id>,
    },
});

| Property | Type | Description | |---|---|---| | template | Object | An object that takes two parameters:id (Required): The ID of the required template, typically representing a category or search. target (Required): This is a CSS selector that defines the DOM element where the results will be placed. | | pageContext | Object | An object defining various details about the current page. These include:categoryId (Required): The ID of the category for the current page.languageId (Optional): This is only required if multiple languages are defined.currencyId (Optional): This is only required if multiple currencies are defined. | | elements (Optional) | Array | An array of elements. Find more detailed explantion of Templates vs Elements here. | | beforeLoad | () => void | A callback Function which can be used before the response is requested. | | afterLoad | (response: LoadResponse, isFirstResponse: boolean) | A callback Function which you will use to process the response.The callback function will receive a response variable which will contain the JSON response from the Query API.There is also a Boolean value that will return true if this is the first time this callback has been returned. |

Example

Below is an example of how to execute the initLoad function.

import { initLoad } from '@webselect/client-graphene-helpers';

initLoad({
  template: {
      id: <page-type>,
      target: <html-selector>,
  },
  pageContext: <page-context>,
  afterLoad: (res: LoadResponse) => {
    // Execute any logic that needs to be applied after load
  },
});

| Property | Type | Description | |---|---|---| | pageNumber | Number | Provide a page number so that Graphene can succesfully return the correct set of lazy loaded data. | | setPageUrl | Boolean | Depending on the value provided Graphene will update the URL query parameter with the current loaded page. |

Example

Below is an example of how to execute the loadNewPage function.

import { loadNewPage } from '@webselect/client-graphene-helpers';

const loadMoreProducts = async () => {
    const currentPage = // Get current page from query paramaters (1)
    try {
        const response = await loadNewPage({
            pageNumber: +currentPage + 1 // Increment the page value so that Graphene returns the next set of product data,
            setPageUrl: true // Update the query parameter to the new value,
        });

        // Get the returned template HTML
        const template =
            response.templates.category || response.templates.search;

        if (!template) return;

        // Use the new HTML as you wish and execute any other logic that needs to be applied.
    } catch (ex) {
        console.error(ex);
    }
};

Although in the majority of cases the Standard Query API is recommended, there are some scenarios where you might require the Fetch, the advanced query API.

The need for using this arose when some issues with the way the load function and the Flickity carousel plugin conflicted. Andy explained the differences here:

Load should be the default starting point. If that works then use it. Basically load gathers some extra data to send automatically (the correct userID, personal search history (we store it with the user rather than on our server as it’s less intrusive) etc). It also handles some special cases automatically (ensuring that the PLP reloads only the necessary bits when you apply filters etc).

Fetch is a lower level version of the same which does less automatically. So if for some reason load is being too clever, you can fall back to fetch and recreate only those bits of load you want.

Example

Below is an example of how to execute the loadNewPage function.

import { initFetch } from '@webselect/client-graphene-helpers';

initFetch({
  format: 'html',
  pageContext: {...},
  elements: ['element-1-id', 'element-2-id'],
  afterFetch: (response) => {
    // Using the initFetch endpoint the elements will not automiically be applied to the 
    // ID (as we dont provide one in this function) so you will need to append the HTML yourself.

    // Apply any other logic after.
  },
});

| Property | Type | Description | |---|---|---| | inputSelector | String | This property identifies the search input that Autocomplete will bind to. | | outputSelector | String | This property identifies the output within which Autocomplete will publish results. |

Example

Below is an example of how to execute the initAutoComplete function.

import { initAutocomplete } from '@webselect/client-graphene-helpers';

initAutocomplete({
    inputSelector: 'input-selector',
    outputSelector: 'output-selector',
});