@epigraph/configurator
v1.13.0
Published
Epigraph Configurator web component.
Downloads
510
Keywords
Readme
INTRODUCTION
The "Epigraph Configurator" web component is meant to be a wrapper around "Epigraph's Configurator Core" web component. The Configurator web component aims at providing a fully functional configurator for our clients with a default UI along with some customisation options. Even though we provide a default UI for our clients, the goal is always to allow the client developers to expand on top of these existing functionalities or even replace it entirely.
Some Useful Links:
SETTING UP DEV ENVIRONMENT (For Epigraph Devs Only)
To setup a dev environment please refer to this repository tagged below, which aims to automate the process as mugh as possible:
USAGE
Importing the Web Component
In order to import the web component on your page, you must import the the script in your head tag:
<head>
<!-- Import other scripts above and below this. -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@epigraph/configurator"></script>
</head>Once the web component is imported, there are two primary modes that we intended the Epigraph Configurator to be used as. Irrespective of the mode that you choose to setup the configurator in, we have tried to make the process as similar as possible.
With the default UI:
This is the usage that we mostly expect our client to use. This is the quickest mode to get started with embedding a configurator on any website that runs on modern browsers.
To start with setting up a fully functional product configurator on your website:
<!-- A client-access-key can only be linked to a single domain, so if you would like to whitelist your staging URL as well, please request a separate key for the same. -->
<epigraph-configurator id="wcEpigraphConfigurator" client-access-key="<key-provided-by-epigraph>"/></epigraph-configurator>Without UI:
This mode allows the developers to use only the configurator core and build a UI on top of it from scratch. Even though we allows our customers to embed the epigraph-configurator-core directly on their websites, we do not recommend that. If you already have a custom UI in mind for what you wish for the configurator to look like. The recommended way is to import the epigraph-configurator web component on the webpage and set it's mode to disable UI.
<!-- A client-access-key can only be linked to a single domain, so if you would like to whitelist your staging URL as well, please request a separate key for the same. -->
<epigraph-configurator
id="wcEpigraphConfigurator"
client-access-key="<key-provided-by-epigraph>"
disable-ui
></epigraph-configurator>Working with the API
Once you choose to move forward with a configurator mode, use the Core API documentation to interact with the configurator and expand on top of it's capabilities.
Epigraph API exposes it's core's API on the HTML element itself and the uses the same internally as well. To access the same, all you should have to do it keep a reference to the web component that was attached to the webpage:
<head>
<!-- Import other scripts above and below this. -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@epigraph/configurator"></script>
</head>
<!-- A client-access-key can only be linked to a single domain, so if you would like to whitelist your staging URL as well, please request a separate key for the same. -->
<epigraph-configurator
id="wcEpigraphConfigurator"
client-access-key="<key-provided-by-epigraph>"
></epigraph-configurator>
<script>
const EPIGRAPH_CONFIGURATOR_WC = document.querySelector(
"wcEpigraphConfigurator"
);
const IS_API_INITIALISED = EPIGRAPH_CONFIGURATOR_WC.api.isReady(); // returns true if the api is avilable to be used
// TODO: We are even planning to add an "coreApi:ready" event on the configurator web component for you to subscribe to
if (IS_API_INITIALISED === false) {
// You could choose to abort the process and remove the web component if the api isn't available.
}
// If the API was initialised and ready to be used. For example:
// EPIGRAPH_CONFIGURATOR_WC.api.<anyMethodFromTheApi>();
</script>