Info | ||
---|---|---|
| ||
This documentation will soon be updated Filippo Broggini |
Excerpt |
---|
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
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.
...
This
...
This file keeps track of the widget metadata. The properties must be filled out. Format:
Code Block | ||
---|---|---|
| ||
[widget]
title=
author=
description= |
...
page
...
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.
Managing Widgets in the Squirro UI
As of Squirro 3.0.0 you can now manage and edit custom widgets in the Squirro UI. Please refer to this guide Managing 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:
Code Block | ||||
---|---|---|---|---|
| ||||
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:
Code Block | ||||
---|---|---|---|---|
| ||||
.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:
Code Block | ||||
---|---|---|---|---|
| ||||
...
getCustomTemplateParams: function () {
return {"html": "<strong>test</strong>", "list": [1, 2, 3]};
}
... |
With this parameters the following is a valid template HTML file:
Code Block | ||||
---|---|---|---|---|
| ||||
<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.
...
Insert the variable contents with escaping.
This escapes any HTML code using the Underline.js escape function.
...
Insert the variable contents in raw form.
Any HTML code is passed through verbatim.
Note |
---|
Only use this for data that's from safe locations. Your default method should be to use |
...
can now be found at Custom Widgets for Dashboards on the Squirro Docs site.