Skip to main content

Widgets.json Overview

The widgets.json file is your configuration file that connects custom backend data to the widgets displayed in the application. Key components include:

  • Basic Information: Defines the widget's name, description, and API endpoint that the data comes from.
  • Metadata: Provide categories for organization and AI enhancement.
  • Display Settings: Specifies widget type and grid dimensions.
  • Data Configuration: Details table and chart settings, including column level information and data types.
  • Parameters: Details query parameters that can be passed to the API endpoint for customization.

Each entry in this file will directly map to a widget in the app. You can find example backends here, where each folder contains a widgets.json file specifying the available widgets.

Below are all of the configurable fields and their descriptions.

A Widgets.json table is a configuration structure with any of the named attributes listed below.

Attributes​

  • name Type: string (required) Sets the display name of the widget shown to the user. Example: "Options EOD Data"

  • description Type: string (required) Provides a brief description of the widget for user info and selection menu. This is important for Copilot to understand what the widget does. Example: "Provides EOD data for all options chains for a given ticker."

  • endpoint Type: string (required) Specifies the backend API endpoint for retrieving data. Example: "chains" Possible values: Any valid API endpoint path as a string.

  • wsEndpoint Type: string Specifies the WebSocket endpoint for live data updates. Only used with the Live Grid Widget. Example: "ws"

  • category Type: string Defines the category for organizing widgets. Example: "Equity" Possible values: Any string representing a category.

  • subCategory Type: string Provides a secondary category for refining search results. Example: "Options"

  • type Type: string Sets the default visualization type for the widget. Possible values: "chart", "table", "markdown", "metric", "note", "multi_file_viewer", "live_grid", "newsfeed", "advanced-chart", "chart-highcharts" Default: "table"

  • runButton Type: boolean If true, a run button will be displayed instead of the refresh button. Possible values: true, false Default: false

  • gridData Type: object containing the following keys:

    • w Type: number Sets the width of the widget in grid units. Example: 20 Maximum value: 40

    • h Type: number Sets the height of the widget in grid units. Example: 9 Maximum value: 100

  • data Type: object containing the following keys:

    • dataKey Type: string A key to identify the data within the widget. Example: "customDataKey"

    • wsRowIdColumn Type: string The column that will be used to identify the row. This is important to set correctly to ensure the live updates are displayed correctly. This the key between your ws and the initial data. Only used with the Live Grid Widget. Example: "symbol"

    • table Type: object containing the following keys:

      • enableCharts Type: boolean Enables chart visualization for table data. Example: true

      • showAll Type: boolean Displays all available data in the table. Example: true

      • chartView Type: object containing the following keys:

        • enabled Type: boolean Sets the chart view as the default view. Example: true

        • chartType Type: string Specifies the type of chart to display. Example: "column" Possible values: see ChartView chart types

        • ignoreCellRange Type: boolean Ignores stored cell range for the chart. Example: false

      • columnsDefs Type: list of objects, each containing the following keys:

        • field Type: string The name of the field from the JSON data. Example: "column1"

        • headerName Type: string The display name of the column header. Example: "Column 1"

        • chartDataType Type: string Specifies how data is treated in a chart. Example: "category" Possible values: "category", "series", "time", "excluded"

        • cellDataType Type: string Specifies the data type of the cell. Example: "text" Possible values: "text", "number", "boolean", "date", "dateString", "object"

        • enableCellChangeWs Type: boolean Controls whether the cell can be updated via WebSocket messages. Only used with the Live Grid Widget. Default: true Example: false

        • formatterFn Type: string Specifies how to format the data. Example: "int" Possible values: see formatterFn

        • renderFn Type: string or array Specifies a rendering function for cell data. See Render Functions for more information. Example: "titleCase" Possible values: "greenRed", "titleCase", "hoverCard", "cellOnClick", "columnColor", "showCellChange"

        • renderFnParams Type: object Required if renderFn is used. Specifies the parameters for the render function. Example: {"actionType": "groupBy"}

        • width Type: number Specifies the width of the column in pixels. Example: 100

        • maxWidth Type: number Specifies the maximum width of the column in pixels. Example: 200

        • minWidth Type: number Specifies the minimum width of the column in pixels. Example: 50

        • hide Type: boolean Hides the column from the table. Example: false

        • pinned Type: string Pins the column to the left or right of the table. Example: "left" Possible values: "left", "right"

        • headerTooltip Type: string Tooltip text for the column header. Example: "This is a tooltip"

  • params Type: list of objects, each containing the following keys:

    • type Type: string The type of the parameter. Example: "date" Possible values: "date", "text", "ticker", "number", "boolean", "endpoint", "form"

    • paramName Type: string The name of the parameter in the URL. Example: "startDate"

    • value Type: string, number, boolean The default value of the parameter. Example: "2024-01-01"

    • label Type: string The label to display in the UI for the parameter. Example: "Start Date"

    • optionsEndpoint Type: string Endpoint to fetch options for the parameter. Example: "v1/test/values"

    • optionsParams Type: object Parameters to pass to the options endpoint. You can use the parameter name from the params array to pass a value to the options endpoint. Example: {"type": "$type"}

    • show Type: boolean Displays the parameter in the UI. Example: true

    • description Type: string Description of the parameter, shown on hover. Example: "The start date for the data"

    • roles Type: array Only used on the Multi-File Viewer Widget - Specifies which parameter is used to select the files. Example: ["fileSelector"]

    • multiSelect Type: boolean Allows multiple values to be selected from your parameter options. Example: true

    • style Type: object Styling options for the parameter. Only popupWidth is currently supported minimum value is 200px max value is 1000px. Example: {"popupWidth": 450}

    • options Type: list of objects, each containing the following keys:

      • label Type: string The label for a dropdown option. Example: "Option 1"

      • value Type: string, number, boolean The value for a dropdown option. Example: "option1"

  • source Type: array of strings Specifies the data source(s) for the widget. Example: ["API", "Database"]

  • refetchInterval Type: number or false Time in milliseconds before the widget's data will refresh if on the page. Minimum value is 1000. Default: 900000 (15m)

  • staleTime Type: number Time in milliseconds before the widget's data is considered stale and will refresh on the next visit to the dashboard. Default: 300000 (5m)

Example widgets.json​

Below is an example widgets.json with a single widget defined. This widget will default to a column chart but have the ability to switch between a table and chart view. The widget will have a start date parameter, a ticker parameter, and a colors parameter, all of which will be able to be selected on the widget in the application.

{
    "custom_widget": {
        "name": "Custom Widget Example",
        "description": "A widget to demonstrate custom configuration",
        "endpoint": "custom-endpoint",
        "runButton": false,
        "data": {
            "dataKey": "customDataKey",
            "table": {
                "enableCharts": true,
                "showAll": true,
                "chartView": {
                    "enabled": true,
                    "chartType": "column"
                },
                "columnsDefs": [
                    {
                        "field": "column1",
                        "headerName": "Column 1",
                        "chartDataType": "category",
                        "cellDataType": "text",
                        "formatterFn": "none",
                        "renderFn": "titleCase",
                        "width": 100,
                        "maxWidth": 200,
                        "minWidth": 50,
                        "hide": false,
                        "pinned": "left"
                    },
                    {
                        "field": "column2",
                        "headerName": "Column 2",
                        "chartDataType": "series",
                        "cellDataType": "number",
                        "formatterFn": "int",
                        "renderFn": "greenRed",
                        "width": 150
                    }
                ]
            }
        },
        "params": [
            {
                "type": "date",
                "paramName": "startDate",
                "value": "2024-01-01",
                "label": "Start Date",
                "show": true,
                "description": "The start date for the data",
            },
            {
                "type": "text",
                "paramName": "ticker",
                "value": "AAPL",
                "label": "Ticker",
                "show": true,
                "description": "Stock ticker symbol",
            },
            {
                "type": "text",
                "paramName": "colors",
                "value": "red",
                "label": "Colors",
                "show": true,
                "description": "Stock ticker symbol",
                "multiSelect": true,
                "options": [
                  { "label": "Red", "value": "red" },
                  { "label": "Green", "value": "green" },
                  { "label": "Blue", "value": "blue" }
                ],
            }
        ],
        "source": [
            "My First API"
        ],
        "refetchInterval" : 900000,
        "staleTime": 300000
    }
}

Special Properties​

Date Modifier​

This is used to display a dynamic date.

The reference is $currentDate and if a user wants to add or subtract they need to append to the variable:

  • h, for hour
  • d, for day
  • w, for week
  • M, for month
  • y, for year

For instance, $currentDate-1w stands for 1 week ago.

If you don't want to set a date you can omit the value parameter or pass null.

Examples​

[
  {
    "paramName": "start_date",
    "value": "$currentDate-2y",
    "label": "Start Date",
    "type": "date",
    "description": "Current Date for the stock price"
  },
  {
    "paramName": "end_date",
    "value": "$currentDate+1d",
    "label": "End Date",
    "type": "date",
    "description": "End Date for the stock price"
  },
    {
    "paramName": "end_date",
    "value": null,
    "label": "End Date",
    "type": "date",
    "description": "End Date for the stock price"
  },
  {
    "paramName": "interval",
    "value": "1d",
    "label": "Interval",
    "options": [
      { "label": "Daily", "value": "1d" },
      { "label": "Weekly", "value": "1w" },
      { "label": "Monthly", "value": "1m" }
    ],
    "type": "text",
    "description": "Select the interval"
  }
]

ChartView chart types​

chartType: The type of chart to display by default. These charts are provided using the AgGrid library. Custom charts can also be created using Plotly. For examples, refer to the GitHub repository.

Allowed values: column, groupedColumn, stackedColumn, normalizedColumn, bar, groupedBar, stackedBar, normalizedBar, line, scatter, bubble, pie, donut, doughnut, area, stackedArea, normalizedArea, histogram, radarLine, radarArea, nightingale, radialColumn, radialBar, sunburst, rangeBar, rangeArea, boxPlot, treemap, heatmap, waterfall

formatterFn​

formatterFn (optional): Specifies the function used to format the data in the table. The following values are allowed:

  • int: Formats the number as an integer.
  • none: Does not format the number.
  • percent: Adds % to the number.
  • normalized: Multiplies the number by 100.
  • normalizedPercent: Multiplies the number by 100 and adds % (e.g., 0.5 becomes 50 %).
  • dateToYear: Converts a date to just the year.

On this page