Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.

Table of Contents

Widgets.Base

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

Status
colourBlue
titleExtend
.

...

Code Block
languagejs
titlewidget.js
return Widgets.Text.extend({
    customEl: '.widget-content-body',

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

...

Code Block
languagejs
titleExample
customEl: '.widget-content-body',

Life cycle

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

  1. Initialization
    1. External module management
    2. Data prefetching
  2. 153092153153157661153092153
  3. 153157661
  4. Interaction
  5. 153092153153157661

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

...

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

...

Code Block
languagejs
titleExample
afterInitialize: function () {
    this.updateTime();
},

External module management

...

This method is called after the setup phase happens. This is a useful place to attach events to the collection, as it's initialised here (but not yet loaded).

Expand
titleExample
Code Block
languagejs
titleExample
afterSetup: function () {
    this.collection.on('add', this.itemAdded, this);
},


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.

...

Code Block
languagejs
titleExample
afterRender: function () {
    console.log(this.collection.length);
},


dashboard

widget.dashboard

...

  • additionalQuery - specifies custom query part that will be added to the current dashboard query to produce the widget's query.
    • Allows presenting different datasets in different widgets
    • Note, produces more requests. Always take care to ensure the overall performance is not affected.
  • createdBefore - specifies an upper time restriction for the widget's collection fetch.
    • Supports both absolute (ISO format) dates and relative strings, e.g. '24h', '3months'
  • createdAfter - like createdBefore, but for lower time restriction

...

titleExample
  • keywords - set to true to include the item keywords in the initial result


Code Block
languagejs
titleExample
getCustomCollectionParams: function () {
	return {
		additionalQuery: 'Company:Squirro',
		createdBefore: '24h',
		createdAfter: '2011-01-01T00:00:00',
	};
},


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.

...

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

...

Code Block
languagejs
titleExample
afterRender: function () {
    this.$el.append(this.customTemplate());
},


customEl

widget.customEl    

Status
colourBlue
titleExtend

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.

Expand
titleExample
Code Block
languagejs
titleExample
customEl: '.widget-content',


customTemplate()

widget.customTemplate(/* no arguments */)

...

Contains a dictionary with keys being the template file names, and values the functions which will ensure the CSS is in the document for the lifecycle of the widget (and will be unloaded afterwards).

...

renderContent()

widget.DISABLE_FULL_GRID (default: false)

Controls whether the Full Grid functionality should be supported by the custom widget. When set to a true value, the expanding button will not be shown on the widget.

expanded

widget.expanded (default: false)

Contains the expanded state of the widget (true / false) if the Full Grid functionality has been turned on. Gets passed automatically to the template under the same name.

renderContent()

widget.renderContentrenderContent(/* 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:

Code Block
languagejs
renderContent: _.noop

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

isEmpty()

widget.isEmpty(/* no arguments */)

This renders the content of should return true if 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:

does not have any data to display. The default implementation uses this.collection.size() and returns true if the size is 0. When creating a widget from a facet collection, that is usually not the desired behaviour. In those cases, isEmpty can be overwritten.

As a lot of the processing of a widget may be needed to determine whether any data is to be displayed, widgets sometimes end up caching the result of that in the isEmpty method. The following is an example from a D3 widget:

Code Block
languagejs
renderContentisEmpty: function () {
    var squirroData = this.collection.indexed.$item_created_.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 153092153. To add the event handlers manually, for example by using jQuery listeners directly, attach them in the afterRender method.

customEvents

widget.customEvents    

Status
colourBlue
titleExtend

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:
at.values;

    this.d3_data = d3.nest()
         …
         .map(squirroData);

    return this.d3_data.size() === 0;
},
Expand
titleExample

This is an example that extends the facets table with an additional click handler.

Code Block
languagejs

ALLOW_OVERFLOW

ALLOW_OVERFLOW: false

If the widget contains content which will pop up or out of the widget boundary then set this value to true.

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 153157661. To add the event handlers manually, for example by using jQuery listeners directly, attach them in the afterRender method.

customEvents

widget.customEvents    

Status
colourBlue
titleExtend

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.

This is an example that extends the facets table with an additional click handler.

See dashboard store for information on the store property being used here.

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


Note

This does not currently work. Instead, use the _.extend pattern with the events property:

Code Block
return Widgets.FacetsTable.extend({
    events: _.extend(Widgets.FacetsTable.prototype.events, {
        'click tr': 'onRowClicked',
    }),

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

See dashboard store for information on the store property being used here.

onStoreChange()

widget.onStoreChange(model, options)    

Status
colourBlue
titleExtend

Called when a store variable changes (see 153092153).

...



onStoreChange()

widget.onStoreChange(model)    

Status
colourBlue
titleExtend

Called when a store variable changes (see 153157661).

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.

Reference: https://backbonejs.org/#Model-changed

Code Block
languagejs
titleExample
onStoreChange: function (model) {
    if (_.has(model.changed, 'mykey')) {
        // mykey has changed
    }
},

Destruction

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

...

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.

...


Code Block
languagejs
titleExample
afterClose: function () {
    this.cancelTimer();
},