<!-- Source: https://docs.squirro.com/en/latest/technical/widgets/backbone/widgets-dashboards.html -->
# Custom Widgets for Dashboards

[Deprecated](../../../getting/release/squirro-release-process.md#getting-squirro-process)

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: ```ini [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](http://backbonejs.org/#View). 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**

```javascript
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**

```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](http://underscorejs.org/#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**

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

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

**widget.html**

```rhtml
<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](http://underscorejs.org/#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.