Skip to content

Latest commit

 

History

History
296 lines (223 loc) · 20.7 KB

README.md

File metadata and controls

296 lines (223 loc) · 20.7 KB
Suricate

Suricate Widgets

GitHub Stars License

Getting Started • Suricate • DevTool

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

Suricate dashboard developer environment

Table of Contents

Repository Architecture

The repository is organized as follows:

  • Content: Contains all the widgets sorted by category.
    • Category: A widget category (e.g. Gitlab, GitHub, Jenkins, etc.).
      • Widgets: Contains all the widgets of the category.
        • Widget: 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

To create a repository of widgets, follow the steps below.

Category

A category is a folder that contains all the widgets related to a specific topic. It contains the following files:

  • 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: 'CATEGORY_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.
  • 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.

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">{{WIDGET_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.

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

Description

The description.yml file provides information about the widget.

name: 'Count issues'
description: 'Count the number of issues in a GitHub repository.'
technicalName: 'github-count-issues'
delay: 300

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.

Parameters

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: 'WIDGET_GITHUB_ORGANIZATION'
    description: 'GitHub organization'
    type: 'TEXT'
    required: true
  - name: 'WIDGET_GITHUB_PROJECT'
    description: 'GitHub project'
    type: 'TEXT'
    required: true
  - name: 'WIDGET_GITHUB_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.
acceptFileRegex false A regular expression to validate the file name when the parameter type is FILE.
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 Suricate Back-End with GraalVM Polyglot.
  • It has to define a function named run. All the data returned by the run function has to be stringified in a JSON format using JSON.stringify(data).
  • 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/" + WIDGET_GITHUB_ORGANIZATION + "/" + WIDGET_GITHUB_PROJECT + "/issues?page=" + page + "&per_page=" + perPage + "&state=" + WIDGET_GITHUB_ISSUES_STATE,
                  "Authorization", "token " + CATEGORY_GITHUB_TOKEN));
  
  return JSON.stringify(data);
}
Execution Logs

To display execution logs in the Suricate application, use the print() method.

function run() {
  var data = {};
  var perPage = 100;
  var issues = [];
  var page = 1;

  var response = JSON.parse(Packages.get('...'));

  print(response);

  return JSON.stringify(data);
}
Previous Execution Data

The previous execution data is accessible as a JSON object in the SURI_PREVIOUS variable.

function run() {
  var data = {};
  var previousData = JSON.parse(SURI_PREVIOUS);
  
  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> to be applied to the widget. This class is unique to the widget and is added by Suricate when the widget is displayed on the dashboard. The technical name is the one defined in the description.yml file of the widget.
.widget.github-count-issues {
  background-color: #FFFFFF;
}

.widget.github-count-issues .title {
  color: #1B1F23;
  text-transform: capitalize;
}

Suricate Widget Tester

The Suricate Widget Tester is a tool that helps you to test 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.