An engine for Guided Tours on DOM-based graphical applications

In this blog post, we describe an invention that fills an important gap in Kogito/RHPAM tooling: The Guided Tour Engine.

The Guided Tour Engine provides a unified end-to-end experience on each combination of host and graphical editor, guiding the user on how to use a feature of Kogito authoring, starting from the host environment to multiple graphical editors.

It provides a nice first user experience for our users enabling them to follow by themselves guided tour tutorials on the 'real' technology. It also allows us to be more efficient writing tutorials, because the engine supports the reuse of similar tutorial steps in multiple guided tour experiences. It also avoids code duplication among multiple tutorials.

The Guided Tour Engine

On the authoring of the Kogito initiative, we support multiple host platforms (currently Desktop, Web, Visual Studio Code, Chrome Extension). Each platform runs various graphical editors (currently BPMN, PMML, DMN, DMN test tool) powered by different technology stacks based on micro-frontend architecture concepts.

The Guided Tour Engine must provide a unified end-to-end experience on each combination of host and graphical editor, guiding the user on how to use a feature of Kogito authoring, starting from the host environment to multiple graphical editors.

Every host has its guided tour steps, and each editor also has its steps as well, meaning that a Kogito Guided Tour experience is a composition of steps between one host and multiple graphical editors.

This invention creates a Guided Tour Engine that composes tutorials at runtime by combining tutorial steps of a host and multiple graphical DOM-based editors. It also provides a unified API able to support decoupled DOM-based guided tour steps, and react to user interactions on each target elemen

Architecture

That is the overall architecture of the Guided Tour Engine:

• Guided Tour Engine: Composes a guided tour at runtime and creates a workflow of multiple steps from multiple tutorials, by analyzing the host environment and the active graphical editors. It also reacts from subscribed host/editors and triggers the next step;
• Guided Tour Tutorial: Responsible for registering Tutorials created by Editors and Hosts;
• Editors API: Observes user iterations on editors and notifies the Guided Tour Engine;
• Hosts API: Observes user iteration on hosts and notifies the Guided Tour Engine;
• Editors: Can start or register a Tutorial;
• Hosts: Can start or register a Tutorial;

An example of a tutorial combining the web editor host steps and the DMN graphical editor steps:

In this example, you can see a "Create DMN asset tutorial" composed of reusable steps from the other three tutorials. The dashed boxes represent a link between the tutorials.

It is important to also mention that in this example we have the "Create a BKM node tutorial" registered in memory, but it's not used by "Create DMN asset tutorial".

Let's now discuss in details the major points of the invention:

Tutorial composition at runtime

The Guided Tour Engine stores a collection of registered tutorials. Once the engine is triggered by a tutorial label, it fetches the appropriate tutorial and its dependencies. Let's take a look at the related API:

The Tutorial entity has a label and a collection of steps, and each step has a mode, which can be:

• Block mode: when a given step has a BlockMode instance, it shows the content and waits for the target user interaction;
• Auto mode: when a given step has an AutoMode instance, it shows the content, stays open for some time, and it's auto-skipped;
• Demo mode: when a given step has a DemoMode instance, it shows the content, and waits for the "Next step" click;
• Sub tutorial mode: when a given step has a SubTutorialMode instance, it means that this step will reference another tutorial, i.e. the 'DMN Beginner Tutorial' in Figure 1.

Decoupled DOM-based steps support

The content property in the Step represents the actual visual content that users will consume. The API supports any DOM-based technology template and it's decoupled from any host or visual editor web framework and CSS. That is important to keep the step isolated from the host and visual editor technology.

Custom selectors support

The selector property in the Step entity represents the selector for the DOM element referenced by the current context. The element coordinates are the basis on the relative position of the guided tour content (usually aside with his target component - Figure 4).

Each DOM-based technologies requires different implementations to find the appropriate coordinates and draw the step of the guided tour on the DOM window, i.e.:

• HTML elements: the position of the element with the browser window object. No extra action required in that scenario.
• DOM-Canvas: a relative position of the element into the Canvas. In that case, the custom position provider will need to sum the relative position of the element with the canvas position on the window;
• HTML elements inside an iframe (micro-frontend pattern): the position of the element in the iframe window. In that case, the custom position provider will need to sum the relative position of the element with the iframe element position on the window;
• Grid Elements: a relative position of the element into the grid element. In that case, the custom position provider will need to keep consideration of the grid cell size;

The engine also introduces a unified way to write custom selectors, allowing Guided Tour Engine to handle their position in a decoupled way.

We extended the DOM query selector API introducing a new operator for custom position providers: ":::". Also, the engine allows steps to still use regular DOM query selectors, and in that case, the Guided Tour Engine selectors work as regular DOM query selectors.

The Guided Tour Engine also introduces an interface for custom selector provider registration. Figure 5 shows an example of a simple position provider with two types of custom selectors.

Element listeners support

The Figure 3 shows the BlockMode as one of the eligible modes for a Step instance. Steps with that kind of mode demand a user interaction to proceed with the next step of the tutorial.

In order to achieve that, graphical editors must notify the Guided Tour Engine every time a user interaction happens. For example, Figure 5 shows a simple implementation of a web app notifying the Guided Tour Engine every time that the click event happens.

The original code was published on a Github PR on July 17th of 2020.