Custom Widgets API

The custom widgets JavaScript API provides a number of properties and methods. Some of these are mostly used to access data, but others are explicitly provided as extension points to overwrite.

Table of Contents

Widgets.Base

All widgets – in-built as well as custom – inherit from the base widget. For a full list of the available widgets to extend from, see Base Widgets.

Methods and properties that are not defined by default, but instead provided purely for extension purposes, are highlighted as follows: EXTEND.

The examples in the reference omit the boilerplate that is needed. For example if you are inheriting from the text widget and setting the customEl property, the code would look like this:

return Widgets.Text.extend({
    customEl: '.widget-content',

    ... // Other code inside the class here
}) 

For conciseness this is abbreviated below as follows:

customEl: '.widget-content',

Life cycle

The widget life cycle is split into a number of stages in order:

1. Initialization
2. Data loading
3. Rendering
4. Interaction
5. Destruction

The methods and properties are all documented in their respective stage.

Properties that are set by the base widget (as for example model) are documented in the stage where they become available. These properties are only available in stages after the one that set it.

Initialization

In this stage the widget is wired up with the basics, configuration options, visual options (if needed).

The stage is executed once when creating the widget (once in the life cycle of a dashboard).

If models or collections are required, they should be initialised here. By default, a widget extending Base widget (without visuals or logic) gets a initialized Squirro Item collection. Extending other widgets gets their respective collections.

afterInitialize()

widget.afterInitialize(/* no arguments */)     EXTEND

This method is called after the class has been initialized. It is a good place to set up data fetching, event listeners, etc.

afterInitialize: function () {
    this.updateTime();
},

Data loading

In this stage the collection data is loaded from the Squirro backend.

This stage is executed every time the widget is rendered, usually when the dashboard query changes.

collection

widget.collection

A Backbone.js collection as instantiated by the base widget. This contains all the data that the widget needs for rendering. It is fetched before the rendering stage.

afterRender: function () {
    console.log(this.collection.length);
},

customCollection

widget.customCollection     EXTEND

A Backbone.js collection that will be fetched automatically before the rendering stage is executed. If this collection is used, it should be set up in the initialization stage .

afterInitialize: function () {
    this.customCollection = new MyWidgetCollection();
},

dashboard

widget.dashboard

A Backbone.js model that represents the currently rendered dashboard. See dashboard state for the main usage of this model.

Rendering

In this stage the widget content is rendered into its container. The container is managed by the Squirro Dashboard automatically. So after this stage the widget is fully in the page's DOM tree and displayed to the user.

This stage is executed each time the widget is rendered - usually when the dashboard query changes as a result of a search or a filter interaction.

afterRender()

widget.afterRender(/* no arguments */)     EXTEND

This method is called after the rendering has been done (after renderContent). When this is executed, the widget is guaranteed to have injected itself into the DOM, and thus normal techniques of manipulating DOM elements apply (jQuery can be used for example).

The default implementation of afterRender appends the custom template to the widget and also installs any custom events (see customEvents).

afterRender: function () {
    this.$el.append(this.customTemplate());
},

customEl

widget.customEl     EXTEND

A special property of the widget that defines the element into which the custom template is rendered. This is a CSS selector that is executed against the root node of the current widget.

customEl: '.widget-content',

customTemplate()

widget.customTemplate(/* no arguments */)

Renders the custom template. The default behavior of this method is to call the customWidgetTemplate function with the return value of getCustomTemplateParams method.

customWidgetTemplate()

widget.customWidgetTemplate(params)

This is a templating function that returns a HTML string templated from the given params hash.

This is assigned automatically by Squirro to be a Underscore.js template function rendering the widget.html file.

getCustomTemplateParams()

widget.getCustomTemplateParams(/* no arguments */)     EXTEND

Returns a hash of all the parameters that are passed into the custom template. The return value of this method is used as input for the customWidgetTemplate call.

renderContent()

widget.renderContent(/* no arguments */)

This renders the content of the widget. In the base widget, this method does nothing - but in all the other widgets it contains the logic for displaying the widget content in the dashboard.

To prevent the default rendering of a widget completely, replace this function with noop:

renderContent: _.noop

In that case rendering can be fully customized and overwritten in the afterRender method.

Interaction

Squirro Widgets provide interaction by subscribing events to its DOM elements and handling them. All of these events fall into the interaction stage.

The recommended way to install custom events is customEvents. To add the event handlers manually, for example by using jQuery listeners directly, attach them in the afterRender method.

customEvents

widget.customEvents     EXTEND

The customEvents hash can be used to specify a set of DOM events that will be listened for and delegated to methods in the widget view. This is an extension to the default events hash of Backbone.js and behaves very similarly.

return Widgets.FacetsTable.extend({
    customEvents: {
        'click tr': 'onRowClicked',
    },
 
    onRowClicked: function () {
        this.dashboard.state.set({'additionalInfo': true});
    },
});

onStateChange

widget.onStateChange(model, options)     EXTEND

Called when a state variable changes (see Dashboard State).

The model argument can be used to access the exact property or properties that have changed by accessing model.changed. That property is a hash containing all the attributes that changed in the last set call.

Destruction

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

This stage is executed once, when destroying the widget.

afterClose()

widget.afterClose(/* no arguments */)     EXTEND

This method is called when the widget is being removed from the document. It is a good place to clean up, such as removing event listeners.

afterClose: function () {
    this.cancelTimer();
},

Utils

Utilities are provided in the Utils global space. They are present in the context of the widget JavaScript file, but not in the template context by default (that can easily be remedied by returning it as part of getCustomTemplateParams though).

queryParam

A utility for handling query string parameters.

parse()

Utils.queryParam.parse(/* no arguments */)

Returns a hash of all the query string parameters in the current URL.

var params = Utils.queryParam.parse();
// returns a hash of parameters, example:
// {"q": "Apple"}
console.log(params.q);

Dashboard State

The dashboard state is accessible in the widget using the widget.dashboard.state property. This model is the recommended way for custom widgets to talk to each-other. The dashboard state is a Backbone.js model though without persistence.

Custom widgets should implement the onStateChange method to listen for changes to the state.

Architecture

A good example for when to use the state is when there are two widgets on a dashboard that have to communicate with each-other.

For example a navigation widget can be implemented which presents the user with a number of menu options. When clicking on one of the options, the state is updated by setting a attribute. A second widget reacts to that state value and changes the content to be displayed depending on the set attribute.

Methods

get()

state.get(attribute)

Get the current value of the state attribute.

onStateChange: function () {
    if (this.dashboard.state.get('additionalInfo')) {
        this.$el.addClass('additional-info-requested');
    }
},

set()

state.set(attribute, value)
state.set(attributes)

Set one attribute to the given value or - in the secondary form - update all the key/value pairs from the hash.

If any attribute changes, a change event is triggered. The easiest way to subscribe to those in the widget is by implementing the onStateChange method.

onRowClicked: function () {
    this.dashboard.state.set({'additionalInfo': true});
},