Configuration API – reference

What is Configuration API? It is our new API introduced in Copilot v2 which aims to provide advanced automation capabilities.

Use cases:

• Client Wizards
• Automated site generations workflows

How it could work:

• Inject our App as hidden iframe (enable client side CSS building)
• Use our Configuration API (Broadcast Channel API under the hood)

Why Client side CSS build via iframe

CSS is front facing of application and building it server side is limited as server has less clue around computed styles than client side methods. Under the hood we use libraries for color manipulation, contrast checking, and have evaluator which enables programmatic contrast relations and this things could only be done at the front so we could use browser as tool to evaluate computed values.

Initializing communication channels

This is like telling to browser to make cross tab channels to send/get data. After defining we could send data using .postMessage or subscribe to listen data on some channel.

/*1. Push user choices from your configuration to our app*/
const setChannel = new BroadcastChannel("headspin_configurator_api_set");

/*2. Get configuration API current data*/
const getChannel = new BroadcastChannel("headspin_configurator_api_get");

/*3. Catch improper commands, use it in dev to have feedback around allowed types*/
const errChannel = new BroadcastChannel("headspin_configurator_api_error");

Set Channel

After defining channels to communicate, we could now tell app to change configuration and save data via setChannel:

setChannel.postMessage({
  action: "brandColor",
  param: "#facc15"
});
/*<param/> any valid color*/

setChannel.postMessage({
  action: "neutralColor",
  param: "#facc15"
});
/*<param/> any valid color*/

setChannel.postMessage({
  action: "projectRadiusPreset",
  param: "medium"
});
/*<param/> none | small | medium | large | full*/

setChannel.postMessage({
  action: "componentSpacingPreset",
  param: "m"
});
/*<param/>  xxs | xs | s | m | l | xl | xxl*/

setChannel.postMessage({
  action: "sectionSpacingPreset",
  param: "m"
});
/*<param/>  xxs | xs | s | m | l | xl | xxl*/

setChannel.postMessage({
  action: "fontSizePreset",
  param: "m"
});
/*<param/>  xxs | xs | s | m | l | xl | xxl*/

setChannel.postMessage({
  action: "lineHeightPreset",
  param: "m"
});
/*<param/>  xxs | xs | s | m | l | xl | xxl*/

setChannel.postMessage({
  action: "disableEnableLineHeight",
  param: "disable"
});
/*<param/>  disable | enable */

setChannel.postMessage({
  action: "themeMode",
  param: "light"
});
/*<param/>  light | dark */

setChannel.postMessage({
  action: "saveApp",
  param: "save"
});
/*<param/>  save */

Get configuration current state app data

If we need to sync wizard with theme generator, we could use getChannel for that task. Getting all configuration API current state data is easy as

/*1. === We need to subscribe to listen response*/
getChannel.onmessage = (event) => {
    console.log(event.data)

};
/*2. === Let's grab data*/
getChannel.postMessage({
    action: "get",
});

/* 
=== This should log something like ===
{
  "data": {
    "brandColor": "#0090ff",
    "neutralColor": "#8e8c99",
    "projectRadiusPreset": "medium",
    "componentSpacingPreset": "m",
    "sectionSpacingPreset": "m",
    "fontSizePreset": "m",
    "lineHeightPreset": "m",
    "disableLineHeight": true,
    "themeMode": "light"
  }
}
*/

Error Channel

We could subscribe to error channel to listen for incorrect data setting:

/*1. === We need to subscribe to listen response*/

  errChannel.onmessage = (event) => {
      console.log(event.data)
  };
  
/*2. === We could get feedback if doing something wrong for example setting fontSizePreset to numerical value 100px would tell us that under that action allowed values are xxs-xxl
{
  data: {
    action: "action::fontSizePreset",
    context: "allowed values: xxs | xs | s | m | l | xl | xxl"
  }
}
*/