Page Comparison

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.

Widgets.Base

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

...

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

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

...

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
   Data loading
2. 153157661
3. Rendering153157661
4. Interaction
5. Destruction153157661

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

...

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);
},

...

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

...

• 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
• keywords - set to true to include the item keywords in the initial result

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

...

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 153157661).

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

...

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.

...

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

customWidgetTemplate()

...

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.

customResources

widget.customResources['myTemplate.html'](parameters)

...

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.renderContent(/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.

isEmpty()

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

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.

...

...

should return true if the widget 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:

isEmpty: function () {
    var squirroData = this.collection.indexed.$item_created_at.values;

    this.d3_data = d3.nest()
      'click tr': 'onRowClicked', …
   },       onRowClicked: function () {.map(squirroData);

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

onStoreChange()

widget.onStoreChange(model, options)    

Called when a store variable changes (see Dashboard Store).

...

d3_data.size() === 0;
},

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    

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.

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

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

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

onStoreChange()

widget.onStoreChange(model)    

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

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.

...