Custom Widgets Life Cycle

stateDiagram-v2 [*] --> Initialization Destruction --> [*] Initialization --> Setup: Prefetch models loaded state "Loading collection" as LoadingCollection Setup --> LoadingCollection: Widget has been added to the DOM LoadingCollection --> Rendering: Collection has been fetched Rendering --> Interaction Interaction --> Refresh: Dashboard query changes Refresh --> Rendering: Collection has been fetched again Interaction --> Destruction

A custom widget goes through different stages in its life cycle. In each stage the widget has access to certain data or elements in the browser DOM. To understand the purpose of the different widget SDK methods and events the interplay between these stages is thus important.

Initialization

The initialization stage starts with the invocation of the widget class constructor and is executed once when creating the widget. In the life cycle of the dashboard as a whole, the widget will only be initialized once, even when it is sometimes hidden through visibility conditions.

In this stage the widget is wired up with the basics, configuration options, and visual options as needed.

In the rare case where a widget has to fetch data beyond what is available through a collection, this has to be set up here. Such data fetching is registered using the registerPrefetch() method.

Setup

The setup stage prepares the data structure of the widget, including initialization of the widget’s collection and model.

This stage is executed after the Initialization stage, once the data marked for pre-fetching (using registerPrefetch()) has been received from the server.

If you need to instantiate a custom collection, do this in the Setup stage. Usually through returning it from the getCollection() method.

A widget extending the Base widget is automatically assigned a initialized Squirro Item collection. Extending other widgets gets their respective collection. If your widget does not require any data from the server, use the Static widget.

Loading Collection

In the loading stage, the widget collection is asynchronously retrieved from the server.

This happens after the widget has been added to the browser DOM. As the collection has not yet been loaded, the widget contents is empty in this stage.

Rendering

In the rendering stage, the widget contents is put into the browser DOM. By default this is done using the template capabilities, which will usually use the collection to render it into the browser.

This stage is executed each time the widget is rendered, the first time is when the collections has been loaded. Later the refresh stage will initiate further rendering.

Refresh

In the refresh stage, the widget is reacting to changes in the dashboard, usually a change of the search query. The widget will refresh its collection as a response to this. When the collection has been fetched, the rendering stage is entered again.

Interaction

During the interaction stage, which is usually the majority of the widget’s lifetime, the widget responds to user interactions. The main task during this stage is to listen for events from the user, the models, and the collections.

Destruction

In the destruction change, the widget views are destroyed, its events unbound and its content removed from the DOM.

This stage is executed once, when destroying the widget. Widgets are destroyed when the user leaves the dashboard. In other cases, such as the user closing the browser, this stage may never be entered.