1 Клонирование проекта

Проект разработки плагина доступен по адресу: https://github.com/modus-bi/custom-chart.

Структура названий веток с референсными реализациями: reference-<префикс библиотеки>-<тип диаграммы>.

Если плагин разрабатывается на поддерживаемой библиотеке визуализации, то лучше форкните (создать новый независимый проект, сделав полную копию данного проекта) референсную реализацию для этой библиотеки (префиксы echarts, d3 и т.п).

В общем случае можете взять универсальную референсную реализацию без специфического функционала (префикс universal).

Смотрите также раздел «Описание репозитория custom-chart». 

2 Добавление сборки ядра в проект

В описании PluginsApi v0.1 (см. раздел «Описание PluginsApi v0.1 ядра платформы «Modus BI») укажите какие версии ядра им соответствуют и получите сборку ядра.

Положите сборку ядра в папку \prebuilt проекта плагина (папка внесена в .gitignore), это нужно для процесса отладки с запуском полноценного портала.

При внутренней разработке можно использовать сборку ядра с добавлением sourcemap для больших возможностей отладки. Для этого можно использовать скрипт deploy:dev.

3 Планирование реализации

3.1 Выбор степени кастомизации

Создание  плагина в основном состоит в реализации модулей встройки. Для каждого модуля встройки надо решить насколько он будет кастомизирован, для этого можно:

• взять готовый код из папки dublicates, пропистать его в managers/ComponentTypeManager и быстро получить работающий плагин с минимальным уровнем кастомизации;
• модифицировать готовый код и получить плагин со средним уровнем кастомизации;
• написать весь код с нуля и реализовать полностью кастомизированный плагин.

3.2 Выбор зависимостей

Если в плагине используются какие-то библиотеки, которые недоступны через PluginsApi из ядра, то надо их прописать в package.json.

Если библиотека визуализации пока недоступна через PluginsApi, то можно использовать конструктор сборки, чтобы минимизировать размер библиотеки добавляемой в плагин.

Библиотека визуализации может быть доступна через PluginsApi.externals, но в урезанном виде без нужного типа диаграммы. Тогда запросите добавление нужного типа диаграммы в следующей версии, а пока импортируйте самостоятельно.

4 Реализация модулей встройки

Реализация модулей встройки осуществляется путем переделывания референсных реализаций с использованием раздела «Описание PluginsApi v0.1 ядра платформы «Modus BI».

4.1 Особенности реализации CustomChart.

При реализации основного модуля встройки нужно создать с нуля или модифицировать существующие файлы:

• 4.1.1 Chart.
  • Реализация рендера самой диаграммы. Если диаграмма основана на каком-то движке визуализации, то в этом модуле вызывается ChartAdaptor. Если нет, основная логика визуализации будет здесь.
• 4.1.2 ChartAdaptor.
  • Адаптер диаграммы предоставляет api ко всем функциям движке визуализации и как правило реализуется один раз для каждого движка.
• 4.1.3 DataAdaptor.
  • Адаптер данных реализует взаимодействие с кэшем данных и подготовкой данных в визуализации. В простых случаях может использоваться CommonDataAdapter, код которого доступен в duplicates, либо можно реализовать полностью кастомный адаптер данных.
• 4.1.4 SpecGenerator.
  • Генератор спецификации создает на основе конфига диаграммы объект спецификации, по которому движок визуализации строит диаграмму.
• 4.1.5 defaultConfig.json.
  • Дефолтный конфиг используется при создании новой диаграммы. В нем задаются дефолтные значения свойств конфига.

4.2 Особенности реализации CustomSettings.

В модуле настроек реализуется интерфейс настроек в редакторе компонента.

Часть разделов настроек универсальны для многих типов диаграмм и такие разделы передаются через API в готовом виде как рендер-пропсы.

Также через API передаются стандартные элементы интерфейса, из которых можно собирать более кастомизированные разделы

4.3 Особенности реализации CustomReducers.

В модуле редьюсеров реализуется код реакции на экшены вызываемые из CustomSettings. Как правило для всех вызовов используется универсальный экшен changeChart, в котором фактический экшен передается через параметр command.

Через API модуля также передяется хелпер автоприменения настройки.

4.4 Особенности реализации CustomAxes.

​​​​​​​В модуле осей кастомизируется интерфейс настройки осей (полок) в конструкторе компонента.

Реализуя функции предоставляемые API, можно скрывать многие элементы интерфейса, менять логику сортировки, логику формирования подписей и т.д. Доступные функции кастомизации выбраны так, чтобы ими можно было реализовать интерфейс настройки полок любой из существующих диаграмм ядра проекта.

5 Отладка

Запуск проекта в dev-режиме выполняется npm-скриптом start:dev.

По умолчанию сервер доступен на порту 7000. Поменять порт можно через настройку server_port в конфиге (\config\index.js).

Когда проект запустился без ошибок, надо перейти в режим редактирования отчета и создать новый компонент dev.

Он должен быть доступен в самом низу панели выбора компонентов.

Сорсмапы плагина должны быть доступны для отладки в ветке CustomChart0 вкладки sources.

6 Сборка плагина

Запуск сборки выполняется в терминале: ​​​​​​​

npm run build:prod

Файл сборки плагина (plugin.js) появляется в папке \build 

7 Создание дистрибутива плагина

Чтобы создать дистрибутив плагина положите рядом со сборкой файл манифеста manifest.json и запустите скрипт в терминале: node create-plugin.js

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

В результате запуска скрипта появится файл дистрибутива: plugin.tar.gz

8 Загрузка плагина на АП

Загрузка плагина на портал выполняется в разделе «Компоненты» вкладки «Настройки» Аналитического портала.

Дистрибутив плагина загрузите в библиотеку плагинов и затем свяжите загруженный плагин с одним из доступных слотов.

После перезагрузки страницы плагин должен стать доступен в редакторе компонентов.