# Advanced Model Options Reference

This reference describes additional options for Custom Data fields and models. In v2 most settings live in the **Custom Data model editor** (**Fields**, **Statistics**, **UI settings**, **Field display** tabs); advanced keys use the **JSON** toggle or this reference.

**When to use:** hide fields, validation, charts, row highlighting, map or slider in the record card, macros. For common field types see [Semantic field types](/en/customdata/reference/semantic-field-types-reference.md). Use cases — [Advanced Custom Data cases](/en/customdata/explanation/advanced-custom-data-cases.md).

---

## 1. Basic Field Parameters

| Option | Purpose | Example |
|--------|---------|---------|
| **label** | Field label for UI display (instead of technical key) | "Store name", "Created at" |
| **default** | Default value when creating a record | Status "New", today's date |
| **unique** | Unique value — creates UNIQUE index in DB | Email, phone, code |

---

## 2. Field Visibility

| Option | Purpose | Example |
|--------|---------|---------|
| **hidden_in_table** | Hide column in columns chooser. User can enable it manually. | Internal supplier code — not in daily table, but may be needed for export |
| **hidden_all** | Hide field everywhere: table, modal, filters | Service field for integration |
| **hide_in_filter** | Hide field in filter panel | "Comment" field — filtering by it is impractical |
| **hidden_in_create_popup** | Hide field in create-record modal | "Created from" — filled automatically |

---

## 3. Table Associations

| Option | Purpose | Example |
|--------|---------|---------|
| **model_name, model_field, model_field_label** | Link field to another model; store id, show label | "Category" — select from Categories model |
| **type** | Association type: `one-to-one`, `one-to-many`, `mtm` (many-to-many). For `mtm` need `through_model_name` and `other_field_name` | Products ↔ Tags via junction table |
| **as** | Alias for association; without it column may not show in table | |
| **attributes** | List of fields from related model to fetch (for slider, fetch_on_create) | `["image_url", "name"]` |
| **fetch_filter** | Limit options in dropdown | Show only active statuses |
| **fetch_limit** | Limit for dropdown options (default 10000) | |
| **fetch_on_create** | When creating from related model, pull additional fields | When selecting "Product" show price and SKU |
| **auto_select_first** | Auto-select first option | "Type" defaults to "New" |
| **auto_select_associated_on_change** | When one field changes, auto-select value in another. Fields must be `hidden_in_create_popup` | |
| **subtype: show_image_in_slider** | Show images from related model as slider. Requires `attributes` with URL fields | Store photos as slider |

---

## 4. Validation and Rules

| Option | Purpose | Example |
|--------|---------|---------|
| **rules** | Array of rules: `required`, `email`, `digits`, `latin`, `latinDigits`, `stringMaxLength`, `minLimit`, `custom_minLimit_N`, `custom_maxLimit_N`, `json` | Email — `["required", "email"]`; code — `["required", "digits"]` |
| **string_input** | Date/time input for STRING: `type: "date"` or `"time"`, `format: "DD.MM.YYYY"` or `"HH:mm"` | Birth date, start time |
| **validate.required_field_empty** | Field name — current field disabled if specified field is empty | "End time" unavailable until "Start time" is set |
| **validate.required_field_not_empty** | Field name — current field disabled if specified field is NOT empty | "Replacement" unavailable if "Primary value" exists |
| **validate.disabled_in_table_on_edit** | Disable editing in table if field already has value | "Created at" — only on create |
| **validate.rules** | Date/time validation: `type`, `val_from_field`, `action` (gt/lt), `ignore_in_table` | End time > start time |
| **validate.disable_clearable** | Disable clearing field (for date/time) if another field is not empty | |

---

## 5. Table Display

| Option | Purpose | Example |
|--------|---------|---------|
| **width** | Column width (e.g. `"200"`) | |
| **align** | Header alignment: `start`, `center`, `end` | |
| **display_in_table: image** | Show image by URL instead of text | "Photo" column with thumbnail |
| **display_type: link** | Display value as clickable link | "Store website" field |
| **click_action: open** | Button to quickly open edit modal | "Actions" column with "Open" button |
| **non_editable** | Disable inline editing in table | "ID" or "Created" field |
| **sortable** | Allow or disable column sorting | Disable for "Comment" |
| **total_sum** | Show total sum at bottom of table. Requires `front_json.table_stylization.total_row: true` | "Amount" column with total |

---

## 6. Statistics and Charts (statistics_json)

Array of objects — each object describes one chart (bar chart).

| Option | Purpose | Example |
|--------|---------|---------|
| **type** | Chart type (currently only `bar` supported) | |
| **color** | Chart color (HEX) | `"#2A9D8F"` |
| **label** | Chart label | "Total by category" |
| **measure** | `count` — record count; `sum` — sum by field | |
| **group_by** | Field for grouping (X axis). If association — labels shown instead of id | status_id, category_id |
| **sum_field** | Field to sum (required for measure: sum) | amount, quantity, price |

---

## 7. Modal Window and Styling (front_json)

### modal_entity

| Option | Purpose | Example |
|--------|---------|---------|
| **type: MAP** | Map with coordinates. Params: `latitude_key`, `longitude_key` — keys from row for lat/long | Stores — map with addresses |
| **type: SLIDER** | Image slider. Param `img_fields` — array of keys from row for URLs | Products — multiple photos |
| **type: CHART** | Chart in modal | Managers — sales chart |
| **label_from_column_name** | Take label from columns_json by specified key | |
| **editable** | Allow or disable editing in modal | "Created" — read-only |
| **icon, icon_color** | MDI icon and color | `mdi-phone`, `red` |
| **expansion-panels** | Array of sections: `label`, `header_color`, `icon`, `icon_color`, `items` (fields object) | "Address" section with fields |
| **create_association_row** | Button to create record in related table. Params: `type: "CREATE_ASSOCIATION_ROW"`, `label`, `from` (model), `to` (field), `show_if_result`, `label_if_result`, `icon`, `icon_color`, `save_by_permission` | "Assign penalty" — create and link |

### table_stylization

| Option | Purpose | Example |
|--------|---------|---------|
| **total_row** | Show total row at bottom of table (for fields with total_sum) | Sum for "Amount" column |
| **colorize** | Highlight row or cell. Params: `what` (cell/row), `field` (column), `param_name` (key for color), `opacity` (0–1), `params_array` (keys for mapping) | "Overdue" status — red row |

### macros

**Purpose:** Let the operator run bot scenario processes (macros) directly from the Custom Data table — for each record separately. E.g., send a message to the client, create a request in an external system, trigger processing. Record data is passed to the scenario as context.

**How it works:** A button (lightning icon) appears in each table row. Operator clicks it → dialog opens to select a macro from the chosen bot's process list → after selection, a widget with the bot opens; record data (id, fields) is passed to the scenario. Macros are scenario sections marked as processes (is_macro).

| Option | Purpose | Example |
|--------|---------|---------|
| **bot_id** | ID of the bot whose scenario contains macros (processes) | Request processing bot |
| **single** | `true` — button in each row (run for one record) | "Send reminder" for each request |
| **multiple** | `true` — button for multi-select (bulk run) | Run process for several selected records |

---

## 8. Files

| Option | Purpose | Example |
|--------|---------|---------|
| **edit_type: file_upload** (STRING) | Upload single file, store URL | "Logo" field |
| **file_upload: true** (JSON) | Upload multiple files. Stored as `{ files: [{ name, url }] }` | "Attachments" — multiple documents |

---

## 9. Conditional Highlighting (highlight_rules)

**Purpose:** Visually highlight a cell by color based on a condition — e.g., red if actual time is less than planned (overdue), green if OK. Operator quickly spots problematic records without scanning each row.

**How it works:** For each row, the system compares values of two fields by the specified condition (less than, greater than, equal). If the condition is met — the cell is highlighted. Rules are checked in order; the first match determines the color.

**Where:** In `columns_json` on the field whose column should be highlighted. Supported for STRING, TEXT, FLOAT, INTEGER, BIGINT.

| Option | Purpose | Example |
|--------|---------|---------|
| **type** | `"time"` — for time comparison (strings in HH:mm format) | |
| **rules** | Array of rules. Each rule: `"0"` — first field name, `"1"` — second, `action` (lt/gt/eq/gte/lte), `color` (red, green, #ff0000) | `[{"0":"actual_time","1":"planned_time","action":"lt","color":"red"}]` — if actual < planned → red |

---

## 10. Special Field Names (column_name)

**Purpose:** Display a field not as plain text or number, but as a map, chart, image slider, or chat. E.g., for a store — map with coordinates, for a product — image slider.

**How it works:** In `columns_json` create a field with technical key `cd_map`, `cd_chart`, `cd_image_slider`, `cd_image_list`, or `cd_chat`. In `front_json.modal_entity` configure it (latitude_key/longitude_key for map, img_fields for slider). When the modal opens, the corresponding component is shown instead of a regular field.

| Key | Purpose | When to use |
|-----|---------|-------------|
| `cd_map` | Map with coordinates | Stores, delivery addresses |
| `cd_chart` | Chart in modal | Managers — sales chart per record |
| `cd_image_slider` | Image slider | Products, store photos |
| `cd_image_list` | Image list | Multiple photos without slider |
| `cd_chat` | Chat | Message history per record |

**Configuration fields** (in `front_json.modal_entity` for each key):

- **cd_map:** `type: "MAP"`, `latitude_key` — key for latitude, `longitude_key` — for longitude
- **cd_image_slider:** `type: "SLIDER"`, `img_fields` — array of keys from row for URLs (e.g. `["outlet_image"]` or `["photo1", "photo2"]`)
- **cd_chart:** `type: "CHART"`, `label`, `editable`
- **cd_image_list:** similar to slider — fields with URLs
- **cd_chat:** data stored in row field (JSON)

---

## 11. Side Cases (Important Combinations and Limitations)

### columns_json
- **hidden_all vs hidden_in_table:** `hidden_all` excludes the column entirely (table, modal, filters). `hidden_in_table` — column is hidden by default in columns chooser, but the user can enable it.
- **total_sum:** works only with `front_json.table_stylization.total_row: true`. Without total_row the total row is not shown.
- **association without as:** a column with association may not display in the table. Add `as` for correct display.
- **mtm (many-to-many):** additional parameters `through_model_name` and `other_field_name` are required.
- **validate:** if field A has `required_field_empty: "B"` and B has `required_field_not_empty: "A"`, a dependency cycle is possible.
- **highlight_rules:** rules are checked in order; the first match determines the cell color.

### front_json
- **modal_entity vs columns_json:** if a key exists only in `modal_entity` but not in `columns_json` — the field will not appear in the table or filters. If only in `columns_json` — DynamicModalEntity may not show it in the modal (depends on configuration).
- **expansion-panels items:** fields in `items` must match keys from `columns_json`, otherwise values will not display.
- **colorize:** for Custom Data usually `param_name` + column with HEX is enough. `params_array` — for more complex mappings (OperatorPanel).

### statistics_json
- **group_by on non-existent field:** may cause an error or empty result.
- **sum_field not numeric:** for `measure: "sum"` — incorrect result.
- **association without model_field_label:** if `group_by` points to a field with association — ids will appear on X axis instead of names.

---

## 12. Where to configure in v2 UI

| Option / topic | Editor tab | Note |
|----------------|------------|------|
| Field type, rules, association, system_ref | **Fields** | Semantic types — [reference](/en/customdata/reference/semantic-field-types-reference.md) |
| count/sum charts | **Statistics** | Generators based on table fields |
| total_row, colorize, macros | **UI settings** | **Table styling**, **Macros** |
| modal_entity, card groups | **Field display** | **Table** / **Card** toggles, **Record card groups** |
| highlight_rules (legacy JSON) | **Fields** or JSON | In records view — **Highlight by field…** from column menu |
| Saved views (filters) | Records view | Not part of columns_json — [Saved views](/en/customdata/how-to/use-saved-views.md) |

---

## Related Documents

- [Advanced Custom Data Cases](/en/customdata/explanation/advanced-custom-data-cases.md) — when and why to use these options
- [Custom Data Patterns and Examples](/en/customdata/explanation/custom-data-patterns-and-examples.md) — typical scenarios
- [What is Custom Data](/en/customdata/explanation/what-is-custom-data.md) — core concepts
- [Integrator — Custom Data](/en/customdata/integrator-hub.md) — navigation through all instructions