Custom Widgets Tutorial

This tutorial goes step by step through creating a custom widget.

Table of Contents

Setup

Installation

To get started, make sure the Toolbox is installed. The Toolbox page also contains some basic information to familiarize yourself with how to execute the commands contained in the Squirro Toolbox.

Set up Connection

To upload a widget to Squirro, the widget command line tool  connects with a Squirro instance. For this, two pieces of information are required:

• cluster
• token

A full manual on where to find this information can be found in Connecting to Squirro.

Once you have obtained this information, go to the command prompt window and type the following commands:

set CLUSTER="..."
set TOKEN="..."

Style an Existing Widget

The first example is a extension to the result list widget to change the styling. As part of a custom widget, you can add custom CSS styles. These style definitions can change the look and feel of a widget.

Step 1: Prepare Squirro project

First create a new Squirro project where the custom widget is to be used.

Before starting, download the file news.xls to your computer. This file is later imported into Squirro as an example data set.

Create Project

Log into Squirro with a user that is allowed to create projects.

Create a new project and specify a project title (e.g. "News"). 

Import Data

On the "Data" tab of the new project choose "Add Data". Select the "Data Import" tab and click on "CSV/Excel" to launch the import wizard.

In the Map Fields step all the fields can be left at the default mapping. Simply press "Next" again.

On the final screen confirm that Squirro is about to import 179 items, then press "Import".

The items will now start to show up on the "Search" tab.

Create Dashboard

Finally create a simple dashboard that shows the imported data. You can add a pie chart widget for the "Resource" keyword and a result list widget for the items.

With these preparations out of the way, it's time to start working on the custom widget.

Step 2: Create necessary files

As a first step, create a folder on your computer called "result_list_fancy".

In that folder create the following files:

return Widgets.Search.extend({
}); 

This is the initial code to simply extend the default dashboard widget Widgets.Search (the JavaScript name for the result list widget).

.custom-result_list_fancy {
} 

This is a CSS file without any rules yet. It simply adds the CSS selector to be used later but doesn't yet apply any styling.

<!-- No content in this file needed --> 

This is the HTML template for the widget. We don't currently need one, so we simply add a comment string to it as the file has to exist even when it's not needed.

Step 3: Upload Widget to Cluster

On the command line go to the parent folder of where you have created the widget. So for example if the files you created above are located in c:\widgets\result_list_fancy navigate to the folder c:\widget on the command line.

Then execute the following command to upload the widget to the Squirro cluster:

squirro_widget ^
    --cluster %CLUSTER% ^
    --token %TOKEN% ^
    upload ^
    --config '{"directory": "result_list_fancy", "title": "Fancy Result List", "baseWidget": "Search"}'

Note that the lines have been wrapped with the circumflex (^) at the end of each line. On Mac and Linux you will need to use backslash (\) instead.

This command assumes that you have set the variables CLUSTER and TOKEN as described in the Set up Connection section above.

The config parameter is a JSON data structure of some configuration of the widget. It contains the following keys:

• directory: the name of the folder where the widget files are located.
• title: the name that the widget will have in the user interface when users add it to a dashboard.
• baseWidget: the name of the widget that is used as a basis. This defines what configuration options are made available for the widget in the user interface.

Step 4: Using the Widget

Now go back to the dashboard in Squirro. Due to client-side caching you should now reload the application using the browser refresh button.

Then edit the dashboard and change the result list Type from "Result List" to "Fancy Result List".

The dashboard should now look the same as before, but it's using the new Fancy Result List widget. So if we now add changes to that widget, the dashboard will reflect those.

Step 5: Add Styling

Edit the widget.css file to contain some new styling.

.custom-result_list_fancy {
    font-size: 16px;
    line-height: 20px;
}
.custom-result_list_fancy h4 a {
    font-size: 20px !important;
}
.custom-result_list_fancy .date {
    display: none;
}
.custom-result_list_fancy .vItemSearch:not(:last-child) {
    border-bottom: 1px solid #adadad;
}

This adds quite a bit of styling with the following effect:

• Make the font sizes big (or huge rather) - lines 1-7
• Remove the date from the items - lines 8-10
• Add a border between the items - lines 11-13

Every rule is prefixed with .custom-result_list_fancy. This class is attached to the root of the custom widget and using it in the CSS definitions ensures that styles of one widget don't apply to the rest of the dashboard.

Step 6: Re-upload and Test

Once these changes have been done, upload the widget again using the same command from above:

squirro_widget ^
    --cluster %CLUSTER% ^
    --token %TOKEN% ^
    upload ^
    --config '{"directory": "result_list_fancy", "title": "Fancy Result List", "baseWidget": "Search"}'

Then reload the dashboard and the result list now has the new styling.

Create a New Widget

The second example is a widget from scratch. In the process you will create a clock widget that can be embedded to any dashboard to show the current date and time.

Step 1: Prepare Squirro project

This widget will not display any results, so as preparation you can just create an empty Squirro project.

Log into Squirro with a user that is allowed to create projects.

Create a new project and specify a project title (e.g. "Clock"). 

Step 2: Create necessary files

As a first step, create a folder on your computer called "clock".

In that folder create the following files:

return Widgets.Text.extend({
    customEl: '.widget-content',
    renderContent: _.noop,
});

This is the initial code to simply extend the default dashboard widget Widgets.Text (the text widget by default just displays some text - it serves as a good basis for simple widgets).

.custom-clock .time {
    display: block;
    text-align: center;
    font-size: 20px;
    color: #ccc;
}

This is a CSS file without any rules yet. It simply adds the CSS selector to be used later but doesn't yet apply any styling.

<div class="js-clock time">Testing time</div>

This is the HTML template for the widget. We just add a simple container where the clock is going to be displayed.

Step 3: Upload Widget to Cluster

On the command line go to the parent folder of where you have created the widget. So for example if the files you created above are located in c:\widgets\clock navigate to the folder c:\widget on the command line.

Then execute the following command to upload the widget to the Squirro cluster:

squirro_widget ^
    --cluster %CLUSTER% ^
    --token %TOKEN% ^
    upload ^
    --config '{"directory": "clock", "title": "Clock"}'

Note that the lines have been wrapped with the circumflex (^) at the end of each line. On Mac and Linux you will need to use backslash (\) instead.

This command assumes that you have set the variables CLUSTER and TOKEN as described in the Set up Connection section above.

The config parameter is a JSON data structure of some configuration of the widget. It contains the following keys:

• directory: the name of the folder where the widget files are located.
• title: the name that the widget will have in the user interface when users add it to a dashboard.
• The baseWidget option has been omitted here, because the widget is not taking any configuration.

Step 4: Using the Widget

Create a new Squirro dashboard and add the Clock widget to that dashboard. For better display you can hide the widget header.

For this example no other widgets are required. So save the dashboard and you should get a empty clock on the widget with the sample text from the template.

Step 5: Add Dynamic Code

Now change the widget.js file to actually render the current time. The clock needs to be updated regularly, for which we use the JavaScript method setTimeout.

Edit the widget.js file to contain the following content:

return Widgets.Text.extend({
    customEl: '.widget-content',
    renderContent: _.noop,

    _timer: null,

    afterInitialize: function () {
        this.updateTime();
    },

    updateTime: function () {
        if (this._timer) {
            clearTimeout(this._timer);
        }
        var now = new Date();
        this.$('.js-clock').text(now.toLocaleTimeString());

        this._timer = setTimeout(this.bind(this.updateTime), 500);
    }
});

The contents of this is as follows:

• Line 1 creates a new class, extending from the default Text widget. That widget has been chosen because it doesn't have much overhead.
• Line 2-3: Declares the element into which the template will be rendered and disabled the default behavior of the text widget.
• Line 5: Creates a variable that will hold the timer. This is part of the standard JavaScript pattern for setTimeout.
• Line 7-9 (afterInitialize): As part of the initialization call set up the timer by calling the updateTime method.
• Line 11-19 (updateTime): Update the time (specifically line 15-16). The other lines handle the timer and ensure that the method is called again every 500 milliseconds.

Step 6: Re-upload and Test

Once these changes have been done, upload the widget again using the same command from above:

squirro_widget ^
    --cluster %CLUSTER% ^
    --token %TOKEN% ^
    upload ^
    --config '{"directory": "clock", "title": "Clock"}'

Then reload the dashboard and the clock should now update and show the current time.

Conclusion

The two examples in this tutorial led you through two main use cases for custom widgets:

1. Style an existing widget in a way that is not yet envisioned by the themes.
2. Create a new widget for different visualizations.

Widgets are very powerful and only limited by what JavaScript as a language can do.

Consult the Custom Widgets Reference for reference or contact support if you have any questions about how to do something specific in a custom widget.