Skip to main content

Introduction

The "Epigraph Configurator" web component aims at providing a fully functional configurator for our clients with a default UI along with a wide range of customisation options. Even though we provide a default UI, the goal is always to allow the developers to:

  1. Expand on top of the existing functionalities or,
  2. Even replace it entirely.

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 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 mode 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.

<!-- 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.

disable-ui (flag) - disables or enables the default UI for this configurator.

Visit this link for a list of all the attributes

<!-- 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​

API reference available here: API Reference

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 is exposed on the web component itself and can be accessed by keeping a reference to the web component in the DOM.

For eg. if you added the id attribute to the web component while attaching it to the DOM, you can access the API like this:

// The id itself could be anything. This is only for demonstrating the use case
const EPIGRAPH_CONFIGURATOR_WC = document.getElementById("wcEpigraphConfigurator");
EPIGRAPH_CONFIGURATOR_WC.api.core.<anyMethodFromTheApi>(); //

All API methods are documented here

DEMO CODE​

<head>
    <!-- Import other scripts above and below this. -->
    <script src="https://cdn.jsdelivr.net/npm/@epigraph/configurator"></script>
</head>

<!-- A container around the web component is completely optional but we highly recommend it. -->
<div class="epg-configurator-container">
    <!-- A client-access-key can only be linked to a single domain. 
    So if you would like to whitelist more than one domain, 
    please request a separate key for the each. -->
    <epigraph-configurator 
        id="wcEpigraphConfigurator" 
        client-access-key="<key-provided-by-epigraph>">
    </epigraph-configurator>
</div>

<script>
    const EPIGRAPH_CONFIGURATOR_WC = document.getElementById("wcEpigraphConfigurator");

    EPIGRAPH_CONFIGURATOR_WC.addEventListener(
        "coreApi:ready", 
        function (event) 
        {
            console.log("Core API successfully initialised.");

            /** Start setting up the behaviour of the website 
             * if the configurator was successfully initialised 
             * without any errors
             */
            EPIGRAPH_CONFIGURATOR_WC.api.core.<anyMethodFromTheApi>();
        }
    );

    EPIGRAPH_CONFIGURATOR_WC.addEventListener(
        "coreApi:failed", 
        function (event) 
        {
            console.error("Failed to initialise core api.");

            /** Gracefully exit and probably show a modal to the user 
             * with a proper reasoning for the API to not initialise. 
             * This could be a hardware limitation too and 
             * not just a problem with the configurator web component
             */
            console.error(event.details);
        }
    );
</script>

If you do not wish to use the "coreApi:ready" event listeners. Optionally, you could even use the 'isReady' (boolean) property of the API to figure out when the API becomes available to use.

var IS_API_INITIALISED = false;

while (IS_API_INITIALISED === false) 
{
    IS_API_INITIALISED = EPIGRAPH_CONFIGURATOR_WC.api.isReady();

    // Do all the setup to be done once the API is ready.

    // If the API was initialised and ready to be used. For example:
    EPIGRAPH_CONFIGURATOR_WC.api.core.<anyMethodFromTheApi>();
}

All API methods are documented here