Suricate Widgets

Getting Started • Suricate • DevTool

Retrieve data from external sources and present it in a tile-based format on Suricate dashboards.

Table of Contents

• Repository Architecture
• Creation
  • Creating a Category
  • Creating a Widget
• Suricate Widget Tester
• Contribution

Repository Architecture

📁 Content - Contains all the widgets sorted by category.

      📁 Category 1 - A widget category (e.g. Gitlab, GitHub, Jenkins, etc.).

           📁 Widgets - Contains all the widgets of the category.

                📁 Widget 1 - A widget.

                     📄 content.html - The HTML content of the widget.

                     📄 description.yml - The description of the widget.

                     ♐ image.png - The image of the widget.

                     📄 params.yml - The parameters of the widget.

                     📜 script.js - The process content of the widget, defining what the widget does.

                     📄 style.css - CSS styles to apply to the widget HTML content.

           📄 description.yml - The description of the category.

           ♐ icon.png - The icon of the category.

📁 Libraries - Contains all the JavaScript libraries used by all the widgets.

Creation

If you want to create your own widget and category in Suricate, you can follow these steps.

Creating a Category

A widget category is a folder that contains:

• A description.yml file that describes the category
• An icon.png file to associate an icon with the category in the Suricate application
• A folder that contains all the widgets related to this category

Description

The description.yml file describes the category and contains associated parameters. Here is an example:

name: GitHub
technicalName: github
configurations:
  -
    key: 'WIDGET_CONFIG_GITHUB_TOKEN'
    description: 'Token for the GitHub API'
    dataType: PASSWORD

Here are the possible parameters that can be set in this file:

Param	Required	Description
name	true	The name of the category to display in Suricate.
technicalName	true	The primary key of the category. This is used by the back-end to uniquely identify a category.
configurations	false	Parameters associated with the category. All the widgets of the category will share these parameters. Values are defined directly from the Configuration tab in the Suricate application. Each parameter must declare the following properties: key - The name of the parameter used by the widget. It must start by WIDGET_CONFIG. description - A description for the parameter. dataType - The type of the parameter. It must be one of these types: "NUMBER", "TEXT", "PASSWORD".

Icon

The icon.png file contains the icon to be associated with the category. The icon will be displayed in the Suricate application.

Widgets

The Widgets folder contains all the widgets linked to the category.

For more information about creating a widget, please see the dedicated section.

Creating a Widget

A widget is a folder containing the following files:

• A content.html file that displays the widget in a tile format on Suricate dashboards.
• A description.yml file that provides a description of the widget.
• A image.png file that is used to associate an image with the widget in the Suricate application.
• A params.yml file that describes the parameters of the widget.
• A script.js file that contains the business logic of the widget in JavaScript.
• A style.css file that contains the CSS style of the widget to apply to the HTML.

Content

The content.html file is responsible for displaying the widget on Suricate dashboards and provides the tile format for the widget. It contains the HTML code of the widget.

<div class="grid-stack-item-content-inner">
	<h1 class="title">{{SURI_GITHUB_PROJECT}}</h1>
	<h2 class="value">{{numberOfIssues}}</h2>
	<h2 class="issues-label">{{#issuesState}} {{issuesState}} {{/issuesState}} issues</h2>

	{{#evolution}}
	<p class="change-rate">
	  <i class="fa fa-arrow-{{arrow}}"></i><span>{{evolution}}% since the last execution</span>
	</p>
	{{/evolution}}
</div>
<div class="github"></div>

This file is a template that will be compiled with Mustache, so feel free to use the provided directives to:

• Display data computed by the Back-End from the "script.js" file
• Display parameters from the "params.yml" file or the "description.yml" file of the related category
• Display conditional content

Note that the variable SURI_INSTANCE_ID is available. This is a unique ID that identifies the widget instantiation on a dashboard. If you need to select the widget to use it in JavaScript or CSS, you can use the class selector .widget-{{SURI_INSTANCE_ID}}.

As in the example above, it is possible to add custom JavaScript or calls to JavaScript libraries to improve the widget display.

Description

The description.yml file provides information about the widget. The following is its content:

name: Number of issues
description: Display the number of issues of a GitHub project
technicalName: githubOpenedIssues
delay: 600

The table below lists all possible parameters in this file:

Param	Required	Description
name	true	The name of the widget to be displayed in Suricate.
technicalName	true	The primary key of the widget, used by the back-end to uniquely identify a widget.
description	true	A short description of what the widget does.
info	false	Usage information about the widget and what the user needs to do to get it to work.
delay	true	The duration (in seconds) between each update of the widget. It can be set to -1 if the widget does not need to start the script.js file.
timeout	false	The timeout duration (in seconds) for the widget execution. If it exceeds this duration, the widget will be stopped.
libraries	false	A list of the names of all the external JavaScript libraries required by the widget. The libraries must be manually imported as minified files into the libraries folder at the root of the widget repository. The libraries will be injected into the DOM at execution so that they are available for the widget.

Image

An image.png file contains the image associated with the widget, which will be displayed in the Suricate application.

Params

The params.yml file describes the parameters of the widget that are displayed in the Suricate application when the user selects the widget to add it to a dashboard. The user can set values to the parameters directly from the application, which can then be used in the script.js file or the content.html file.

The params.yml file must adhere to the following rules:

• The file should always start with the widgetParams keyword.
• The parameters have to be described after this keyword as a YAML list format.

widgetParams:
  -
    name: 'SURI_GITHUB_ORG'
    description: 'GitHub organization'
    type: TEXT
    required: true
  -
    name: 'SURI_GITHUB_PROJECT'
    description: 'GitHub project'
    type: TEXT
    required: true
  -
    name: 'SURI_ISSUES_STATE'
    description: 'Filter on the state of the issues'
    type: COMBO
    defaultValue: 'all'
    possibleValuesMap:
      -
        jsKey: all
        value: All
      -
        jsKey: open
        value: Open
      -
        jsKey: closed
        value: Closed
    required: true

The following table lists all available parameters for the params.yml file:

Param	Required	Description
name	true	The name of the variable. It has to start with the keyword "SURI_". Then the variable can be used in the script.js file and the content.html file. It will hold the value set by the user in the Suricate application.
description	true	The description of the parameter. Describe the expected value. It will be displayed as an input label to the user.
type	true	The data type of the parameter. Here is the full list of available types to define in uppercase: TEXT - display a text input TEXTAREA - display a text area input PASSWORD - display a password input BOOLEAN - display a check box NUMBER - display a number input COMBO - display a combo box MULTIPLE - display a combo box with check boxes FILE - display a file upload input
possibleValuesMap	false	Contains the possible values of a combo box. This has to be set if the type of the parameter is COMBO or MULTIPLE. There are two pieces of information to set: jsKey - The key of the option, especially to use it in the script.js file value - The related value displayed to the user in the Suricate application
defaultValue	false	The default value to set for the parameter. It will be displayed in the input by default in the Suricate application.
usageExample	false	An example of how to fill the parameter.
usageTooltip	false	A message to display in a tooltip when configuring the widget.
required	true	Defines whether the parameter is required or not.

Script

The script.js file is the core of the widget. It contains the business process of the widget and defines what the widget does. Most of the time, it submits requests to REST APIs and processes the retrieved data to send to the front-end.

How does the script work?

• It is executed by the Spring Boot back-end with Nashorn.
• It has to define a function named run. This is the function executed by the back-end. All the data returned by the run function has to be stringified in a JSON format.
• The calls to the REST APIs have to be done by invoking Packages.get() or Packages.post(). It will invoke one of the get or post methods in the Suricate back-end.

function run() {
	var data = {};
	var perPage = 100;
	var issues = [];
	var page = 1;
	
	var response = JSON.parse(Packages.get("https://api.github.com/repos/" + SURI_GITHUB_ORG + "/" + SURI_GITHUB_PROJECT + "/issues?page=" + page + "&per_page=" + perPage + "&state=" + SURI_ISSUES_STATE, "Authorization", "token " + WIDGET_CONFIG_GITHUB_TOKEN));
	
	issues = issues.concat(response);

	...
	
	data.numberOfIssues = issues.length;
	
	return JSON.stringify(data);
}

Style

This style.css file is used to add CSS style to the widget.

Usage information:

• It is a pure CSS style file.
• All the classes have to be prefixed by .widget.<technicalname>. The technical name is the one defined in the description.yml file of the widget.

.widget.githubOpenedIssues {
	background-color: #FFFFFF;
}

...

.widget.githubOpenedIssues .issues-label {
	color: #1B1F23;
	font-size: 40px;
}

Suricate Widget Tester

The Suricate Widget Tester is a tool that helps you testing your widget. It is available at https://github.com/michelin/suricate-widget-tester.

Contribution

We welcome contributions from the community! Before you get started, please take a look at our contribution guide to learn about our guidelines and best practices. We appreciate your help in making Suricate a better tool for everyone.