Custom Widgets for Dashboards#

This page 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.

Files#

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

File	Type	Explanation
`widget.js`	JavaScript	The executable code of the widget. This file is loaded when the widget is used on a dashboard.
`widget.css`	CSS	Styling of the widget. This file must exist even when no styles are used for the widget.
`widget.html`	HTML	Template for the HTML code of the widget. Even if no custom template is used, this file must exist.
`widget.ini`	Config	This file keeps track of the widget metadata. The properties must be filled out. Format: [widget] title= author= description=
config.js	Properties Page	The definition for the properties page used to configure the widget via the frontend

Managing Widgets#

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

Managing Widgets in the Squirro UI#

You can manage and edit custom widgets in the Squirro UI.

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:

widget.js

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.

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:

widget.css

.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 ~Base.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:

widget.js

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

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

widget.html

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

Syntax

Explanation

<%- variable %>

Insert the variable contents with escaping.

This escapes any HTML code using the Underline.js escape function.

<%= variable %>

Insert the variable contents in raw form.

Any HTML code is passed through verbatim.

Only use this for data that’s from safe locations. Your default method should be to use <%- variable %> for best security.

<% JavaScript Code %>

Execute JavaScript code in the current template context. The most common use case for this is a loop as shown in the example above.

Custom Widgets for Dashboards

Contents