Custom Widget

Build your own custom widget to view and filter existing data

For most use cases, you'll want to create a widget inside a schema. Click here to view the documentation for creating schema plugins.

Configuring Custom Plugin

From your service overview page, select the Add Plugin button.

From the Plugins dialog, browse through the list of available plugins and select the Custom Plugin plug-in by clicking on the Add button.

This will bring you to the custom plugin editor, which will be empty by default.

Custom Plugin JSON Format

A custom plugin is created by specifying an array of plugin option objects. The objects must follow this format:

export type ICustomPluginSchema =
  | ICustomPluginList
  | ICustomPluginCard
  | ICustomPluginDivider
  | ICustomPluginTable
  | ICustomPluginChart
  | ICustomPluginChartAggregate;

export interface ICustomPluginList {
  displayType: "list";
  schema: string;
  title?: string;
  item?: {
    title: string;
    subtitle?: string;
    color?: string;
    icon?: string;
    tags?: string;
    url?: string;
  };
  maxItems?: number;
  sort?: IQueryBuilderSort;
  filters?: IQueryBuilderFilterCondition[];
  dateRange?: ICustomPluginDateRange;
}

export interface ICustomPluginCard {
  displayType: "card";
  schema: string;
  title?: string;
  item?: {
    title: string;
    subtitle?: string;
    icon?: string;
    url?: string;
  };
  maxItems?: number;
  sort?: IQueryBuilderSort;
  filters?: IQueryBuilderFilterCondition[];
  dateRange?: ICustomPluginDateRange;
}

export interface ICustomPluginTable {
  displayType: "table";
  schema: string;
  path?: string;
  title?: string;
  menu?: ICustomPluginMenu;
  sort?: IDataFlexibilitySort;
  filters?: IDataFlexibilityFilterCondition[];
  pageSize?: number;
  columns?: string[];
  dateRange?: ICustomPluginDateRange;
}

export interface ICustomPluginDivider {
  displayType: "divider";
  title?: string;
}

export enum QueryBuilderSortDirection {
  ASC = 'ASC',
  DESC = 'DESC',
}

export interface IQueryBuilderSort {
  field: string;
  direction: QueryBuilderSortDirection;
}

export enum QueryBuilderFilterType {
  compare = 'compare',
  or = 'or',
  and = 'and',
}

export type IQueryBuilderFilterCondition =
  | IQueryBuilderFilterCompare
  | IQueryBuilderFilterOr
  | IQueryBuilderFilterAnd;

export interface IQueryBuilderFilterCompare {
  type: QueryBuilderFilterType.compare;
  field: string;
  value: string | number | boolean | (string | number)[] | null;
  compare: QueryBuilderFilterCompare;
}

export interface IQueryBuilderFilterOr {
  type: QueryBuilderFilterType.or;
  conditions: IQueryBuilderFilterCondition[];
}

export interface IQueryBuilderFilterAnd {
  type: QueryBuilderFilterType.and;
  conditions: IQueryBuilderFilterCondition[];
}

type RelativeDateUnit = "day" | "week" | "month" | "quarter" | "year";

interface IDateRangeRelativeOption {
  title: string;
  start: {
    value: number;
    unit: RelativeDateUnit;
  };
  end: {
    value: number;
    unit: RelativeDateUnit;
  };
}

export interface ICustomPluginDateRange {
  enabled?: boolean;
  hideDefaultRelativeOptions?: boolean;
  relativeOptions?: IDateRangeRelativeOption[];
}

In addition to this JSON format and following display type examples, Chart Widgets are also available.

This likely looks more complicated than it actually is, especially since we allow complex filtering and sorting. Here's a simple example just to show a list of items with some detailed information inline:

[{
    "displayType": "list",
    "schema": "<your_schema_name_here>",
    "item": {
        "title": "{{ item.name }}",
        "subtitle": "{{ item.description }}"
    }
}]

And switching displayType to card looks like this:

The editor on the left-hand side will give you some hints if there are issues in the formatting for the code:

Complex examples

Here are a couple more examples of custom plugins with some varying configurations.

List View

This is an example of a plugin with some more detailed data, as well as a max number for the list of items.

Code snippet

[{
    "schema": "<your_schema_here>",
    "displayType": "list",
    "item": {
        "title": "{{ item.name }}",
        "subtitle": "{{ item.severity }}",
        "icon": "{{ item.priority }}"
    },
    "maxItems": 3
}]

This is an example of a plugin with filtering and sorting.

Code snippet

[{
    "schema": "<your_schema_here>",
    "displayType": "list",
    "item": {
        "title": "{{ item.name }}",
        "subtitle": "{{ item.severity }}"
    },
    "filters": [{
        "type": "compare",
        "field": "name",
        "value": "CVE-2024-0193",
        "compare": "like"
    }]
}]

Table View

This is an example of a plugin with basic configuration

Code snippet

[{
    "displayType": "table",
    "schema": "<your_schema_here>",
}]

This is an example of a plugin with custom page size and sorting.

Code snippet

[{
    "displayType": "table",
    "schema": "scorecards",
    "pageSize": 12,
    "sort": {
        "field": "evaluatePercentage",
        "direction": "ASC"
    },
}]

This is an example of a plugin with filtering.

Code snippet

[{
    "displayType": "table",
    "schema": "scorecards",
    "pageSize": 12,
    "sort": {
        "field": "evaluatePercentage",
        "direction": "ASC"
    },
     "filters": [{
        "type": "compare",
        "field": "evaluatePercentage",
        "value": 10,
        "compare": "gte"
    }],
}]

This is an example of a plugin with custom columns.

Code snippet

[{
    "displayType": "table",
    "schema": "scorecards",
    "pageSize": 12,
    "sort": {
        "field": "evaluatePercentage",
        "direction": "ASC"
    },
     "filters": [{
        "type": "compare",
        "field": "evaluatePercentage",
        "value": 10,
        "compare": "gte"
    }],  
    "columns": ["name","evaluatePercentage"]
}]

Date Range

This is an example of a plugin using a date range with default options.

Code snippet

[
  {
    "displayType": "table",
    "schema": "<your_schema_here>",
    "columns": [
      "name",
      "accruedCosts",
      "priorPeriodCosts",
      "changeCosts"
    ],
    "dateRange": {
      "enabled": true
    }
  }
]

This is an example of a plugin using a date range without the default relative date options.

Code snippet

[
  {
    "displayType": "table",
    "schema": "<your_schema_here>",
    "columns": [
      "name",
      "accruedCosts",
      "priorPeriodCosts",
      "changeCosts"
    ],
    "dateRange": {
      "enabled": true,
      "hideDefaultRelativeOptions": true
    }
  }
]

This is an example of a plugin using a date range by adding custom relative date options.

Title: name to be shown on the left side of date picker dialog. Start: relative date reference for the initial date. Ex. "2-week" is 2 weeks prior to today. End: relative date reference for the ending date. Ex. "0-day" is today. Value: number field. Unit: can be one of the following; "day", "week", "month", "quarter", or "year".

Code snippet

[
  {
    "displayType": "table",
    "schema": "<your_schema_here>",
    "columns": [
      "name",
      "accruedCosts",
      "priorPeriodCosts",
      "changeCosts"
    ],
    "dateRange": {
      "enabled": true,
      "hideDefaultRelativeOptions": true,
      "relativeOptions": [
        {
          "title": "Past 2 weeks",
          "start": {
            "value": 2,
            "unit": "week"
          },
          "end": {
            "value": 0,
            "unit": "day"
          }
        }
      ]
    }
  }
]