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" 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
          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"

    • 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