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 | ||||
---|---|---|---|---|
|
...
Code Block | ||||
---|---|---|---|---|
| ||||
return Widgets.Text.extend({
customEl: '.widget-content-body',
... // Other code inside the class here
}) |
...
Code Block | ||||
---|---|---|---|---|
| ||||
customEl: '.widget-content-body', |
Life cycle
The widget life cycle is split into a number of stages in order:
- Initialization
- External module management
- Data prefetching
- 153092153153157661153092153
- 153157661
- Interaction
- 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 | ||||
---|---|---|---|---|
| ||||
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 | ||||
---|---|---|---|---|
| ||||
Code Block | ||||
| ||||
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 | ||||
---|---|---|---|---|
| ||||
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
...
title | Example |
---|
- keywords - set to
true
to include the item keywords in the initial result
Code Block | ||||
---|---|---|---|---|
| ||||
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 | ||||
---|---|---|---|---|
| ||||
afterRender: function () {
this.$el.append(this.customTemplate());
}, |
customEl
widget.customEl
Status | ||||
---|---|---|---|---|
|
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 | ||||
---|---|---|---|---|
| ||||
Code Block | ||||
| ||||
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 | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
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 colour Blue title 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.
Expand | ||
---|---|---|
| ||
This is an example that extends the facets table with an additional click handler. Code Block | | |
|
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 colour Blue title 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.
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 | ||
---|---|---|
| ||
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
See dashboard store for information on the store property being used here. |
onStoreChange()
widget.onStoreChange(model, options)
Status colour Blue title Extend
Called when a store variable changes (see 153092153).
...
onStoreChange()
widget.onStoreChange(model)
Status colour Blue title Extend
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 | ||||
---|---|---|---|---|
| ||||
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 | ||||
---|---|---|---|---|
| ||||
afterClose: function () {
this.cancelTimer();
}, |