Getting Started

This document aims to describe how support for Blueriq's development tooling can be integrated into any frontend technology.

If you are using Blueriq's Angular framework, then integration with the development tooling is provided through DevtoolsModule from @blueriq/angular/devtools. Please include that module in your Angular application to enable development tooling support; no further usage of this package is needed.

The DevtoolsHost

The development toolbar UI is loaded and managed by a DevtoolsHost that acts as a gateway between the devtools UI and the theme. Creating a DevtoolsHost is done using the asynchronous initializeDevtools function that is exported from @blueriq/devtools, which takes a DevtoolsEnvironment that needs to be implemented according to technoloy that is used in the theme.

import { DevtoolsEnvironment, initializeDevtools } from '@blueriq/devtools';

export async function loadDevtools(): Promise<DevtoolsHost> {
  const environment = new MyDevtoolsEnvironment();
  return initializeDevtools(environment);
}

class MyDevtoolsEnvironment implements DevtoolsEnvironment {
  // ...
  // Please refer to the interface documentation on how to implement this class.
  // ...
}

It is recommended that the DevtoolsHost is only loaded and activated when the devtools query parameter is present, as that is used as an indication that development tooling is requested.

Once the host has been created, you can interact with its various methods. First, the host should be activated and the Blueriq sessions on the page should be registered:

const devtools = loadDevtools();
devtools.then(host => host.activate());
devtools.then(host => host.addSession({ sessionId: 'some-session-id', sessionName: 'Main' }));

In the above example a session name is provided for the session, which is shown in the session list in the devtools UI. Omitting a session name causes the session id to be shown instead.

When sessions are no longer shown on the page, they need to be removed from the host as well:

devtools.then(host => host.removeSession({ sessionId: 'some-session-id' }));

Finally, the theme has the ability to notify the devtools UI that the session has been updated, for example after the theme has sent a page event.

devtools.then(host => host.notifyUpdate({ sessionId: 'some-session-id' }));

Vice versa, editing the session from within the devtools UI can request the theme to recompose in order to show the latest changes. To accomplish this, a listener should be registered with the host:

devtools.then(host => host.onRecompose(session => {
  // The session with ID `session.sessionId` should be recomposed here (by sending an empty page event).
}))

Devtools deployment

The devtools UI is deployed inside of the Blueriq Runtime starting from version 13.12 and 14.0 at the /server/devtools path (potentially below the context-root of the Java web application, typically /runtime). The DevtoolsEnvironment that needs to be implemented has to configure a devtoolsUrl that would load the /server/devtools/index.html and related assets. If desired, these resources may be routed through a reverse proxy.

If this resource fails to load, perhaps because development mode is not enabled in the Runtime, then loading a DevtoolsHost using initializeDevtools will reject the promise with an error. As a consequence, the devtools UI is not loaded.