Поля

Поле — это один ввод в блоке или таблице. То, что заполняет менеджер, и то, что потом читает шаблон.

Поля принадлежат блоку или таблице и правятся внутри них — PageBlocks → Конструктор, затем блок или таблица, затем её поля.

Что содержит строка поля

Настройка	Что делает
Подпись	Что менеджер видит над вводом
Имя поля	Ключ в данных. Именно его читает шаблон: {$block->subtitle}
Тип поля	Какой ввод рисуется — см. Типы полей
Значение по умолчанию	Подставляется в новую строку
Ширина поля	Процент от строки формы, по умолчанию 100. Два поля по 50 встанут рядом
Описание поля	Подсказка под вводом
Обязательное	Не даёт сохранить пустым
Вкладка	На какой вкладке поле появится
Порядок	Место среди соседей; его пишет перетаскивание

Плюс три флага, которые на форме не делают ничего, а за её пределами — всё:

Флаг	Где проявляется
Искомое	Поле участвует в поиске по таблице
Фильтруемое	Поле появляется в pbFilters и по нему можно фильтровать через API
Зависимое	Поле показывается, только когда другое поле удовлетворяет условию

Имя поля — это контракт

Подпись переименовывается свободно, её видит только человек. Имя поля — это ключ, под которым лежит значение, поэтому переименование после того, как контент уже заполнен, осиротит данные: старый ключ останется в data, новый начнётся пустым.

Никакого предупреждения не будет: со стороны базы переименование и новое поле выглядят одинаково. Решайте имя до того, как поле начнут заполнять, а если переименовать всё-таки нужно — переносите данные сами.

За полем не стоит колонка

Значение поля живёт в JSON-колонке своей строки, а не в отдельной колонке таблицы. Поэтому добавление поля не требует миграции — и поэтому имя поля может быть любым, схеме до него дела нет. См. Модели.

Зависимые поля

Поле с включённым флагом Зависимое скрыто, пока другое поле на той же форме не удовлетворит условию. Вы выбираете, от какого поля оно зависит и по какому оператору.

Это для форм с ветвлением: селект «способ доставки» и адрес, который появляется только для курьера. Без этого поля всех вариантов висят на экране разом, и менеджер должен сам знать, какие из них относятся к делу.

Флаг выключен или поле зависимости не выбрано — поле видно всегда.

Фильтруемое и искомое — разное

Выглядят как два названия одного и того же, но это не так:

• Искомое питает текстовый поиск по таблице — одна строка поиска, много полей.
• Фильтруемое даёт полю собственный элемент управления: селект, диапазон, календарь в pbFilters и разрешённый ключ filter[...] в API.

Поле фильтруемое, но не искомое — нормально: например, цена. Обратное так же нормально для длинного описания.

Фильтру в API нужен этот флаг

«Фильтр не работает» через API почти всегда означает, что поле не отметили фильтруемым. Ошибки при этом не будет: неизвестный ключ фильтра игнорируется молча.

Ширина делает форму читаемой

Ширина задаётся в процентах, поэтому 50 + 50 ставят два поля в одну строку, 33 — три. Дата рядом со временем, город рядом с индексом: форма, где связанные поля стоят вместе, читается взглядом, а не прокруткой.

Порядок и публикация

Порядок пишет перетаскивание. Неопубликованное поле исчезает с формы, но данные сохраняет, — это безопасный способ вывести поле из обращения: спрятать, убедиться, что ничего не отвалилось, удалить потом.