Внешний визуализатор на уровне файловой системы представляет собой папку с файлами, необходимыми для работы: скрипты, картинки и другие составляющие. Файл плагина должен иметь имя manifest.json.
Пример файла manifest.json:
{
"name": "Sunburst α",
"description": "Sunburst diagram - alpha version",
"name-ru": "Санбёрст-диаграмма α",
"description-ru": "Санбёрст-диаграмма - предварительная версия",
"icon": "support.svg",
"author": "Foresight LLC",
"entry": "index.html",
"supportedDimensions": [ "Row", "Column", "Filter", "Facts" ],
"supportedMarks": [ "AxisX", "AxisY", "Color", "Shape", "Size" ],
"supportedSettings": ["axisX", "axisY", "textColor","number", "unit", "affixes", "sparkline","backgroundColor"],
"params": [
{
"name": "Fill color",
"name-ru": "Цвет заливки",
"type": "color_picker",
"default": "#ffffff"
},
{
"name": "Smooth",
"name-ru": "Сглаживание",
"type": "boolean",
"default": false
}
],
"devel": true
}
Задайте обязательные поля:
name. Наименование визуализатора в локали по умолчанию на английском языке;
description. Краткое описание визуализатора в локали по умолчанию на английском языке;
name-ru. Наименование визуализатора на русском языке;
description-ru. Краткое описание визуализатора на русском языке;
icon. Путь до файла иконки визуализатора относительно папки.
Примечание. Допустимо добавление полей вида name-XX и description-XX для других языков, но пока поддерживаются только en и ru.
Задайте функциональные поля:
entry. Обязательное для заполнения поле. Путь до файла, который будет являться точкой входа. Допустимо использование файлов форматов *.html, *.htm или *.js;
supportedDimensions. Необязательное для заполнения поле. Поддерживаемые поля;
supportedMarks. Необязательное для заполнения поле. Поддерживаемые метрики;
supportedSettings. Необязательное для заполнения поле. Поддерживаемые настройки визуализатора;
params. Необязательное для заполнения поле. Настраиваемые параметры визуализатора.
Задайте признак отображения кнопки «Перезагрузить» в области визуализатора:
devel. Необязательное для заполнения поле. По умолчанию поле отсутствует, кнопка не отображается. Для отображения кнопки «Перезагрузить» задайте поле со значением true:
Доступны следующие варианты полей (supportedDimensions):
Row. Строки;
Column. Столбцы;
Filter. Фильтр;
Facts. Факты.
Доступны следующие варианты метрик (supportedMarks):
AxisX. Ось X;
AxisY. Ось Y;
Color. Цвет;
Shape. Форма;
Size. Размер.
Доступны следующие настройки визуализатора:
axisX. Настройка оси категорий (X):
axisY. Настройка оси значений (Y):
textColor. Настройка цвета шрифта:
number. Настройка отображения чисел. Состоит из нескольких настроек:
unit. Настройка единиц измерения:
affixes. Настройка дополнительного текста:
sparkline. Настройка спарклайна:
backgroundColor. Настройка цвета фона визуализатора:
Для добавления пользовательских настроек визуализатора на боковую панель в информационной панели используйте поле params, имеющее следующий формат:
{
"name": "Smooth",
"name-ru": "Сглаживание",
"type": "boolean",
"default": false,
}
Задайте поля:
name. Наименование параметра в локали по умолчанию;
name-ru. Наименование параметра на русском языке. Для задания наименования действуют правила префиксов для других языков по аналогии с полями визуализатора;
type. Тип параметра:
boolean. Логический флажок или переключатель:
color_picker. Выбор цвета на палитре:
параметр на панели:
раскрывающаяся палитра:
position. Положение:
interface Value {
horizontalAlign: 'left' | 'center' | 'right';
verticalAlign: 'top' | 'middle' | 'bottom';
}
radialPosition. Положение на круговой диаграмме;
align. Выравнивание по горизонтали:
valign. Выравнивание по вертикали;
select. Выбор из списка:
radio. Выбор из нескольких значений:
group. Группа параметров:
Простая группировка параметров:
{
"params": [
{
"name": "Totals",
"name-ru": "Итоги",
"type": "group",
"params": [
{
// ... аналогичная структура params
}
]
}
]
}
Сворачиваемая группа:
{
"params": [
{
"name": "Row color",
"name-ru": "Цвет ряда",
"type": "group",
"variant": "collapsible",
"params": [
{
// ... аналогичная структура params
}
]
}
]
}
Выключаемая группа:
{
"params": [
{
"name": "Row color",
"name-ru": "Цвет ряда",
"type": "group",
"variant": "toggleable",
"params": [
{
// ... аналогичная структура params
}
]
}
]
}
default. Значение по умолчанию для параметра.
Точка входа – это файл формата *.html или *.js, в котором должны быть определены две функции в глобальной области видимости на объекте window:
/**
* Функция инициализации визуализатора
* @returns {MaybePromise<void>}
*/
window.init = () => {
// инициализация
};
/**
* Функция обновления визуализатора
* @param данные для построения визуализатора
* @returns {MaybePromise<void>}
*/
window.update = (data) => {
// отрисовка данных
}
/**
* Функция изменения параметров визуализатора
*/
window.paramsUpdate = (param, value, allParams) => {
// реакция на смену настройки
}
В зависимости от формата файла расположения точки входа возможны варианты:
если точка входа в файле *.js, то функции могут быть определены, как в примере выше. Скрипт запускается в отдельном контексте – есть свой объект window и document, с которым можно работать. Например, начать создавать DOM через document.write() или любым другим способом;
если точка входа в файле *.html, то функции могут быть определены внутри тега <script> или быть подгружены из другого файла формата *.js. Этот способ позволяет привычным образом подгрузить стили, скрипты, картинки и другие ресурсы, необходимые визуализатору.
Функция обновления
данных update
Функция обновления
параметров визуализатора paramsUpdate
Типизация внешнего
визуализатора
Визуализатор можно добавить вручную в дистрибутив информационной панели, выполнив действия:
Положить папку с файлами визуализатора в подкаталог visualizers.
Добавить запись о визуализаторе в файл info.json, расположенный в подкаталоге visualizers.
Запись о визуализаторе – это копия содержимого manifest.json, добавленная в массив этого файла.
Например:
[
{
"name": "Sample",
"description": "Sample dummy visualizer",
"icon": "support.svg",
"entry": "main.js",
"dirname": "sample"
},
{
"name": "Sunburst α",
"description": "Sunburst diagram - alpha version",
"name-ru": "Санбёрст-диаграмма α",
"description-ru": "Санбёрст-диаграмма - предварительная версия",
"icon": "support.svg",
"entry": "index.html",
"dirname": "sunburst"
}
]
В примере описано два визуализатора (Sunburst из примера выше).
После выполнения указанных шагов необходимо обновить страницу информационной панели, и внешний визуализатор будет доступен к использованию.
{
"Dims": { // Список измерений
"Names": ["Группа товара", "Тип скидки"], // Имена измерений
"IsCalendar": [0, 1], // Признак календарного измерения
"Elements": [ // Список элементов измерений
["Телевизоры", "Игровые приставки", "Ноутбуки"], // Элементы первого измерения
["5%", "10%"] // Элементы второго измерения
],
"ElementKeys": [ // Ключи элементов
[555, 666, 667], // Ключи элементов первого измерения
[33, 44] // Ключи элементов второго измерения
],
"Marks": [ // Маркеры и позиции измерений
["Row", "Color", "Size"], // Первоге измерение в строках с маркерами Color и Size
["Column", "Form"] // Второе измерение в столбцах с маркером Form
]
},
"Facts": { // Список фактов
"Names": ["Количество", "Сумма"], // Имена фактов
"Aggregation": ["Sum", "Min"], // Первый факт имеет агрегацию по сумме, второй по минимуму
"Marks": [ // Маркеры и позиции фактов
["Filter"], // В фильтре
["Column", "Border"] // В столбцах и с маркером Border
]
},
"Data": { // Данные таблицы
"Values": [33918621, 49771071.5, 418318642], // Значения в ячейках таблицы
"Elements": [ // Список элементов измерений для каждой ячейки
[1, 0], // Первый элемент первого измерения, нулевой элемент второго измерения, данные в ячейке 33918621
[3, 0], // Третий элемент первого измерения, нулевой элемент второго измерения, данные в ячейке 49771071.5
[0, 4] // Нулевой элемент первого измерения, четвёртый элемент второго измерения, данные в ячейке 418318642
]
}
}
В маркеры отправляется положение измерения в заголовках таблицы и наличие метрик.
См. также:
