Довідник описує додаткові опції полів і моделей, які доступні при створенні або редагуванні моделі Custom Data. Вони налаштовуються в JSON-структурі моделі (вкладка «Створити/Оновити»). Для більшості простих таблиць достатньо базових типів полів; цей довідник — для інтеграторів, які проектують складні моделі.
Коли використовувати: якщо потрібно приховати поля, додати валідацію, графіки, кольорову підсвітку рядків, карту або слайдер у модальному вікні. Детальніше про кейси — у статті Складні кейси Custom Data.
| Опція | Призначення | Приклад |
|---|
| label | Назва поля для відображення в UI (замість технічного ключа) | «Назва магазину», «Дата створення» |
| default | Значення за замовчуванням при створенні запису | Статус «Нова», дата сьогодні |
| unique | Унікальність значення — створює UNIQUE index у БД | Email, телефон, код |
| Опція | Призначення | Приклад |
|---|
| hidden_in_table | Приховати колонку у виборі колонок (columns chooser). Користувач може увімкнути її вручну. | Внутрішній код постачальника — не в щоденній таблиці, але може знадобитися для експорту |
| hidden_all | Приховати поле скрізь: таблиця, модальне вікно, фільтри | Службове поле для інтеграції |
| hide_in_filter | Приховати поле у панелі фільтрів | Поле «Коментар» — фільтрувати по ньому незручно |
| hidden_in_create_popup | Приховати поле в модальному вікні створення нового запису | Поле «Створено з» — заповнюється автоматично |
| Опція | Призначення | Приклад |
|---|
| model_name, model_field, model_field_label | Зв'язати поле з іншою моделлю; зберігати id, показувати назву | Поле «Категорія» — вибір з моделі «Категорії» |
| type | Тип зв'язку: one-to-one, one-to-many, mtm (many-to-many). Для mtm потрібні through_model_name та other_field_name | Товари ↔ Теги через проміжну таблицю |
| as | Псевдонім для зв'язку; без нього колонка може не показуватися в таблиці | |
| attributes | Список полів з пов'язаної моделі для отримання (для слайдера, fetch_on_create) | ["image_url", "name"] |
| fetch_filter | Обмежити варіанти у випадаючому списку | Показувати тільки активні статуси |
| fetch_limit | Ліміт варіантів у випадаючому списку (за замовчуванням 10000) | |
| fetch_on_create | При створенні з пов'язаної моделі підтягувати додаткові поля | При виборі «Товар» показувати ціну та артикул |
| auto_select_first | Автоматично вибрати перший варіант | Поле «Тип» за замовчуванням «Нова» |
| auto_select_associated_on_change | При зміні одного поля автоматично вибрати значення в іншому. Поля мають бути hidden_in_create_popup | |
| subtype: show_image_in_slider | Показати зображення з пов'язаної моделі як слайдер. Потрібен attributes з полями-URL | Фото магазинів у вигляді слайдера |
| Опція | Призначення | Приклад |
|---|
| rules | Масив правил: required, email, digits, latin, latinDigits, stringMaxLength, minLimit, custom_minLimit_N, custom_maxLimit_N, json | Email — ["required", "email"]; код — ["required", "digits"] |
| string_input | Ввід дати/часу для STRING: type: "date" або "time", format: "DD.MM.YYYY" або "HH:mm" | Дата народження, час початку |
| validate.required_field_empty | Ім'я поля — поточне поле disabled, якщо вказане поле пусте | «Час закінчення» недоступне, поки не вказано «Час початку» |
| validate.required_field_not_empty | Ім'я поля — поточне поле disabled, якщо вказане поле НЕ пусте | Поле «Заміна» недоступне, якщо є «Основне значення» |
| validate.disabled_in_table_on_edit | Заборонити редагування в таблиці, якщо поле вже має значення | «Дата створення» — тільки при створенні |
| validate.rules | Валідація дати/часу: type, val_from_field, action (gt/lt), ignore_in_table | Час закінчення > час початку |
| validate.disable_clearable | Відключити очищення поля (для date/time), якщо інше поле не пусте | |
| Опція | Призначення | Приклад |
|---|
| width | Ширина колонки (наприклад, "200") | |
| align | Вирівнювання заголовка: start, center, end | |
| display_in_table: image | Показати зображення за URL замість тексту | Колонка «Фото» з мініатюрою |
| display_type: link | Відобразити значення як клікабельне посилання | Поле «Сайт магазину» |
| click_action: open | Кнопка для швидкого відкриття модального вікна | Колонка «Дії» з кнопкою «Відкрити» |
| non_editable | Заборонити редагування в таблиці (inline) | Поле «ID» або «Створено» |
| sortable | Дозволити або забороняти сортування по колонці | Вимкнути для «Коментар» |
| total_sum | Показати підсумкову суму внизу таблиці. Потрібно front_json.table_stylization.total_row: true | Колонка «Сума» з підсумком |
Масив об'єктів — кожен об'єкт описує один графік (bar chart).
| Опція | Призначення | Приклад |
|---|
| type | Тип графіка (наразі підтримується bar) | |
| color | Колір графіка (HEX) | "#2A9D8F" |
| label | Підпис графіка | «Сума за категоріями» |
| measure | count — кількість записів; sum — сума по полю | |
| group_by | Поле для групування (ось X). Якщо association — показуються назви замість id | status_id, category_id |
| sum_field | Поле для підсумовування (обов'язкове для measure: sum) | amount, quantity, price |
| Опція | Призначення | Приклад |
|---|
| type: MAP | Карта з координатами. Параметри: latitude_key, longitude_key — ключі з рядка для широти/довготи | Торгові точки — карта з адресами |
| type: SLIDER | Слайдер зображень. Параметр img_fields — масив ключів з рядка для URL | Товари — кілька фото |
| type: CHART | Графік у модальному вікні | Менеджери — графік продажів |
| label_from_column_name | Взяти label з columns_json за вказаним ключем | |
| editable | Дозволити або заборонити редагування в модальному вікні | Поле «Створено» — тільки перегляд |
| icon, icon_color | Іконка MDI та колір | mdi-phone, red |
| expansion-panels | Масив секцій: label, header_color, icon, icon_color, items (об'єкт полів) | Секція «Адреса» з полями |
| create_association_row | Кнопка створення запису в пов'язаній таблиці. Параметри: type: "CREATE_ASSOCIATION_ROW", label, from (модель), to (поле), show_if_result, label_if_result, icon, icon_color, save_by_permission | «Призначити штраф» — створити і прив'язати |
| Опція | Призначення | Приклад |
|---|
| total_row | Показати підсумковий рядок внизу таблиці (для полів з total_sum) | Сума по колонці «Сума» |
| colorize | Підсвітка рядка або комірки. Параметри: what (cell/row), field (колонка), param_name (ключ для кольору), opacity (0–1), params_array (масив ключів для маппінгу) | Статус «Прострочено» — червоний рядок |
Навіщо: Дозволити оператору запускати процеси (макроси) сценарію бота прямо з таблиці Custom Data — для кожного запису окремо. Наприклад: відправити клієнту повідомлення, створити заявку в зовнішній системі, запустити обробку. Дані запису передаються в сценарій як контекст.
Як працює: У таблиці з'являється кнопка (іконка блискавки) в кожному рядку. Оператор натискає її → відкривається діалог вибору макросу зі списку процесів обраного бота → після вибору відкривається віджет з ботом, дані запису (id, поля) передаються в сценарій. Макроси — це секції сценарію, позначені як процеси (is_macro).
| Опція | Призначення | Приклад |
|---|
| bot_id | ID бота, у сценарії якого є макроси (процеси) | Бот обробки заявок |
| single | true — кнопка в кожному рядку (запуск для одного запису) | «Відправити нагадування» для кожної заявки |
| multiple | true — кнопка для множинного вибору (масовий запуск) | Запустити процес для кількох обраних записів |
| Опція | Призначення | Приклад |
|---|
| edit_type: file_upload (STRING) | Завантажити один файл, зберегти URL | Поле «Логотип» |
| file_upload: true (JSON) | Завантажити кілька файлів. Зберігається як { files: [{ name, url }] } | Поле «Вкладення» — кілька документів |
Навіщо: Візуально виділити комірку кольором залежно від умови — наприклад, червоний, якщо фактичний час менший за плановий (прострочення), зелений — якщо все в порядку. Оператор швидко бачить проблемні записи без перегляду кожного рядка.
Як працює: Для кожного рядка система порівнює значення двох полів за вказаною умовою (менше, більше, дорівнює). Якщо умова виконується — комірка підсвічується кольором. Правила перевіряються по черзі; перше спрацьоване визначає колір.
Де: У columns_json у полі, колонка якого має підсвічуватися. Підтримується для STRING, TEXT, FLOAT, INTEGER, BIGINT.
| Опція | Призначення | Приклад |
|---|
| type | "time" — для порівняння часів (рядки у форматі HH:mm) | |
| rules | Масив правил. Кожне правило: "0" — ім'я першого поля, "1" — другого, action (lt/gt/eq/gte/lte), color (red, green, #ff0000) | [{"0":"actual_time","1":"planned_time","action":"lt","color":"red"}] — якщо фактичний < планового → червоний |
Навіщо: Показати поле не як звичайний текст або число, а як карту, графік, слайдер фото або чат. Наприклад, для торгової точки — карта з координатами, для товару — слайдер зображень.
Як працює: У columns_json створюється поле з технічним ключем cd_map, cd_chart, cd_image_slider, cd_image_list або cd_chat. У front_json.modal_entity для цього ключа задається конфігурація (latitude_key/longitude_key для карти, img_fields для слайдера). При відкритті модального вікна замість звичайного поля відображається відповідний компонент.
| Ключ | Призначення | Коли використовувати |
|---|
cd_map | Карта з координатами | Торгові точки, адреси доставки |
cd_chart | Графік у модальному вікні | Менеджери — графік продажів по запису |
cd_image_slider | Слайдер зображень | Товари, фото магазинів |
cd_image_list | Список зображень | Кілька фото без слайдера |
cd_chat | Чат | Історія листування по запису |
Поля конфігурації (у front_json.modal_entity для кожного ключа):
- cd_map:
type: "MAP", latitude_key — ключ для широти, longitude_key — для довготи - cd_image_slider:
type: "SLIDER", img_fields — масив ключів з рядка для URL (наприклад, ["outlet_image"] або ["photo1", "photo2"]) - cd_chart:
type: "CHART", label, editable - cd_image_list: аналогічно слайдеру — поля з URL
- cd_chat: дані зберігаються в полі рядка (JSON)
- hidden_all vs hidden_in_table:
hidden_all виключає колонку повністю (таблиця, модальне, фільтри). hidden_in_table — колонка прихована за замовчуванням у columns chooser, але користувач може її увімкнути. - total_sum: працює тільки разом з
front_json.table_stylization.total_row: true. Без total_row підсумковий рядок не показується. - association без as: колонка з association може не відображатися в таблиці. Додай
as для коректного показу. - mtm (many-to-many): обов'язкові додаткові параметри
through_model_name та other_field_name. - validate: якщо поле A має
required_field_empty: "B", а B — required_field_not_empty: "A", можливий цикл залежностей. - highlight_rules: правила перевіряються по черзі; перше спрацьоване визначає колір комірки.
- modal_entity vs columns_json: якщо ключ є тільки в
modal_entity, але не в columns_json — поле не буде в таблиці та фільтрах. Якщо тільки в columns_json — DynamicModalEntity може не показати його в модальному вікні (залежить від конфігурації). - expansion-panels items: поля в
items мають відповідати ключам з columns_json, інакше значення не відобразиться. - colorize: для Custom Data зазвичай достатньо
param_name + колонки з HEX. params_array — для складніших маппінгів (OperatorPanel).
- group_by на неіснуюче поле: можлива помилка або порожній результат.
- sum_field не числовий: для
measure: "sum" — некоректний результат. - association без model_field_label: якщо
group_by вказує на поле з association — на осі X будуть id замість назв.