Tabs

Chart configuration is customized using JavaScript code you add on the editor tabs in the interface.

The chart configuration code, as described on the tabs, is executed on the server. This page presents the code formats for each of the tabs.

The function code inside Editor.wrapFn is executed on the client in the user's browser. This imposes a number of limitations, see Available methods for more details.

The tabs are executed in a specific order.

MetaMeta

Serves to describe service information about the list of related entities.

The Meta tab is used to add the object IDs of the sources used for the chart/selector. Object ID description is a required element. This information is used to find out what connections and datasets the chart is related to, for the related objects dialog, when copying a workbook, and when publishing to Public.

You can copy object IDs from the relevant object's menu or in navigation by clicking Copy ID. The ID will be saved to the clipboard.

As a key, you need to specify any alias name that will be assigned to this data source in the chart. Next, on the Source tab, you can get this alias name using Editor.getId(arg) and specify it as a source.

{
    "links": {
        "<string>": "<string>",
        ...
    }
}

{
    "links": {
        "myDatasetKeyName": "qvnkqzm0wstyf",
        "connectionKey": "ch96co0501xy1",
        "apiConnectionKey": "uzrou8sqm5zaj"
    } 
}

ParamsParams

This tab is for default chart/selector parameters. All chart/selector parameters must be described on the Params tab. The parameter values ​​are arrays of strings. If you only need to provide one value, you need to format it as an array consisting of one element.

{
    "<string>": "<string>",
    ...
}

module.exports = {
    count: ['10'],
    setting: ['value'],
};

If you set other parameter values for such a chart on the dashboard or in the report in the widget settings, the Params tab values will be overridden. The values will also be overridden if you select values different from the default ones in the dashboard or report selector or apply cross-filtering by another chart. Learn more about overriding parameters

You can get the values ​​of all current parameters on subsequent tabs using the Editor.getParams() method; you can also get the current value of any parameter by its name using Editor.getParam(name).

You can override the parameters using the chart's URL. For example:

&period=40&metric=2012&metric=2014

When such a URL comes on top of the default parameters, you get the following object:

{
  period: 40,
  metric: ['2012', '2014'],
  id: ['1215', '1217', '979', '483']
}

When a dashboard or report is initially rendered, the parameters that link the JS selector to the charts on the dashboard or report remain static. If the parameter is dynamically calculated in the selector code, then the chart re-renders with the updated parameter value only when the selector changes next time.

Special parametersSpecial parameters

Relative dateRelative date

Formats:

• __relative_<symbol><amount><unit>
• __relative_<symbol><amount><unit>_<casting_type><unit>

• <symbol>: + or -
• <unit>:
  • y: Year
  • Q: Quarter
  • M: Month
  • w: Week
  • d: Day
  • h: Hour
  • m: Minute
  • s: Second
  • ms: Millisecond
• <casting_type>:
  • s: To the start
  • e: To the end

Example:

If the current time is 2020-03-24T23:30:39.874Z, then

• __relative_-7d: Seven days back, 2020-03-17T00:00:00.000Z
• __relative_+30m: 30 minutes later, 2020-03-25T00:00:39.874Z
• __relative_-0d: Today, 2020-03-24T00:00:00.000Z
• __relative_-0h: Now, 2020-03-24T23:30:39.874Z
• __relative_-3M_sQ
  • Minus 3 months, 2019-12-24T00:00:00.000Z
    • Cast to the start of the quarter: 2019-10-01T00:00:00.000Z
• __relative_+15s_em
  • Plus 15 seconds: 2020-03-24T23:30:54.874Z
    • Cast to the end of the minute: 2020-03-24T23:30:59.999Z

Note: If no casting is specified, then for the units of one day and longer, the time is cast to the start of the day,
i.e., 00:00:00.000, while casting to the current time is used for the units shorter than one day.

Helper method: Editor.resolveRelative

IntervalInterval

Format: __interval_<start>_<end>

start/end: relative date or ISO date.

Example:

If the current time is 2020-03-24T23:30:39.874Z, then

• __interval_2019-03-11T09:35:48_2019-12-28T09:35:48
  • from 2019-03-11T09:35:48 to 2019-12-28T09:35:48
• __interval_2019-01-17T09:35:48___relative_+0d
  • from 2019-01-17T09:35:48 to today (2020-03-24T23:59:59.999Z)
• __interval___relative_-2w_sM___relative_+1d
  • two weeks ago or more: 2020-03-10T00:00:00.000Z
    • cast to the start of the month: 2020-03-01T00:00:00.000Z
  • until tomorrow: 2020-03-25T23:59:59.999Z

Helper method: Editor.resolveInterval

LimitationsLimitations

The following limitations apply when using parameters:

• You cannot use the following reserved keys:

  • tab
  • state
  • mode
  • focus
  • grid
  • scale
  • tz
  • timezone
  • date
  • datetime
  • _action_params
  • _autoupdate
  • _opened_info
  • report_page
  • preview_mode

  Parameters with these keys are ignored and not saved.

• Links can only use parameters that are set in the dashboard settings. Otherwise, they are ignored. For example, if a link contains ?product=Furniture, but the dashboard settings have no product parameter (not even with an empty value), this parameter will be ignored.

• Dashboard parameters are applied to widgets anyway. This may lead to errors in data requests.

SourcesSources

This tab defines the structure for requesting the data to visualize.

You can get the data using:

• Dataset
• Database connection via an SQL query
• Connection via API Connector

Connecting to a data source via a datasetConnecting to a data source via a dataset

To use data from a dataset:

{
    datasetId: "<string>",
    data: {
        fields: [
            {
                ref: {
                    title: "<string>",
                    type: "title"| "id",
                },
            },
            ...
        ],
    }
}

module.exports = {
    'myDatasetSource': {
        datasetId: Editor.getId('myDatasetKeyName'),
        data: {
            fields: [
                {
                    ref: {
                        type: "title",
                        title: "PaymentType",
                    },
                },
		{
                    ref: {
                        type: "title",
                        title: "OrderYear",
                    },
                },
		{
                    ref: {
                        type: "title",
                        title: "OrderMonth",
                    },
                },
            ],
        },
    },
};

const {buildSource} = require('libs/dataset/v2');
module.exports = {
    'myDatasetSource': buildSource({
        datasetId: Editor.getId('myDatasetKeyName'),
        columns: ['PaymentType', 'OrderYear', 'OrderMonth'],
    }),
};

Example of getting only a list of fields from a dataset:

module.exports = {
  fields: {
      datasetId: Editor.getId('mySource'),
      path: 'fields'
  }
};

See alsoSee also

• Quick start on creating a table with a dataset connection

Connecting to a data source via an SQL queryConnecting to a data source via an SQL query

To get data from a connection (via an SQL query):

{
    qlConnectionId: "<string>",
    data: {
        sql_query: "<string>",
    },
}

module.exports = {
    'myDataSource': {
        qlConnectionId: Editor.getId('connectionKey'),
        data: {
            sql_query: 'SELECT 1 + 1',
        },
    }
}

See alsoSee also

• Quick start on creating a table with connection via an SQL query

Connecting to a data source via API ConnectorConnecting to a data source via API Connector

To get data via API Connector:

{
    apiConnectionId: "<string>",
    path: "<string>",
    method: "GET"|"POST",
    body: <object>,
}

module.exports = {
    'myApiDataSource': {
        apiConnectionId: Editor.getId('apiConnectionKey'),
        path: '/html',
        method: 'GET',
    }
}

See alsoSee also

• Quick start on creating a table with a connection via API Connector

ConfigConfig

This tab is used to set visualization settings, e.g., cross-chart filtering settings.

Available for Chart and Table visualization types. Possible contents depend on the specific visualization type.

PreparePrepare

This tab is responsible for data preprocessing prior to rendering and includes the following actions:

• Getting uploaded data from sources using the Editor.getLoadedData() method.

• Processing and conversion to required format (depends on visualization type).

• Writing the results to module.exports, from where they get into rendering.

Available for Chart, Advanced chart, Table, Markdown visualization types.

ControlsControls

The declarative style describes the possible controls, i.e., the chart's control elements. Unlike dashboard selectors and report selectors, these control the current chart alone and are not saved after you refresh the page.

Available for all visualization types. The tab format details depend on the type of controls.

ActivitiesActivities

The tab allows you to configure interactive actions for dashboard elements, such as sending an HTTP request when a table row is clicked.

Available for the following visualization types: selector, table, and chart (Gravity UI Charts).

module.exports = {
    sources: ({params}) => { /* configuration of sources */ },
    handleResponse: ({data}) => { /* response processing */ }
}

module.exports = {
  sources: ({params}) => {
      const ticketId = params.cells[0].value;
      return {
          todoList: {
              apiConnectionId: Editor.getId('todoListConnection'),
              path: `?ticketId=${ticketId}`,
              method: "GET",
          },
      }; 
  },
  handleResponse: ({data}) => {
      const ticket = data.todoList.data.body;
      return {
          action: 'popup',
          title: ticket.title,
          content: ticket.description,
      };
  }
};

Available methodsAvailable methods

• sources(): Function returning an object for connection to a data source. It is used to send requests. The format is identical to the Sources tab format:

  sources: ({params}) => ({     
      sourceKey: {         
          apiConnectionId: Editor.getId("mySourceKeyName"),         
          path: '/api/endpoint',         
          method: 'POST',         
          body: { /* request data */ }     
      } 
  })
  

  Where:

  • params: Object with parameters from the dashboard controls.
  • apiConnectionId: ID of the API Connector type connection described on the Meta tab and obtained using the Editor.getId(arg) method.
  • mySourceKeyName: Alias name for the data source described on the Meta tab.
  • path: API path after host.
  • method: Request method.
  • body: Request data.

• handleResponse(): Function returning an object formatted for the specific action type. It processes the server response and defines the interface action:

      handleResponse: ({data}) => { /* response processing */ }
  

  Where data is an object with responses from data sources.

Available actionsAvailable actions

• popup: Pop-up notification:

  Format

  Example

  {
      action: "toast",
      title: "<string>",
      content: "<string>",
      type: "warning"|"success"|"normal"|"info"|"danger"|"utility",
  }
  

  Where:

  • action: Type of action to invoke after sending the request. The toast value shows the brief pop-up notification component in the lower right corner.
  • title: Notification title.
  • content: Notification content.

  {
      action: 'toast',
      title: 'Title',
      content: 'Notification text' 
  }
  

• popup: Pop-up window:

  Format

  Example

  {
      action: "popup",
      title: "<string>",
      /** text or markup in markdown format */
      content: "<string>",
  }
  

  Where:

  • action: Type of action to invoke after sending the request. The popup value shows a pop-up window component in the center of the screen.
  • title: Window title.
  • content: Window content.

  {
      action: 'popup',
      title: 'Title',
      content: 'Window content' 
  }
  

• setParams: Setting parameters:

  Format

  Example

  {
      action: "setParams",
      params: object,
  }
  

  Where:

  • action: Type of action to invoke after sending the request. The setParams value updates the parameter values ​​from the provided params field.
  • params: Object with a list of keys and parameter values to set.

  {
      action: "setParams",
      params: {p: ["1"]}
  }
  

Performing actionsPerforming actions

To perform actions of the Activities tab, configure interface element events:

• Selectors: On the Controls tab, set the button’s onClick event to the runActivity action.
• Gravity UI Charts and Tables: Configure the runActivity action on the Config tab.

LimitationsLimitations

• The Activities tab supports limited data sources for requests: requests to datasets, standard connections, and API Connector connections.
• This feature is currently available for the following chart types: Selector, Table, and Chart (Gravity UI Charts).

See alsoSee also

• Example of using the Activities tab in Editor