Topic manager

The topic manager is a global object that keeps track of topic states and events. It allows to perform additional actions after events or state changes occur. For example, to collect information about customer actions in the topic for further analytics.

Manager initialization

Manager object is available in a global window object called ISPDragonManager. This object does not become available immediately. To wait for its creation, it is recommended to monitor the ISPDragonManagerLoaded event, which is triggered when the manager object is ready. The ISPDragonManagerLoaded event data contains the manager object.

To get a manager object, use a template:

function handlerManager(manager) {
    // working with a manager
}

// if the code was executed after creation of the manager, the ISPDragonManager object is available in the `window` object 
if (window.ISPDragonManager) {
    handlerManager(window.ISPDragonManager);
} else {
    // if the manager is not yet created by the time the code is executed, wait until the `ISPDragonManagerLoaded` event is executed
    window.addEventListener('ISPDragonManagerLoaded', event => {
        // the event data contains a manager object
        const manager = event.detail;
        handlerManager(manager);
    });
}

Events

Manager allows to keep track of general events that occur in a topic:

• http-response — receiving a response to the request;
• action — performing an action, e.g., clicking on a button;
• form-submit — successful form submission;
• form-view-init — form initialization;
• form-destroy — form closing;
• form-wizard — switching to or leaving the wizard.

The http-response event type

Happens when an HTTP response is received from the server.

The event object includes the following properties:

Action event type

Happens at internal topic events:

• button click;
• click on an internal link, i.e. a link with the @internal=“yes” attribute.

Depending on the type of event, its objects contain properties:

Button Click event object

Click on internal link event object

Form-submit event type

Happens when the form is successfully submitted. If the form has not passed validation, the event will not happen.

Form-view-init event type

Happens during the initial initialization of the form. After this event, user can interact with DOM elements of the form.

Form-destroy event type

Happens when the form is closed.

Form-wizard event type

Happens when the user logs in to the Form wizard or leaves the wizard after successfully submitting the form in the last step.

Event object “Opening the first wizard step”

Event object “Successful form submission on the last wizard step”

Event handling methods

The following are the methods of the manager object that allow to handle topic events.

addListener(eventName, callback) 

Allows to specify a function to execute when the event specified in the first argument happens.

The function returns undefined .

removeListener(eventName, callback) 

Deletes the passed function from the handlers of the event with the name set in eventName. The function will no longer be called when an event with such a name happens.

The function returns undefined .

listenToEvent$(eventName) 

Allows to get an object of Observable ,class that is triggered when an event with the name set in eventName occurs.

The function returns an Observable class object that sends an event object.

Usage examples

Below is an example of adding and removing the http-response event handler:

// handler function
const callback = (event) => {
    // handler receives the event object
    console.log('Http-response event object', event);
    // handler removal
    window.ISPDragonManager.removeListener('http-response', callback);
};
//add handler for `http-event`
window.ISPDragonManager.addListener('http-response', callback);

The example below shows a subscription to the Observable object of the action event:

// subscription to the `action` event
window.ISPDragonManager.listenToEvent$('action').subscribe(event => {
    // thread sends an event object
    console.log('Action event object', event);
});

States

The manager allows to retrieve topic states and their changes:

• active-doc — doc tag of the active platform tab;
• user-real-level — user level in the panel;
• active-context-id — id of the current active context.

Active-doc state

The object corresponding to the root doc tag of the active platform tab.

User-real-level state

The user's current level is represented by an integer. Corresponds to the @level attribute from the first doc.path element. This is how the root user level is determined.

Active-context-id state

A string that corresponds to the id of the currently active context. For example, the id of the active tab. Allows to distinguish clearly the elements on the page, if, for example, several identical tabs are open.

Methods of working with the state

Below are the methods of the manager object that allow to work with topic states.

getState(stateName) 

Allows to get the current value of the state specified in stateName synchronously.

The function returns the value of the state.

addWatcher(stateName, watcher) 

Allows to add a function that is called immediately after it is added with the current state value, and with each subsequent change to that value.

The function returns undefined .

removeWatcher(stateName, watcher)

Removes the state value change tracking function with the name specified in stateName.

The function returns undefined .

watchForState$(stateName, options?)

Allows to get an Observable class object that is triggered when the state value with the name set in stateName changes. When subscribed, this Observable sends the current state value immediately. It then returns the state value each time it is changed.

Function returns an object of class Observable that sends a state value.

Usage examples

The example below shows a synchronous user level retrieval:

// get `user-real-level` state value
const currentUserLevel = window.ISPDragonManager.getState('user-real-level');
console.log(currentUserLevel);

The example below shows how to add and remove a state listener:

// handler function
const callback = (currentDoc) => {
    // the handler receives the state value as the first argument
    console.log('Active-doc state value', currentDoc)
    // handler removal
    window.ISPDragonManager.removeWatcher('active-doc', callback);
};
// adding a handler. When a handler is added, it is invoked immediately. Then it is invoked every time the state changes 
window.ISPDragonManager.addWatcher('active-doc', callback);

The example below shows how to subscribe to a Observable object of user-real-level state:

window.ISPDragonManager.watchForState$('user-real-level').subscribe(userLevel => {
    // user level is displayed in the console immediately after subscribing, and every time the state changes
    console.log(userLevel)
});

When skipFirst: true is set, the thread only sends state values when it changes and doesn't send the value immediately after subscribing to it:

window.ISPDragonManager.watchForState$('user-real-level', { skipFirst: true }).subscribe(userLevel => {
    // user level is displayed in the console only when the state changes
    console.log(userLevel)
});