Справка по библиотеке сторонних компонентов Студии данных (dscc)

Общие сведения об API

Библиотека dscc (сторонних компонентов Студии данных) помогает создавать компоненты для Студии данных. Исходный код можно посмотреть на GitHub.

Библиотека dscc предоставляет доступ к трем функциям: getWidth(), getHeight() и subscribeToData().

getWidth()

Имя Параметры Тип возвращаемого значения Описание
getWidth() Нет number Возвращает значение ширины окна iframe в пикселях.

Использование getWidth()

// to get the width of the iframe
    var width = dscc.getWidth();
    

getHeight()

Имя Параметры Тип возвращаемого значения Описание
getHeight() Нет int Возвращает значение высоты окна iframe в пикселях.

Использование getHeight()

// to get the height of the iframe
    var height = dscc.getHeight();
    

sendInteraction()

Функция sendInteraction() передает в Студию данных сообщение с данными для фильтрации.

Параметры:

Имя Тип Описание
actionID string Строка, соответствующая значению actionId в конфигурации.
interaction enum(InteractionType) Передает в Студию данных информацию о взаимодействии.
data object(InteractionData) Предоставляет данные, необходимые для взаимодействия.

InteractionType

В настоящее время единственное допустимое значение InteractionType – FILTER.

Имя Тип Описание
dscc.InteractionType.FILTER Enum Описывает взаимодействие FILTER.

Использование sendInteraction


    // the actionID can either be hardcoded or parsed from the returned data
    var actionId = "interactionConfigId";

    // dscc provides enums for the interaction types
    var FILTER = dscc.InteractionType.FILTER;

    var fieldID = "qt_m9dtntutsb";
    var dataValue = "Asia";

    // sendInteraction expects data that tells you the concepts and the values of
    // those concepts to use in constructing a filter.
    var interactionData = {
      "concepts": [fieldId],
      "values": [[dataValue]]
    }

    dscc.sendInteraction(actionId, FILTER, interactionData);
    

interactionData

var interactionData = {
      "concepts": array(fieldId),
      "values": array(array(dataValue))
    }
    
Поле Тип Описание
concepts Array Массив fieldIds
values Array<Array> Вложенный массив значений. Размер всех подмассивов должен соответствовать размеру массива concepts. Каждое значение в подмассиве соответствует значению параметра.

Пример interactionData:

var interactionData = {
      "concepts": ["dim1Id", "dim2Id"],
      "values": [
        ["dim1Val1", "dim2Val1"],
        ["dim1Val2", "dim2Val2"]
        ]
    }
    

Использование функции dscc.sendInteraction с объектом interactionData эквивалентно следующей инструкции SQL:

SELECT data WHERE
      (dim1 == dim1Val1 AND dim2 == dim2Val1)
      OR
      (dim1 == dim1Val2 AND dim2 == dim2Val2);
    

clearInteraction()

Функция clearInteraction() передает в Студию данных сообщение об отмене фильтрации, ранее заданной этой визуализацией.

Параметры:

Имя Тип Описание
actionID string Строка, соответствующая значению actionId в конфигурации.
interaction enum(InteractionType) Передает в Студию данных информацию о взаимодействии.

Использование clearInteraction()


    // the actionID can either be hardcoded or parsed from the returned data
    var actionId = "interactionConfigId";

    // dscc provides enums for the interaction types
    var FILTER = dscc.InteractionType.FILTER;

    dscc.clearInteraction(actionId, FILTER);
    

subscribeToData(callback, options)

Функция subscribeToData() осуществляет подписку на сообщения от Студии данных.

Параметры:

Имя Тип Описание
callback(data) function Функция, которая получает данные, возвращаемые функцией subscribeToData.
options object Определяет формат возвращаемых данных.

Объект options выглядит следующим образом:

{
      transform: dscc.tableTransform | dscc.objectTransform
    }
    

Возвращаемое значение:

Тип Описание
function Отменяет получение функцией callback сообщений от Студии данных.

Использование subscribeToData()

// define and use a callback
    var unsubscribe = dscc.subscribeToData(function(data){
      // console.log the returned data
      console.log(data);
    }, {transform: dscc.tableTransform});

    // to unsubscribe

    unsubscribe();

    

data

Объект, переданный функции callback, зарегистрированной в dscc.subscribeToData. Ниже приведены поля, общие для dscc.objectFormat и dscc.tableFormat.

{
      fields: object(fieldsByConfigId),
      style: object(styleById),
      interactions: object(interactionsById),
      theme: object(themeStyle),
      tables: object(tablesById)
    }
    
Поле Тип Описание
fields object(fieldsByConfigId) Объект, который содержит объекты field, связанные с определенным значением configId.
style object(styleById) Объект, который содержит объекты style, связанные с определенным значением configId.
interactions object(interactionsById) Объект, который содержит объекты interaction.
theme themeStyle Объект themeStyle, который содержит информацию о стилистической теме отчета.
tables object(tablesById) Объект, который содержит объекты table.

fieldsByConfigId

{
       configId: array(field)
    }
    

Объект fieldsByConfigId содержит массивы объектов field, связанных с определенным идентификатором, заданным в конфигурации визуализации. Этот объект содержит по одной записи для каждого объекта dataField, определенного в конфигурации.

Поле Тип Описание
configId Array<field> Массив объектов field, связанных с объектом dataField.

field

{
      id: fieldId,
      name: string,
      description: string,
      type: fieldType,
      concept: enum(conceptType)
    }
    

Объект field содержит информацию о поле, выбранном пользователем на панели свойств.

Поле Тип Описание
id string Созданный Студией данных идентификатор поля.
name string Имя поля в понятном для пользователя формате.
description string Описание поля.
type enum(fieldType) Семантический тип поля (semanticType).
concept enum(conceptType) Тип элемента поля (conceptType).

styleById

{
       configId: styleValue
    }
    

Объект styleById содержит информацию о стиле, связанном с определенным идентификатором, заданным в конфигурации визуализации.

Поле Тип Описание
configId styleValue Объект, который содержит значение style и определенное в конфигурации значение style по умолчанию.

styleValue

{
      value: string | object | bool | number,
      defaultValue: string | object | bool | number
    }
    

Объект styleValue содержит выбранное пользователем значение style и определенное в конфигурации значение style по умолчанию. Тип value и defaultValue зависит от элемента style.

Поле Тип Описание
value string OR object OR bool OR number Значение элемента style, выбранное пользователем на панели свойств.
defaultValue string OR object OR bool OR number Значение элемента style по умолчанию, определенное в конфигурации визуализации.

interactionsById

{

    }
    

Объект interactionsById содержит информацию о взаимодействии, связанном с определенным идентификатором (interactionId), заданным в конфигурации визуализации.

Индекс Тип Описание
configId interaction Объект, который содержит информацию, связанную с взаимодействием.

interactionField

{
      value: object(interactionValue),
      supportedActions: array(InteractionType)
    }
    

Объект interactionField содержит массив значений supportedActions, определенных в конфигурации, а также выбранные пользователем значения для взаимодействия.

Поле Тип Описание
value string OR object OR bool OR number Значение элемента style, выбранное пользователем на панели свойств.
supportedActions Array<InteractionType> Действия, поддерживаемые в этом взаимодействии (определены в конфигурации).

interactionValue

Объект interactionValue содержит выбранные пользователем значения для типа взаимодействия. Если ключ data существует, то объект InteractionData отражает текущий статус фильтра. Если ключ data не существует, значит, визуализация не настроена для использования в качестве фильтра.

{
      type: enum(InteractionType)
      data: object(interactionData) | None
    }
    
Поле Тип Описание
type enum(InteractionType) Выбранное пользователем значение InteractionType.
data object(InteractionData) Объект data, связанный с текущим статусом фильтра. Если фильтрация отменена, то ключ не существует.

theme

{
      fillColor: {
        color: string,
        opacity: number
      },
      fontColor: {
        color: string,
        opacity: number
      },
      accentFillColor: {
        color: string,
        opacity: number
      },
      accentFontColor: {
        color: string,
        opacity: number
      },
      fontFamily: string,
      accentFontFamily: string,
      increaseColor: {
        color: string,
        opacity: number
      },
      decreaseColor: {
        color: string,
        opacity: number
      },
      gridColor: {
        color: string,
        opacity: number
      },
      seriesColor: [
        {
          color: string,
          opacity: number
        }
      ]
    }
    

Объект themeStyle передает в визуализацию информацию о теме отчета.

Поле Тип Описание
fillColor object Объект формата {color: string, opacity: number}.
fontColor object Объект формата {color: string, opacity: number}.
accentFillColor object Объект формата {color: string, opacity: number}.
accentFontColor object Объект формата {color: string, opacity: number}.
fontFamily string Строка с описанием семейства шрифтов.
accentFontFamily string Строка с описанием семейства шрифтов акцента.
increaseColor object Объект формата {color: string, opacity: number}.
decreaseColor object Объект формата {color: string, opacity: number}.
gridColor object Объект формата {color: string, opacity: number}.
seriesColor Array<object> Массив объектов формата {color: string, opacity: number}.

tablesById

{
      "DEFAULT": object(tableObject),
      "COMPARISON": object(tableObject) | undefined
    }
    

tableObject содержит информацию о заголовке и данных для каждой строки. "DEFAULT" всегда возвращает данные, "COMPARISON" передает значения, только если пользователь настроил сравнение.

Единственное различие между dscc.tableFormat и dscc.objectFormat – формат tableObject.

Поле Тип Описание
"DEFAULT" object(tableObject) OR Array<objectRow> Объект tableObject, связанный с данными, добавленными пользователем в визуализацию.
"COMPARISON" object(tableObject) OR Array<objectRow> Объект tableObject, связанный с данными сравнения (если применимо).

Справка по tableFormat

tableObject

{
      headers: array(object),
      rows: array(array)
    }
    
Поле Тип Описание
headers Array Массив объектов field. Для этих объектов также задано свойство configId, соответствующее идентификаторам из конфигурации.
rows Array<Array> Массив массивов, каждый из которых является строкой данных.

Пример данных, использующих tableFormat

Ниже приведен пример данных (data), возвращаемых при использовании dscc.subscribeToData() и dscc.tableFormat.

{
      "tables": {
        "DEFAULT": {
          "headers": [{
            "id": "qt_ky8sltutsb",
            "name": "dimension",
            "type": "TEXT",
            "concept": "DIMENSION",
            "configId": "configId1"
          }, {
            "id": "qt_b5bvmtutsb",
            "name": "second dim",
            "type": "TEXT",
            "concept": "DIMENSION"
            "configId": "configId1"
          }, {
            "id": "qt_m9dtntutsb",
            "name": "metric",
            "type": "NUMBER",
            "concept": "METRIC",
            "configId": "configId2"
          }],
          "rows": [
            ["Week 4", "lm", 55]
          ]
        },
        "COMPARISON": {
          "headers": [{
            "id": "qt_ky8sltutsb",
            "name": "dimension",
            "type": "TEXT",
            "concept": "DIMENSION",
            "configId": "configId1"
          }, {
            "id": "qt_b5bvmtutsb",
            "name": "second dim",
            "type": "TEXT",
            "concept": "DIMENSION"
            "configId": "configId1"
          }, {
            "id": "qt_m9dtntutsb",
            "name": "metric",
            "type": "NUMBER",
            "concept": "METRIC",
            "configId": "configId2"
          }],
          "rows": [
            ["Week 5", "no", 123]
          ]
        }
      },
      "fields": {
        "configId1": [
          {
            "id": "qt_ky8sltutsb",
            "name": "week",
            "type": "TEXT",
            "concept": "DIMENSION"
          },
          {
            "id": "qt_b5bvmtutsb",
            "name": "textId",
            "type": "TEXT",
            "concept": "DIMENSION"
          }
        ],
        "configId2": [
          {
            "id": "qt_m9dtntutsb",
            "name": "orders",
            "type": "NUMBER",
            "concept": "METRIC"
          }
        ]
      },
      "style": {
        "nodeColor": {
          "value": {
            "color": "#000000"
          }
        }
      },
      "theme": {},
      "interactions": {
        "onClick": {
          "value": {
            "type": "FILTER",
            "data": {
              "concepts": [
                "qt_h6oibrb6wb",
                "qt_i6oibrb6wb"
              ],
              "values": [
                [
                  "Afternoon",
                  "Sunday"
                ],
                [
                  "Afternoon",
                  "Thursday"
                ],
                [
                  "Morning",
                  "Tuesday"
                ]
              ]
            }
          },
          "supportedActions": [
            "FILTER"
          ]
        }
      }
    }
    

Справка по objectFormat

objectRow

{
      configId1: array(string | bool | number),
      configId2: array(string | bool | number)
    }
    
Поле Тип Описание
configId array Массив значений, связанных с определенным идентификатором конфигурации.

Пример данных, использующих objectFormat

Ниже приведен пример данных (data), возвращаемых при использовании dscc.subscribeToData() и dscc.objectFormat.

{
      "tables": {
        "COMPARISON": [
          {
            "configId1": ["Week 5", "cd"],
            "configId2": [123]
          }
        ],
        "DEFAULT": [
          {
            "configId1": ["Week 1", "ab"],
            "configId2": [24]
          }
        ]
      },
      "fields": {
        "configId1": [
          {
            "id": "qt_h6oibrb6wb",
            "name": "time of day",
            "type": "TEXT",
            "concept": "DIMENSION"
          },
          {
            "id": "qt_i6oibrb6wb",
            "name": "day",
            "type": "TEXT",
            "concept": "DIMENSION"
          }
        ],
        "configId2": [
          {
            "id": "qt_m9dtntutsb",
            "name": "metric",
            "type": "NUMBER",
            "concept": "METRIC"
          }
        ]
      },
      "style": {
        "nodeColor": {
          "value": {
            "color": "#000000"
          }
        }
      },
      "theme": {},
      "interactions": {
        "onClick": {
          "value": {
            "type": "FILTER",
            "data": {
              "concepts": [
                "qt_h6oibrb6wb",
                "qt_i6oibrb6wb"
              ],
              "values": [
                [
                  "Afternoon",
                  "Sunday"
                ],
                [
                  "Afternoon",
                  "Thursday"
                ],
                [
                  "Morning",
                  "Tuesday"
                ]
              ]
            }
          },
          "supportedActions": [
            "FILTER"
          ]
        }
      }
    }