Custom Widgets Reference

The reference shows the full usage of the custom widgets for Squirro dashboards. In this reference the command line utility squirro_widget and it's usage for uploading widgets to a Squirro cluster is explained. Then each of the main components of a widget has its own section: JavaScript, CSS, HTML.

Table of Contents

Files

On the local disk a Squirro widget is a folder. That folder contains a number of files that all have their purpose.

Managing Widgets (squirro_widget)

The Toolbox comes with a command line utility squirro_widget which is used to manage custom widgets on a Squirro installation.

The full reference of this command can be found in the separate section squirro_widget Command Line Reference.

JavaScript

Custom widgets are implemented as Backbone.js views. Despite this, no prior experience with the Backbone.js framework is required.

The template for a new widget.js file is as follows:

return Widgets.Text.extend({
    // Class properties and methods here
});

Base Widgets

This example extends from the Widgets.Text base class. The full list of base classes from which widgets can inherit is documented in Base Widgets.

API

The JavaScript API, including all properties and methods to be overwritten, is documented in the Custom Widgets API.

External Libraries

See the section External JavaScript Libraries for how to use additional libraries.

CSS

The widget.css file contains Cascading Style Sheet instructions for styling of the dashboard.

Widgets are namespaced by adding a CSS class custom-name where name is the widget name. For example the clock widget from the tutorial would receive the CSS class custom-clock which from CSS can be styled as follows:

.custom-clock {
    // CSS rules here that should apply to the whole widget
}
.custom-clock a {
    // CSS rules here that should apply to all links inside the clock widget
}

Use the namespacing for any styling that is local to the widget.

It is also possible to add global styles (without the namespace). These styles will affect the whole dashboard on which the custom widget is embedded. Note however that the class names, elements, etc. are not guaranteed to remain the same and will change between releases without notice. So if you choose to style global elements of the dashboard, test with every new Squirro release if the styles still work.

The CSS declarations from custom widgets are applied in sequence, by the widgets position in the dashboard (top-left to bottom-right). This can be meaningful when !important clauses are used, as the latest CSS definition one will override the former.

HTML

The HTML file widget.html is treated as a template file. The underscore.js template method is used for this.

The return value of the getCustomTemplateParams method is passed in as parameters into the template and its values are accessible in the template as local variables.

As an example take the following method template parameters method in the widget.js file:

...
getCustomTemplateParams: function () {
    return {"html": "<strong>test</strong>", "list": [1, 2, 3]};
}
... 

With this parameters the following is a valid template HTML file:

<dl>
    <dt>HTML (escaped)</dt>
    <dd><%- html %></dd>

    <dt>HTML (raw)</dt>
    <dd><%= html %></dd>

    <dt>List<dt>
    <dd>
        <% _.each(list, function (el) { %>
            <%- el %>,
        <% } %>
    </dd>
</dl>

This example highlights the three main template features.