ptnl-constructor-sdk
v0.13.1
Published
Набор инструментов для создания виджетов.
Downloads
68
Readme
Constructor SDK
Конфигурация виджета
Конфигурацию описывает интерфейс Config
. Рассмотрим пример:
import {
block,
colorize,
Config,
DataQueryFunction,
DataQueryMethod,
filter,
sort,
} from 'ptnl-constructor-sdk/config';
export const config: Config = {
// Имя виджета. Отображается в списке загруженых выджетов
label: {
ru: 'Имя на русском',
en: 'И на английском',
},
// Иконка виджета. Отображается в списке загруженых выджетов
icon: 'icon.svg',
// метаданные для формирования документации виджета
documentation: {
// путь до файла в формате markdown с документацией
readme: 'widget/README.md',
// путь до папки и контентом для документации
assetsDirectory: 'widget/documentation-assets',
// пути к файлам превью виджета
images: [
'widget/documentation-assets/preview-1',
'widget/documentation-assets/preview-2',
],
},
// см. Настройка получения виджетом данных
dataSettings: {
// см. Метод группировки данных
method: DataQueryMethod.Aggregate,
//
blocks: [
block({
// По данному ключу можно получить колонки в виджете
// this.dataSettings.columnsByBlock['uniq-key']
key: 'uniq-key',
label: { ru: 'Columns', en: '' },
// Влияет на агрегацию данных
// см. Метод группировки данных
dataQueryFunction: DataQueryFunction.Sum,
}),
// Добавляет блок для колонок, по которым будет осуществляться фильтрация
// Доступны в виджете через this.dataSettings.filters
filter(),
// Добавляет блок для колонок, по которым будет осуществляться сортировка
// Доступны в виджете через this.dataSettings.sort
sort(),
// Добавляет блок для колонок, по которым будет осуществляться раскраска
// Настройки раскраски доступна через
// this.dataSettings.colorize
colorize(),
],
},
};
Настройка получения виджетом данных dataSettings
Параметр конфигурации dataSettings
описывает, из каких колонок датасета требуются данные, способ их фильтрации,
сортировку, а также способ агрегации данных. Чаще всего виджет использует один датасет, но если требуется несколько
датасетов, в конфигурации необходимо указать описание каждого в массиве, указав для каждого уникальный ключ:
// ...
dataSettings: [
{
key: 'dataset-1',
label: { ru: 'Первый источник', en: '' },
method: DataQueryMethod.Table,
blocks: [
// ...
],
},
{
key: 'dataset-2',
label: { ru: 'Второй источник', en: '' },
method: DataQueryMethod.Aggregate,
blocks: [
// ...
],
},
],
// ...
По значению ключей в виджете будут доступны данные и настройки (см. SingleData и MultiData)
Метод группировки данных DataQueryMethod
Этот параметр может менять данные из датасета. Для примера рассмотрим исходную таблицу
╔═══╤═══╤═══╗
║ A │ C │ 1 ║
╟───┼───┼───╢
║ A │ C │ 2 ║
╟───┼───┼───╢
║ B │ C │ 7 ║
╚═══╧═══╧═══╝
Для DataQueryMethod.Table
данные вернуться в исходном виде, тогда как для параметра
DataQueryMethod.Aggregate
будет произведена агрегация в зависимоти от параметра dataQueryFunction
у блока. Например, при DataQueryFunction.Sum
происходит суммирование числовых столбцов и
группировка по значением в столбцах других типов. При этом данные в виджет попадут в таком виде:
╔═══╤═══╤═══╗
║ A │ C │ 3 ║
╟───┼───┼───╢
║ B │ C │ 7 ║
╚═══╧═══╧═══╝
Код виджета
Рассмотрим виджет
import { Declare, SingleData, Widget } from 'ptnl-constructor-sdk';
@Declare()
export class Example extends Widget implements SingleData {
readonly data!: SingleData['data'];
readonly dataSettings!: SingleData['dataSettings'];
onChange(): void {
// ...
// ВАЖНО! Метод ready необходимо вызывать после каждого вызова onChange
this.ready();
}
}
Чтобы класс стал виджетом, его необходимо декорировать @Declare()
. Также, благодаря наследованию
от базового класса Widget
, будут доступны для автокомплика методы (например, onThemeChange
) и свойства (например, lang
).
SingleData и MultiData
При конфигурировании можно указать как один, так и несколько источников данных.
В зависимости от этого виджет будет реализовывать один из этих интерфейсов. Например, для нескольких датасетов, данные
для каждого из них будут доступны через key
, указанный в конфигурации:
import { Declare, MultiData, Widget } from 'ptnl-constructor-sdk';
@Declare()
export class WidgetFilters extends Widget implements MultiData {
readonly data!: MultiData['data'];
readonly dataSettings!: MultiData['dataSettings'];
onChange(): void {
this.dataSettings['dataset-key'].dataset.name;
}
Life cycle
Порядок срабатывания хуков виджета:
onThemeChange
при инициализации и при смене темыonLangChange
при инициализации и при смене языкаonInit
при инициализацииonChange
при инициализации и при смене данных
CSS переменные
По умолчанию, css переменные не объявляются. Для их инициализации необходимо указать параметр
provideCssVariables
у декоратора Declare
:
@Declare({
provideCssVariables: true,
})
При этом будут объявлены все переменные, доступные для виджета через this.theme
, но в kebab-case:
/* this.theme.text → --text */
color: var(--text);
/* this.theme.backgroundBright → --background-bright */
background: var(--background-bright);
Настройки виджета (установка параметров при создании)
При создании виджета, пользователь может установить параметры следующих типов:
- input
- checkbox
- radio
- select
- colorPicker
- title (заголовок блока настроек, используется для разделения параметров на блоки)
Эти параметры получаются динамически из вызова функции createViewSettings
в файле src/view-settings.ts
.
Рассмотрим пример. Здесь выводится текстовое поле, в которое можно ввести число от 1 до количества колонок
в блоке с ключом blocke-key
:
import { DataSettings } from 'ptnl-constructor-sdk';
import {
CreateViewSettings,
input,
ViewSettingsValidation,
} from 'ptnl-constructor-sdk/config';
let max = 0;
export const createViewSettings: CreateViewSettings<DataSettings> = ({
dataSettings,
}) => {
max = dataSettings.columnsByBlock['blocke-key'].length;
return [
input({
key: 'number-key',
label: {
ru: `Число от 1 до ${max}`,
en: `Range 1 to ${max}`,
},
}),
];
};
export const validation: ViewSettingsValidation = {
['number-key']: (value: any) => {
const number = parseInt(value);
if (isNaN(number))
return {
ru: 'Значение должно быть числом',
en: 'Not a number',
};
if (number < 1 || number > max)
return {
ru: `Значение должно быть в диапозоне от 1 до ${max}`,
en: `Not in range 1 до ${max}`,
};
return null;
},
};