Макеты форм

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

Базовое использование

Для простейшего макета виджеты не нужны вовсе. Укажите поле по его строковому имени, чтобы оставить его на отдельной строке, а имена полей сгруппируйте в кортеж, чтобы разместить их в одной строке бок о бок.

from starlette_admin.contrib.sqla import ModelView


class EmployeeView(ModelView):
    fields = ["id", "first_name", "last_name", "email", "salary", "notes"]
    form_layout = [
        ("first_name", "last_name"),
        "email",
        ("salary", "notes"),
    ]

В приведённом выше макете:

• ("first_name", "last_name") создаёт одну строку, разделённую поровну между двумя полями ввода.
• "email" отображается на отдельной строке непосредственно под ней.
• ("salary", "notes") создаёт вторую многоколоночную строку.

В строку можно поместить любое количество полей и свободно чередовать одноколоночные и многоколоночные строки.

Контейнерные виджеты сами разворачивают эту сокращённую запись: RowWidget, ColumnWidget, GridWidget, PanelWidget, FieldsetWidget, TabsWidget и Col при создании превращают кортежи в строки, а списки — в вертикальные колонки. Поэтому сокращённая запись работает и внутри вложенных атрибутов children, и внутри дашборда CustomView.widget.

Группировка полей

Панели с заголовками

Чтобы дать группе полей заголовок или сделать её сворачиваемой, оберните её в PanelWidget. Виджет принимает ту же сокращённую запись со строками и кортежами, что и верхний уровень.

from starlette_admin import PanelWidget


class EmployeeView(ModelView):
    fields = ["id", "first_name", "last_name", "email", "salary", "notes"]
    form_layout = [
        PanelWidget(
            title="Identity",
            children=[("first_name", "last_name"), "email"],
        ),
        PanelWidget(
            title="Compensation",
            children=["salary", "notes"],
            collapsible=True,
            collapsed=True,
        ),
    ]

PanelWidget принимает следующие атрибуты:

Если группе не нужен заголовок, используйте вместо этого ColumnWidget. Он выстраивает дочерние элементы вертикально, не оборачивая их в стилизованную карточку.

Fieldsets

FieldsetWidget группирует поля во многом так же, как PanelWidget, но вместо стилизованной карточки отображает нативные HTML-элементы <fieldset> и <legend>. Используйте его, когда нужна более простая группировка с рамкой.

from starlette_admin import FieldsetWidget

form_layout = [
    FieldsetWidget(
        legend="Identity",
        children=[("first_name", "last_name"), "email"],
    ),
    FieldsetWidget(
        legend="Compensation",
        children=["salary", "notes"],
        disabled=True,
    ),
]

Атрибут legend задаёт подпись в элементе <legend>. Значение disabled=True устанавливает HTML-атрибут disabled на контейнере, что отключает все вложенные элементы управления формы. FieldsetWidget поддерживает ту же сокращённую запись для children, что и PanelWidget, но не поддерживает специфичные для панелей опции, такие как collapsible и icon.

Явная ширина колонок

Сокращённая запись через кортеж всегда делит строку поровну. Для более точного управления шириной колонок соберите строку явно с помощью RowWidget, Col и FieldRef:

from starlette_admin import Breakpoints, Col, FieldRef, RowWidget

form_layout = [
    RowWidget(
        children=[
            Col(FieldRef("first_name"), Breakpoints(default=12, md=4)),
            Col(FieldRef("last_name"), Breakpoints(default=12, md=8)),
        ]
    ),
]

Скрытие подписей полей

Явное создание FieldRef даёт доступ к параметру show_label, который убирает элемент <label>, когда окружающий макет уже делает назначение поля очевидным.

from starlette_admin import FieldsetWidget, FieldRef

form_layout = [
    FieldsetWidget(legend="Email", children=[FieldRef("email", show_label=False)]),
]

Параметр show_label по умолчанию равен True. Строковая и кортежная сокращённые записи всегда отображают подписи, поскольку не принимают именованных аргументов.

Группы ввода

Параметры prepend и append прикрепляют дополнение группы ввода к любой из сторон поля ввода. Каждый из них принимает обычный текст или сырой HTML, например иконку Font Awesome.

from starlette_admin import FieldRef

form_layout = [
    FieldRef("email", prepend="@"),
    FieldRef("phone", append='<i class="fa fa-phone"></i>'),
    FieldRef("salary", prepend="$", append="USD"),
]

Дополнения работают с полями, чей шаблон формы отображает нативный элемент <input>: StringField, EmailField, URLField, PhoneField, PasswordField, ColorField, SlugField, числовые поля (IntegerField, DecimalField, FloatField) и поля даты и времени. Другие типы, такие как EnumField, TextAreaField и BooleanField, молча игнорируют их.

Вкладки

Чтобы разбить разделы на интерфейс с вкладками, используйте TabsWidget. Он принимает список пар (label, widgets).

from starlette_admin import TabsWidget

form_layout = [
    TabsWidget(
        tabs=[
            ("Identity", [("first_name", "last_name"), "email"]),
            ("Compensation", ["salary", "notes"]),
        ]
    ),
]

Статический контент

Используйте HtmlWidget и TextWidget, чтобы отобразить произвольный контент в любом месте макета: инструкции, предупреждения или разделители.

from starlette_admin import HtmlWidget, PanelWidget

form_layout = [
    HtmlWidget(html="<p class='text-warning'>Changes here are audited.</p>"),
    PanelWidget(title="Compensation", children=["salary", "notes"]),
]

Собственные виджеты

Поскольку form_layout использует ту же иерархию BaseWidget, что и дашборды, вы можете создать подкласс BaseWidget, чтобы построить собственные элементы. Это «аварийный люк» для всего, чего не покрывают встроенные виджеты: превью только для чтения, встроенных диаграмм или собственных макросов Jinja.

Общий шаблон описан в разделе Custom Views & Widgets, а методы, которые может переопределить подкласс, — в справочнике API виджетов. Собственные виджеты в form_layout отображаются всегда, независимо от правил видимости полей.

Контроль доступа и видимость

form_layout учитывает ваши правила доступа на уровне полей. Каждый FieldRef проходит стандартную проверку can_access_field, а exclude_from_create, exclude_from_edit и права доступа на основе ролей продолжают действовать.

• Расширение строки: если поле в многоколоночной строке скрыто для запроса, оставшиеся видимые поля расширяются, заполняя освободившееся место.
• Пустые контейнеры: если все поля в контейнере (строке, панели, fieldset, колонке, сетке или вкладке) скрыты, контейнер не отображается вовсе, поэтому пустой оболочки никогда не будет.
• Статическое отображение: статические компоненты, такие как HtmlWidget, TextWidget и собственные подклассы BaseWidget, отображаются всегда, поскольку не зависят от полей формы.

Обработка пропущенных полей

Поле, объявленное в fields, но не включённое в form_layout, добавляется в конец формы в порядке объявления, поэтому ни одно поле не теряется незаметно.

Повторное указание одного и того же поля или ссылка на имя, отсутствующее в fields, вызывают исключение ValueError при создании представления.

Что дальше

• Custom Views & Widgets: иерархия виджетов, на которой строится form_layout, и то, как написать собственный виджет.
• Templates: переопределите _form_group.html, чтобы изменить разметку, которую отображает группа макета.
• Fields: типы полей и правила видимости, которые упорядочивает макет.