@axa-ch/bifrost

integration framework for aem

Usage no npm install needed!

<script type="module">
  import axaChBifrost from 'https://cdn.skypack.dev/@axa-ch/bifrost';
</script>

README

Bifröst - a useful AEM integration framework

An integration framework for AEM. It's like a multicolored bridge between SPAs and AEM. It will provide localhost dev environment for SPAs and integration interfaces so that they can run inside a multi-spa enviroment

Detailed documentation can be found here: https://confluence.axa.com/confluence/x/4samCw

Requirements

The client SPA have to be able to deal with standard ES6 Modules.

Authorisation

Bifrost offers three methods used under the hood to provide your POD's SPA with an Access Token:

  • <iframe>
  • Redirect
  • XMLHttpRequest

Iframe

This method does not leave your POD's page, instead an authorization <iframe> is overlaid above the whole page and prompts the user for login.

Redirect

This method leaves your POD's page and redirects to an authorization page to prompt the user for login.

XMLHttpRequest

This method performs an asynchronous network request to authorise you POD.

Dev stuff

To start the mocking api, please run npm run api. Default port is 8080. If you need another port to be served, please run npm run api port=3000

Store

Bifrost implements a immutable store for communication between PODs. Important to know, it makes a deep clone when a new entry is added to the store and also when someone gets an entry from the store. This is important so that consumer and provider can change their value of type object without having reference based side effects.

On every store entry, the entry gets syncronised to the Session Storage of the Browser. This feature is very handy if a page refresh happens on the store. Keep aware that the usage of Local Storage is critical and have to be double checked with security, case by case. For this reaosn, bifrost does not provide an api. If someone has the OK from security and can use Local Storage, please make a entry key that is unique, like so: [ANY-HASH]-key-name. Also, there must be an implementation that cleans Local Storage entries of comeback.

When publishing:

  • scalar and array values are replaced in store
  • objects values are merged together (to be discussed whether to keep this behavior)

API under POD Menu Manager

POD Menu Manager uses the bifrost store for communication. The API is described here: https://github.com/axa-ch/pod-menu-manager/blob/develop/DOCUMENTATION.md

Store API

When creating a new POD with the latest create-pod-app a mock store is available. In the devonly.js, which is created dynamically when running create-pod-app, you can mock external PODs. You will find more details in the devonly.js.

Every entry refers to a namespace. The default namespace is "common".

The store that is injected in the POD's options parameter has the following API (direct access to the store DB is tecnichally prevented):

{
  // gets the value of an entry. if no namespace is passed, it gets it from common
  get ( entry: string [, namespace: string] ) : any,

  // adds a new value for an entry to a namespace in the store and calls all subscribers to the given entry in the same namespace. If persist is passed as "false", session Storage sync will be disabled
  publish ( entry: string, namespace: string, value: any, persist = true: boolean ) : boolean,

  // the callback function cb is called with the value for a given entry  when for the same entry / namespace combination a publish() has been executed
  subscribe ( entry: string, namespace: string, cb: Function(value: any) ) : boolean,

  // deletes the given entry in a namespace and its value from the store
  clean ( entry: string, namespace: string ) : boolean,

  // gets the value of an entry / namespace combination only if and when bifrost initialisation is happened
  getAsync ( entry: string, namespace: string, cb: Function(value: any) ) : boolean
}