Справочник: поля форм в схемах¶

Доступные поля форм для использования в админке¶

Формы в админке можно создавать из множества полей. Этот документ содержит полный справочник свойств каждого поля и примеры использования.

Помимо перечисленных ниже полей, можно также использовать все поля, доступные во фронтенд-формах и описанные в справочнике полей форм на сайте.

Специальные поля форм, доступные в админке¶

Общие атрибуты полей¶

Каждое поле принимает список атрибутов. Эти общие атрибуты могут использоваться разными полями, но конкретные поля могут их игнорировать. Лучший способ узнать, какие атрибуты допустимы для поля, — посмотреть описание поля на этой странице и проверить, какие атрибуты упомянуты.

Этот список служит общей основой, чтобы не повторять описание общих полей.

Подробнее о полях¶

Как устроены поля, можно прочитать в исходном коде: поля, добавленные плагином Form и компоненты полей, которые отрисовывает Admin Next.

Валидация¶

Большинство полей поддерживают валидацию.

1
2

validate:
    required: true

помечает поле как обязательное.

1
2

validate:
    message: 'Some message'

показывает заданное сообщение, если поле заполнено неправильно.

1
2

validate:
    pattern: 'Some pattern'

проверяет значение поля по переданному regex-шаблону. Примеры: pattern: "[1-9][0-9]*", pattern: '[A-Za-z0-9-]+', pattern: '[a-z0-9-]+', pattern: '^[a-z0-9_-]{3,16}$', pattern: '(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{8,}'

validate.type¶

validate.type указывает, по какому типу проверять значение.

Несколько примеров:

Редактор будет проверяться как textarea:

1
2
3
4

content:
    type: editor
    validate:
      type: textarea

Selectize будет проверяться как commalist:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

taxonomies:
    type: selectize
    size: large
    label: PLUGIN_ADMIN.TAXONOMY_TYPES
    classes: fancy
    help: PLUGIN_ADMIN.TAXONOMY_TYPES_HELP
    validate:
        type: commalist

filters.category:
  type: selectize
  label: Category filter
  help: Comma separated list of category names
  validate:
    type: commalist

Проверка адреса email:

1
2
3
4
5
6
7

author.email:
    type: text
    size: large
    label: PLUGIN_ADMIN.DEFAULT_EMAIL
    help: PLUGIN_ADMIN.DEFAULT_EMAIL_HELP
    validate:
        type: email

Проверка, что значение — bool:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

summary.enabled:
    type: toggle
    label: PLUGIN_ADMIN.ENABLED
    highlight: 1
    help: PLUGIN_ADMIN.ENABLED_HELP
    options:
        1: PLUGIN_ADMIN.YES
        0: PLUGIN_ADMIN.NO
    validate:
        type: bool

Проверка, что значение — целое число от 0 до 65536:

1
2
3
4
5
6
7
8
9

summary.size:
    type: text
    size: x-small
    label: PLUGIN_ADMIN.SUMMARY_SIZE
    help: PLUGIN_ADMIN.SUMMARY_SIZE_HELP
    validate:
        type: int
        min: 0
        max: 65536

Проверка, что значение — число > 1:

1
2
3
4
5
6
7
8

pages.list.count:
    type: text
    size: x-small
    label: PLUGIN_ADMIN.DEFAULT_PAGE_COUNT
    help: PLUGIN_ADMIN.DEFAULT_PAGE_COUNT_HELP
    validate:
        type: number
        min: 1

Проверка типа таксономии как массива:

1
2
3
4
5
6

header.taxonomy:
  type: taxonomy
  label: PLUGIN_ADMIN.TAXONOMY
  multiple: true
  validate:
    type: array

Проверка текстового поля как slug:

1
2
3
4
5

folder:
  type: text
  label: PLUGIN_ADMIN.FOLDER_NAME
  validate:
    type: slug

Поле Array¶

Тип поля array используется для создания простого списка объектов «ключ — значение» или просто списка значений, если использовать параметр value_only.

Пример:

1
2
3
4
5
6
7

metadata:
   type: array
   label: PLUGIN_ADMIN.METADATA
   help: PLUGIN_ADMIN.METADATA_HELP
   placeholder_key: PLUGIN_ADMIN.METADATA_KEY
   placeholder_value: PLUGIN_ADMIN.METADATA_VALUE
   required: true

Поле Colorpicker¶

Тип поля colorpicker используется для отображения поля выбора цвета.

Пример:

1
2
3
4

color:
   type: colorpicker
   label: Choose a color
   default: '#FFFFFF'

Поля Columns / column¶

Типы полей columns и column используются, чтобы разделить вложенные поля формы на колонки.

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

columns:
  type: columns
  fields:
    column1:
      type: column
      fields:

        # .... подполя

    column2:
      type: column
      fields:

        # .... другие подполя

Поле Dateformat¶

Тип поля dateformat используется для

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

pages.dateformat.short:
    type: dateformat
    size: medium
    classes: fancy
    label: PLUGIN_ADMIN.SHORT_DATE_FORMAT
    help: PLUGIN_ADMIN.SHORT_DATE_FORMAT_HELP
    default: "jS M Y"
    options:
        "F jS \\a\\t g:ia": Date1
        "l jS \\of F g:i A": Date2
        "D, d M Y G:i:s": Date3
        "d-m-y G:i": Date4
        "jS M Y": Date5

Поле Datetime¶

Тип поля datetime используется для хранения и отображения даты и времени.

Пример:

1
2
3
4
5

header.date:
  type: datetime
  label: PLUGIN_ADMIN.DATE
  toggleable: true
  help: PLUGIN_ADMIN.DATE_HELP

Поле Editor¶

Тип поля editor используется для отображения редактора Codemirror.

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

frontmatter:
  classes: frontmatter
  type: editor
  label: PLUGIN_ADMIN.FRONTMATTER
  autofocus: true
  codemirror:
    mode: 'yaml'
    indentUnit: 4
    autofocus: true
    indentWithTabs: false
    lineNumbers: true
    styleActiveLine: true
    gutters: ['CodeMirror-lint-markers']
    lint: true

Поле Elements¶

Это поле только организационное: оно позволяет группировать элементы в именованную группу, которая показывается, только если выбранное значение элемента совпадает с группой.

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

header.elements-demo.type:
  type: elements
  label: 'Elements Demo'
  size: small
  default: gelato
  options:
    gelato: Gelato Flavors
    color: Color
    planets: Planets
  fields:
    gelato:
      type: element
      fields:
        .flavours:
          type: array
          default:
            pistacchio: Pistacchio
            vanilla: Vanilla
            chocolate: Chocolate
            stracciatella: Stracciatella
    color:
      type: element
      fields:
        .description:
          type: textarea
          rows: 10
          default: Color (American English) or colour (Commonwealth English) is the visual perceptual property corresponding in humans to the categories called blue, green, red, etc. Color derives from the spectrum of light (distribution of light power versus wavelength) interacting in the eye with the spectral sensitivities of the light receptors. Color categories and physical specifications of color are also associated with objects or materials based on their physical properties such as light absorption, reflection, or emission spectra. By defining a color space colors can be identified numerically by their coordinates.
    planets:
      type: element
      fields:
        .favorites:
          type: text
          placeholder: What are your favorite planets?
          markdown: true
          description: 'Find a list of planets from [Wikipedia](https://en.wikipedia.org/wiki/Planet)'

Поле Fieldset¶

fieldset группирует набор полей в раскрывающемся блоке.

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

header.fieldset:
  type: fieldset
  title: Your title
  help: Help text
  info: Info text
  text: Text inside fieldset and before other fields
  icon: comments       # Система иконок Fork Awesome (см. forkaweso.me).
  collapsed: true      # Начальное состояние fieldset (см. параметр collapsible)
  collapsible: true    # Можно ли разворачивать fieldset
  fields:
    header.fieldset.an_example_text:
      type: text
      label: text
    header.fieldset.an_example_textarea:
      type: textarea
      label: textarea

!Наборы полей тоже нужно сохранять во frontmatter с header., чтобы состояния их подполей корректно запоминались!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

header.fieldset:
  type: fieldset
  ... etc...
  fields:
    header.content.pagination:
      type: toggle
      toggleable: true
      label: "Activate Pagination ?"
      highlight: 1
      default: 0
      options:
        1: Yes
        0: No
      validate:
        type: bool

Иконка набора полей¶

В заголовке набора полей можно разместить иконку. Используется система иконок Fork Awesome.

Поле File¶

Пример:

1
2
3
4
5
6

custom_logo_login_screen:
  type: file
  label: Custom Logo Login Screen
  destination: 'plugins://admin/assets'
  accept:
    - image/*

1
2
3
4
5
6
7
8
9

custom_file:
  type: file
  label: A Label
  destination: 'theme://assets'
  multiple: true
  limit: 5
  filesize: 1
  accept:
    - image/*

Поле Filepicker¶

Тип поля filepicker можно использовать на страницах, в конфигурациях плагинов и тем (схемах). Обрабатывает выбор файла из расположения и сохранение его в заголовках страницы или конфигурации темы или плагина.

Пример:

1
2
3
4
5
6
7
8

picked_image:
  type: filepicker
  folder: 'theme://images/pages'
  label: Select a file
  preview_images: true
  accept:
    - .png
    - .jpg

1
2
3
4
5

header.a_file:
  type: filepicker
  folder: 'self@'
  preview_images: true
  label: Select a file

Поле Frontmatter¶

Тип поля frontmatter показывает обычный редактор кода YAML без панели форматирования. Любой введённый текст хранится дословно, как необработанная строка (переводы строк представляются escape-последовательностями) под собственным именем поля — он не разбирается и не объединяется с реальными ключами заголовка страницы.

1
2

show_title: true
title_h1: 'Heading H1'

1

frontmatter_field: "show_title: true\ntitle_h1: 'Heading H1'"

Пример:

1
2
3
4

header.notes:
  type: frontmatter
  label: Freeform Notes
  help: Anything typed here is stored as a single raw text block

Поле Honeypot¶

Тип поля honeypot создаёт скрытое поле, которое при заполнении возвращает ошибку. Это полезный способ не дать ботам заполнять и отправлять форму.

Пример:

1
2
3

fields:
    - name: honeypot
      type: honeypot

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

Поле honeypot — популярная альтернатива полям captcha.

Поле IconPicker¶

Тип поля iconpicker предоставляет визуальный выбор иконки Font Awesome. Выбранная иконка хранится как строка с именем её класса Font Awesome.

Поле доступно и в классической админке, и в Admin Next. Admin Next предоставляет дополнительные семейства иконок Font Awesome и выбор с поиском, а классическая админка использует набор иконок Font Awesome, поставляемый с плагином Admin.

Пример:

1
2
3

icon:
    type: iconpicker
    label: Choose an icon

Выбранную иконку затем можно использовать в шаблоне, например:

1
2

{% if page.header.icon %} <i class="{{ page.header.icon }}"></i>
{% endif %}

В Admin Next выбор предоставляет отдельные семейства Solid, Regular и Brands. Иконки можно искать по имени или связанным условиям поиска, и одновременно показывается до 200 подходящих иконок.

Например, выбор иконки Solid house сохраняет:

fa-house

Иконка Regular или Brands включает семейство в сохраняемое значение:

fa-regular fa-address-book
fa-brands fa-github

Это позволяет использовать выбранное значение напрямую как класс Font Awesome в теме сайта.

Формат¶

Классическая админка поддерживает атрибут format:

1
2
3

icon:
    type: iconpicker
    format: short

short сохраняет короткий формат класса иконки. Любое другое значение или отсутствие атрибута format использует длинный формат.

Выбор иконок основан на Font Awesome. Классическая админка загружает определения иконок из данных Font Awesome, поставляемых с плагином Admin, а Admin Next ведёт собственный каталог иконок и поддерживает семейства Solid, Regular и Brands.

Поле List¶

Тип поля list используется для создания коллекций полей. Поле принимает атрибут fields с подполями и показывает кнопку «Добавить элемент», чтобы пользователь мог добавлять элементы в коллекцию.

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

header.buttons:
  name: buttons
  type: list
  style: vertical
  label: Buttons
  fields:
    .text:
      type: text
      label: Text
    .url:
      type: text
      label: URL
    .primary:
      type: toggle
      label: Primary
      highlight: 1
      default: 1
      options:
          1: 'Yes'
          0: 'No'
      validate:
          type: bool

Этот пример создаёт такой интерфейс админки:

При сохранении страницы во frontmatter добавится такой YAML:

1
2
3
4
5
6
7
8
9

buttons:
    -
        text: 'Some text'
        url: 'https://getgrav.org'
        primary: false
    -
        text: 'Another text'
        url: 'https://another-url.com'
        primary: true

Он будет использоваться в Twig темы, чтобы красиво вывести список.

Ещё один пример определения этого поля — список Features, используемый модульной дочерней страницей Features в Antimatter. У каждой фичи есть иконка, заголовок и текст:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

header.features:
  name: features
  type: list
  label: Features

  fields:
    .icon:
      type: text
      label: Icon
    .header:
      type: text
      label: Header
    .text:
      type: text
      label: Text

Доступ к данным поля list и их вывод выполняются простым циклом for в Twig, как в примере ниже:

1
2
3
4
5

{% for feature in page.header.features %}
    {{ feature.icon }}
    {{ feature.header }}
    {{ feature.text }}
{% endfor %}

Поле Markdown¶

Тип поля markdown показывает редактор Markdown, используемый полем Content страницы: панель форматирования, переключатель предпросмотра и вставку изображений. Это тип поля, который system/blueprints/pages/default.yaml использует для content; его можно добавить в любом другом месте схемы, чтобы дать странице вторую область Markdown.

Пример:

1
2
3
4

header.summary:
  type: markdown
  label: Summary
  help: A short Markdown summary shown on listing pages

Значение хранится как необработанный Markdown, поэтому при выводе в шаблоне пропускайте его через фильтр markdown:

1

{{ page.header.summary|markdown }}

Поле Media¶

Тип поля media позволяет автору выбрать изображение или файл из трёх мест в одном элементе управления:

• Медиа страницы — файлы, прикреплённые к редактируемой странице;
• Медиа сайта — медиатека сайта (поток media://, обычно user/media) с просмотром по папкам;
• URL — адрес, введённый вручную.

Какие из них предлагать, задаётся через sources. Если включён только один источник, поле сразу показывает соответствующий выбор без вкладок.

Это охватывает возможности filepicker и добавляет медиатеку сайта и источник URL. filepicker не изменился и по-прежнему поддерживается, поэтому существующие схемы менять не нужно.

Пример — изображение hero, которое автор может взять откуда угодно:

1
2
3
4
5

header.hero:
  type: media
  label: Hero Image
  accept:
    - image/*

Пример — логотип, ограниченный одной папкой медиатеки:

1
2
3
4
5
6
7
8

header.logo:
  type: media
  label: Brand Logo
  sources:
    - site
  folder: 'media://logos'
  accept:
    - image/*

Пример — упорядоченная галерея из медиатеки или внешних URL:

1
2
3
4
5
6
7
8
9

header.gallery:
  type: media
  label: Gallery
  multiple: true
  sources:
    - site
    - url
  accept:
    - image/*

Что сохраняется¶

Значение всегда обычная строка или список строк, если установлен multiple. Источник, из которого оно получено, записывается в самом значении:

Значение медиа страницы намеренно представляет собой просто имя файла — именно это всегда сохранял filepicker и чего ожидает page.media[...], поэтому поле, переключённое с filepicker на media, продолжает читать существующие значения.

При multiple: true значение — список YAML в выбранном автором порядке:

1
2
3

gallery:
  - 'media://gallery-img-1.png'
  - 'media://Subfolder/Jeep.png'

Использование значения в Twig¶

Каждый источник требует немного разной обработки. Медиа страницы проходит через собственный объект Media страницы, поэтому работает обработка изображений Grav; путь media:// — это поток, который разрешает url(); внешний URL используется как есть.

1
2
3
4
5
6
7
8
9

{% set hero = page.header.hero %}

{% if hero starts with 'http' %}
    <img src="{{ hero }}" alt="">
{% elseif hero starts with 'media://' %}
    <img src="{{ url(hero) }}" alt="">
{% else %}
    {{ page.media[hero].cropZoom(1200, 600).html|raw }}
{% endif %}

Если поле ограничено одним источником, достаточно соответствующей ветки. Для поля sources: [site], например, это просто <img src="{{ url(page.header.logo) }}">.

Поле PageMediaSelect¶

Тип поля pagemediaselect позволяет пользователям выбрать медиа из уже загруженных медиа страницы через FTP или менеджер медиа страницы.

filepicker без folder уже по умолчанию использует медиа текущей страницы, поэтому эти два объявления эквивалентны:

1
2
3
4
5
6
7

header.img_link:
  label: Choose media
  type: pagemediaselect

header.img_link:
  label: Choose media
  type: filepicker

Поле Pages¶

Тип поля pages показывает список страниц сайта.

Пример

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

home.alias:
    type: pages
    size: medium
    classes: fancy
    label: PLUGIN_ADMIN.HOME_PAGE
    start_route: '/some_page'
    show_all: false
    show_modular: false
    show_root: false
    help: PLUGIN_ADMIN.HOME_PAGE_HELP

Если установить multiple в true, нужно добавить validate.type: array. Иначе массив выбранных страниц не сохранится корректно.

Поле Parents¶

Тип поля parents предоставляет выбор страницы для указания родительской страницы. Оно показывает иерархию страниц сайта и позволяет выбрать страницу в качестве родителя.

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

1
2
3

parent:
    type: parents
    label: Parent

В Admin Next (Admin2) поле parents использует тот же выбор страницы, что и поле Pages, но с другим поведением по умолчанию. Поддерживаются следующие свойства:

1
2
3
4
5

parent:
    type: parents
    show_root: true
    show_slug: true
    show_modular: false

show_root¶

Управляет тем, можно ли выбрать корень сайта (/) в качестве родителя.

В Admin Next для поля parents параметр show_root по умолчанию равен true. Установите false, чтобы запретить выбор корня.

1
2
3

parent:
    type: parents
    show_root: false

show_slug¶

Управляет тем, показывается ли slug страницы рядом с заголовком в списке выбора.

В Admin Next show_slug по умолчанию true.

1
2
3

parent:
    type: parents
    show_slug: false

Это влияет только на отображение страниц в списке выбора и не меняет сохраняемое значение поля.

show_modular¶

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

В Admin Next show_modular по умолчанию false.

1
2
3

parent:
    type: parents
    show_modular: true

Установите true, если модульные страницы должны включаться в список выбора страниц.

Поле Section¶

Тип поля Section используется, чтобы разделить страницу настроек на разделы.

Пример:

1
2
3
4
5
6
7
8

content:
    type: section
    title: PLUGIN_ADMIN.DEFAULTS
    underline: true

    fields:

        #..... подполя

Поле Selectize¶

Тип поля selectize показывает гибрид текстового поля и выпадающего списка. В основном полезен для тегов и других полей выбора элементов.

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

taxonomies:
    type: selectize
    selectize:
        options:
            - text: "test"
              value: "real value 1"
            - text: "test-2"
              value: "real value 2"
            - text: "test-3"
              value: "real value 3"
    size: large
    label: PLUGIN_ADMIN.TAXONOMY_TYPES
    classes: fancy
    help: PLUGIN_ADMIN.TAXONOMY_TYPES_HELP
    validate:
        type: commalist

Поле Taxonomy¶

Тип поля taxonomy — особый список, предварительно настроенный для выбора одного или нескольких значений таксономии.

Пример:

1
2
3
4
5
6

header.taxonomy:
  type: taxonomy
  label: PLUGIN_ADMIN.TAXONOMY
  multiple: true
  validate:
    type: array