# Довідник розширених налаштувань моделей Custom Data

Довідник описує додаткові опції полів і моделей Custom Data. У v2 більшість параметрів задається в **Редакторі моделі Custom Data** (вкладки **Поля**, **Графіки**, **UI-налаштування**, **Відображення полів**); розширені ключі — через перемикач **JSON** або цей довідник.

**Коли використовувати:** приховати поля, валідація, графіки, підсвітка рядків, карта або слайдер у картці запису, макроси. Для типових типів полів див. [Семантичні типи полів](/uk/customdata/reference/semantic-field-types-reference.md). Кейси — [Складні кейси Custom Data](/uk/customdata/explanation/advanced-custom-data-cases.md).

---

## 1. Базові параметри полів

| Опція | Призначення | Приклад |
|-------|-------------|---------|
| **label** | Назва поля для відображення в UI (замість технічного ключа) | «Назва магазину», «Дата створення» |
| **default** | Значення за замовчуванням при створенні запису | Статус «Нова», дата сьогодні |
| **unique** | Унікальність значення — створює UNIQUE index у БД | Email, телефон, код |

---

## 2. Видимість полів

| Опція | Призначення | Приклад |
|-------|-------------|---------|
| **hidden_in_table** | Приховати колонку у виборі колонок (columns chooser). Користувач може увімкнути її вручну. | Внутрішній код постачальника — не в щоденній таблиці, але може знадобитися для експорту |
| **hidden_all** | Приховати поле скрізь: таблиця, модальне вікно, фільтри | Службове поле для інтеграції |
| **hide_in_filter** | Приховати поле у панелі фільтрів | Поле «Коментар» — фільтрувати по ньому незручно |
| **hidden_in_create_popup** | Приховати поле в модальному вікні створення нового запису | Поле «Створено з» — заповнюється автоматично |

---

## 3. Зв'язки між таблицями (Association)

| Опція | Призначення | Приклад |
|-------|-------------|---------|
| **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 | Фото магазинів у вигляді слайдера |

---

## 4. Валідація та правила

| Опція | Призначення | Приклад |
|-------|-------------|---------|
| **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), якщо інше поле не пусте | |

---

## 5. Відображення в таблиці

| Опція | Призначення | Приклад |
|-------|-------------|---------|
| **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` | Колонка «Сума» з підсумком |

---

## 6. Статистика та графіки (statistics_json)

Масив об'єктів — кожен об'єкт описує один графік (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 |

---

## 7. Модальне вікно та стилізація (front_json)

### modal_entity

| Опція | Призначення | Приклад |
|-------|-------------|---------|
| **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` | «Призначити штраф» — створити і прив'язати |

### table_stylization

| Опція | Призначення | Приклад |
|-------|-------------|---------|
| **total_row** | Показати підсумковий рядок внизу таблиці (для полів з total_sum) | Сума по колонці «Сума» |
| **colorize** | Підсвітка рядка або комірки. Параметри: `what` (cell/row), `field` (колонка), `param_name` (ключ для кольору), `opacity` (0–1), `params_array` (масив ключів для маппінгу) | Статус «Прострочено» — червоний рядок |

### macros

**Навіщо:** Дозволити оператору запускати процеси (макроси) сценарію бота прямо з таблиці Custom Data — для кожного запису окремо. Наприклад: відправити клієнту повідомлення, створити заявку в зовнішній системі, запустити обробку. Дані запису передаються в сценарій як контекст.

**Як працює:** У таблиці з'являється кнопка (іконка блискавки) в кожному рядку. Оператор натискає її → відкривається діалог вибору макросу зі списку процесів обраного бота → після вибору відкривається віджет з ботом, дані запису (id, поля) передаються в сценарій. Макроси — це секції сценарію, позначені як процеси (is_macro).

| Опція | Призначення | Приклад |
|-------|-------------|---------|
| **bot_id** | ID бота, у сценарії якого є макроси (процеси) | Бот обробки заявок |
| **single** | `true` — кнопка в кожному рядку (запуск для одного запису) | «Відправити нагадування» для кожної заявки |
| **multiple** | `true` — кнопка для множинного вибору (масовий запуск) | Запустити процес для кількох обраних записів |

---

## 8. Файли

| Опція | Призначення | Приклад |
|-------|-------------|---------|
| **edit_type: file_upload** (STRING) | Завантажити один файл, зберегти URL | Поле «Логотип» |
| **file_upload: true** (JSON) | Завантажити кілька файлів. Зберігається як `{ files: [{ name, url }] }` | Поле «Вкладення» — кілька документів |

---

## 9. Підсвітка за умовами (highlight_rules)

**Навіщо:** Візуально виділити комірку кольором залежно від умови — наприклад, червоний, якщо фактичний час менший за плановий (прострочення), зелений — якщо все в порядку. Оператор швидко бачить проблемні записи без перегляду кожного рядка.

**Як працює:** Для кожного рядка система порівнює значення двох полів за вказаною умовою (менше, більше, дорівнює). Якщо умова виконується — комірка підсвічується кольором. Правила перевіряються по черзі; перше спрацьоване визначає колір.

**Де:** У `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"}]` — якщо фактичний < планового → червоний |

---

## 10. Спеціальні імена полів (column_name)

**Навіщо:** Показати поле не як звичайний текст або число, а як карту, графік, слайдер фото або чат. Наприклад, для торгової точки — карта з координатами, для товару — слайдер зображень.

**Як працює:** У `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)

---

## 11. Side cases (важливі комбінації та обмеження)

### columns_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:** правила перевіряються по черзі; перше спрацьоване визначає колір комірки.

### front_json
- **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).

### statistics_json
- **group_by на неіснуюче поле:** можлива помилка або порожній результат.
- **sum_field не числовий:** для `measure: "sum"` — некоректний результат.
- **association без model_field_label:** якщо `group_by` вказує на поле з association — на осі X будуть id замість назв.

---

## 12. Де налаштовувати в UI v2

| Опція / тема | Вкладка редактора | Примітка |
|--------------|-------------------|----------|
| Тип поля, rules, association, system_ref | **Поля** | Семантичні типи — [довідник](/uk/customdata/reference/semantic-field-types-reference.md) |
| Графіки count/sum | **Графіки** | Генератори на основі полей таблиці |
| total_row, colorize, macros | **UI-налаштування** | **Стилізація таблиці**, **Макроси** |
| modal_entity, групи картки | **Відображення полів** | Toggle **Таблиця** / **Картка**, **Групи картки запису** |
| highlight_rules (legacy JSON) | **Поля** або JSON | У таблиці записів — **Підсвітка по полю…** з меню колонки |
| Збережені зрізи (фільтр) | Перегляд записів | Не частина columns_json — [Збережені зрізи](/uk/customdata/how-to/use-saved-views.md) |

---

## Пов'язані документи

- [Складні кейси Custom Data](/uk/customdata/explanation/advanced-custom-data-cases.md) — коли і навіщо використовувати ці опції
- [Патерни та приклади Custom Data](/uk/customdata/explanation/custom-data-patterns-and-examples.md) — типові сценарії
- [Що таке Custom Data](/uk/customdata/explanation/what-is-custom-data.md) — основні концепції
- [Інтегратор — Custom Data](/uk/customdata/integrator-hub.md) — навігація по всіх інструкціях