Ссылка: указатель полей формы⚓︎

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

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

Этот список обеспечивает общую основу, поэтому нет необходимости повторять описание общего поля.

Чтобы добавить пользовательские атрибуты, вы можете использовать:

attributes:
  key: value

Чтобы добавить пользовательские значения data-*, вы можете использовать:

datasets:
  key: value

Указанные выше определения атрибутов и наборов данных приводят к следующему определению поля:

<input name="data[name]" value="" type="text" class="form-input " key="value" data-key="value">

Доступные поля⚓︎

Поле Basic-Captcha⚓︎

Добавлено в Forms 7.0.0 в качестве локальной альтернативы полю Google ReCaptcha. Это поле особенно удобно при работе со СПАМом в контактных формах, когда вы не хотите иметь дело с хлопотами или, возможно, ограничениями GPDR, которые приходят с предложением Google. В нем используются OCR-устойчивые шрифты для предотвращения атак, и его можно настроить с помощью кодов для копирования или простых математических вопросов.

тип поля basic-captcha полностью настраивается через конфигурацию forms, но поставляется с разумными значениями по умолчанию. Общая конфигурация Basic-Captcha задается в вашем глобальном файле конфигурации формы (обычно user/config/plugins/form.yaml). По умолчанию установлены следующие параметры:

basic_captcha:
  type: characters # options: [characters | math]
  chars:
    length: 6 # number of chars to output
    font: zxx-noise.ttf # options: [zxx-noise.ttf | zxx-camo.ttf | zxx-xed.ttf | zxx-sans.ttf]
    bg: '#cccccc' # 6-char hex color
    text: '#333333' # 6-char hex color
    size: 24 # font size in px
    start_x: 5 # start position in x direction in px
    start_y: 30 # start position in y direction in px
    box_width: 135 # box width in px
    box_height: 40 # box height in px
  math:
    min: 1 # smallest digit
    max: 12 # largest digit
    operators: ['+', '-', '*'] # operators that can be used in math

Пример:

basic-captcha:
  type: basic-captcha
  placeholder: скопируйте 6 символов
  label: Вы человек?

Для этого также требуется соответствующий элемент process:, чтобы обеспечить правильную проверку формы.

Это должна быть первая запись в разделе process: формы, чтобы гарантировать, что форма не будет обработана, если проверка каптчи не прошла.

Пример:

process:
  basic-captcha:
    message: Проверка на человечность не прошла, попробуйте ещё раз...

Поле Turnstile Captcha (Cloudflare)⚓︎

Начиная с версии Form v7.1.0, Grav добавляет поддержку нового поля Cloudflare Turnstile. Это поле — новый способ предотвращения СПАМа в формах, и это отличная альтернатива полю Google ReCaptcha и ограничениям GPDR, предлагаемым Google. Это поле особенно удобно при работе со СПАМом в контактных формах. Подробнее о Turnstile.

Преимущества по сравнению с Google ReCaptcha⚓︎

1. Соответствие требованиям GDPR и ориентация на защиту частной жизни пользователей
2. Чрезвычайно быстрая проверка вызовов
3. Очень простая реализация как в Cloudflare, так и в Grav, никаких сложных пользовательских интерфейсов или параметров для настройки.
4. Никаких причудливых обходных путей для асинхронной отправки форм (ajax), это просто работает!
5. Исключительный пользовательский опыт по сравнению с ReCaptcha, больше никаких подсчётов машин, светофоров и прочей ерунды
6. Построен на основе машинного обучения, со временем становится лучше и адаптируется к новым векторам атак.
7. Исчерпывающая аналитика эффективности задачи, см. скриншот

Интеграция⚓︎

Прежде чем интегрировать Grav Forms с Turnstile, вы должны сначала создать новый сайт Turnstile, к примеру, с помощью официальной инструкции "get started". Здесь вы также можете выбрать тип виджета, который вы хотите использовать, это может быть управляемый, неинтерактивный или невидимый. Важно отметить, что тип виджета можно изменить только в Cloudflare, вы не сможете настроить его через Grav. Однако, если вас не устраивает один из вариантов, вы сможете изменить его позже, если возникнет необходимость. Подробнее о различных типах виджетов.

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

После создания сайта вам будут предоставлены site_key и site_secret, которые нужно будет задать в файле конфигурации формы (обычно user/config/plugins/form.yaml). Вы можете игнорировать предложенный тег сценария, так как Grav позаботится об этом за вас.

По умолчанию установлены следующие параметры:

turnstile:
  theme: light
  site_key: <Your Turnstile Site Key>
  secret_key: <Your Turnstile Secret Key>

Наконец, вам также потребуется соответствующий элемент process: для обеспечения правильной проверки формы.

Это должна быть первая запись в разделе process: формы, чтобы гарантировать, что форма не будет обработана, если проверка captcha не прошла.

Пример⚓︎

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

form:
  name: contact
  fields:
    name:
      label: Имя
      type: text
      validate:
        required: true
    email:
      label: Имейл
      type: email
      validate:
        required: true
    message:
      label: Сообщение
      type: textarea
      validate:
        required: true
    captcha:
      type: turnstile
      theme: light
  buttons:
    submit:
      type: submit
      value: Отправить
  process:
    turnstile: true
    email:
      subject: '[Acme] {{ form.value.name|e }}'
      reply_to: '{{ form.value.name|e }} <{{ form.value.email }}>'
    message: Спасибо, что обратились к нам!
    reset: true
    display: '/'

Поле Google Captcha (ReCaptcha)⚓︎

Тип поля captcha используется для добавления элемента Google reCAPTCHA в вашу форму. В отличие от других элементов, его можно использовать в форме только один раз.

Начиная с версии 3.0, поле поддерживает 3 варианта reCAPTCHA. Общая конфигурация reCAPTCHA лучше всего задается в глобальном файле конфигурации формы (обычно user/config/plugins/form.yaml). По умолчанию установлены следующие параметры:

recaptcha:
  version: 2-checkbox
  theme: light
  site_key:
  secret_key:

Эти параметры должны быть установлены на основе следующего:

В определении формы атрибут name поля captcha должен быть g-recaptcha-response'. Причина в том, что Google reCAPTCHA хранит код подтверждения Captcha в поле с именемg-recaptcha-response`.

Пример:

g-recaptcha-response:
  type: captcha
  label: Капча

Вы также можете предоставить настраиваемое сообщение об ошибке recaptcha_not_validated, но если вы этого не сделаете, сообщение по умолчанию предоставляется подключаемым модулем формы. Если вы хотите установить специфичный для формы ключ recaptcha_site_key, а не устанавливать его глобально в конфигурации формы, вы также можете установить это.

g-recaptcha-response:
  type: captcha
  label: Капча
  recaptcha_site_key: ENTER_YOUR_CAPTCHA_PUBLIC_KEY
  recaptcha_not_validated: 'Капча не действительна!'

Для этого также требуется соответствующий элемент process:, чтобы обеспечить правильную проверку формы.

Это должна быть первая запись в разделе process: формы, чтобы гарантировать, что форма не будет обработана, если проверка каптчи не прошла.

Пример:

process:
  captcha: true

Проверка Captcha на стороне сервера⚓︎

Приведенный выше код проверит Captcha во внешнем интерфейсе и предотвратит отправку формы, если она неверна. Чтобы также проверить правильность ввода капчи на стороне сервера, добавьте действие процесса ввода капчи в свои формы:

process:
  captcha: true

Вы также можете указать необязательное message об успешном выполнении, но если вы этого не сделаете, при успешном выполнении не будет отображаться никакого конкретного сообщения. Если вы хотите установить специфичный для формы recaptcha_secret, а не устанавливать его глобально в конфигурации формы, вы также можете установить это.

process:
  captcha:
    recaptcha_secret: ENTER_YOUR_CAPTCHA_SECRET_KEY
    message: 'Successfully passed reCAPTCHA!'

См. пример контактной формы, чтобы увидеть его в действии.

Поле флажка⚓︎

Тип поля checkbox используется для добавления одного флажка в вашу форму.

Пример:

agree_to_terms:
  type: checkbox
  label: 'Согласитесь с положениями и условиями'
  validate:
    required: true

Поле флажков⚓︎

Тип поля checkboxes используется для добавления группы флажков в вашу форму.

Примеры:

pages.process:
  type: checkboxes
  label: PLUGIN_ADMIN.PROCESS
  help: PLUGIN_ADMIN.PROCESS_HELP
  default:
    markdown: true
    twig: true
  options:
    markdown: Markdown
    twig: Twig
  use: keys

my_field:
  type: checkboxes
  label: Несколько флажков с подсказкой по каждому варианту и отключенным option1
  default:
    - option1
    - option2
  options:
    option1: Вариант 1
    option2: Вариант 2
    help_options:
        option1: Подсказка для варианта 1
        option2: Подсказка для варианта 2
    disabled_options:
        - option1

Условное поле⚓︎

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

Примеры:

Если ваше условное выражение уже возвращает true или false, вы можете просто использовать этот упрощенный формат:

my_conditional:
  type: conditional
  condition: config.plugins.yourplugin.enabled
  fields: # The field(s) below will be displayed only if the plugin named yourplugin is enabled
    header.mytextfield:
      type: text
      label: Текстовое поле

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

my_conditional:
  type: conditional
  condition: "config.site.something == 'custom'"
  fields: # The field(s) below will be displayed only if the `site` configuration option `something` equals `custom`
    header.mytextfield:
      type: text
      label: Текстовое поле

Поле даты⚓︎

Тип поля date используется для добавления поля ввода HTML5 date.

Пример:

- type: date
  label: Введите дату
  validate.min: '2014-01-01'
  validate.max: '2018-12-31'

Поле отображения⚓︎

Тип поля display используется для отображения текста или инструкций внутри формы. Может принимать Markdown-контент.

Пример:

test:
  type: display
  size: large
  label: Instructions
  markdown: true
  content: "This is a test of **bold** and _italic_ in a text/display field\n\nanother paragraph...."

Поле электронной почты⚓︎

Тип поля email используется для представления текстового поля ввода, которое принимает электронную почту, используя элемент input типа email.

Пример:

header.email:
  type: email
  autofocus: true
  label: Email

Поле файла⚓︎

С типом поля file вы можете позволить пользователям загружать файлы через форму. Поле по умолчанию позволяет только один файл типа изображение и будет загружено на текущую страницу, где была объявлена ​​форма.

# Default settings
my_files:
  type: file
  multiple: false
  destination: 'self@'
  accept:
    - image/*

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

По умолчанию в админке поле типа file будет перезаписывать загруженный файл с тем же именем, что и более новый, содержащийся в той же папке, в которую вы хотите его загрузить, если только вы не установите для параметра avoid_overwriting значение true в определении поля.

Скрытое поле⚓︎

Тип поля hidden используется для добавления скрытого элемента в форму.

Example:

header.some_field:
  type: hidden
  default: my-value

Поле приманки⚓︎

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

Пример:

fields:
  honeypot:
    type: honeypot

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

Поле приманки - популярная альтернатива полям капчи.

Поле игнорирования⚓︎

Тип поля ignore можно использовать для удаления неиспользуемых полей при расширении из другого чертежа

Пример:

header.process:
  type: ignore
content:
  type: ignore

Числовое поле⚓︎

Тип поля number используется для представления поля ввода текста, которое принимает только числа, с использованием поля HTML5 number.

Пример:

header.count:
  type: number
  label: 'Сколько?'
  validate:
    min: 10
    max: 360
    step: 10

Поле пароля⚓︎

Тип поля password используется для представления поля ввода текста пароля.

Пример:

password:
  type: password
  label: Пароль

Поле Radio⚓︎

Тип поля radio используется для представления набора радиополей.

Пример:

my_choice:
  type: radio
  label: Выбор
  default: markdown
  options:
    markdown: Markdown
    twig: Twig

Поле диапазона⚓︎

Поле range используется для представления поля диапазона.

Пример:

header.choose_a_number_in_range:
  type: range
  label: Выберите число
  validate:
    min: 1
    max: 10

Поле Section⚓︎

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

Пример:

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

  fields:

    #..... subfields

Поле выбора⚓︎

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

Пример 1:

pages.order.by:
  type: select
  size: long
  classes: fancy
  label: 'Порядок по умолчанию'
  help: 'Страницы в списке будут отображаться в этом порядке, если он не переопределен'
  options:
    default: 'По умолчанию - на основе имени папки'
    folder: 'Папка - на основе имени папки без префикса'
    title: 'Заголовок - на основе поля Title в заголовке'
    date: 'Дата - на основе поля Date в заголовке'

Пример 2 - Отключение отдельных опций:

my_element:
  type: select
  size: long
  classes: fancy
  label: 'Мой элемент Select'
  help: 'Используйте ключ:значение disabled для отображения, с отключением определенной опции'
  options:
    option1:
      value: 'Вариант 1'
    option2:
      value: 'Вариант 2'
    option3:
      disabled: true
      value: 'Вариант 3'

Если вы установите для multiple значение true, вам нужно добавить

pages.order.by:
  validate:
    type: array

В противном случае массив выбранных значений не будет сохранен корректно.

Поле Select Optgroup⚓︎

Тип поля select_optgroup используется для представления поля выбора с группировками.

Пример:

header.newField:
  type: select_optgroup
  label: Test Optgroup Select Field
  options:
    - OptGroup1:
        - Option1
        - Option2
    - OptGroup2:
        - Option3
        - Option4

Промежуточное поле⚓︎

Тип поля spacer используется для добавления текста, заголовка или тега hr

Пример:

test:
  type: spacer
  title: A title
  text: Some text
  underline: true

Поля Tabs / Tab⚓︎

Типы полей tabs и tab используются для разделения содержащихся полей формы на вкладки.

Пример:

tabs:
  type: tabs
  active: 1

  fields:
    content:
      type: tab
      title: PLUGIN_ADMIN.CONTENT

      fields:

        # .... other subfields

    options:
      type: tab
      title: PLUGIN_ADMIN.OPTIONS

      fields:

        # .... other subfields

Поле телефона⚓︎

Тип поля tel используется для представления поля ввода текста, которое принимает число, используя элемент input типа tel.

Пример:

header.phone:
  type: tel
  label: 'Ваш номер телефона'

Текстовое поле⚓︎

Поле text используется для представления поля ввода текста.

Пример:

header.title:
  type: text
  autofocus: true
  label: PLUGIN_ADMIN.TITLE
  minlength: 10
  maxlength: 255

Поле Textarea⚓︎

Поле textarea используется для представления поля ввода текстового поля.

Пример:

header.content:
  type: textarea
  autofocus: true
  label: PLUGIN_ADMIN.CONTENT
  minlength: 10
  maxlength: 255

Поле переключателя⚓︎

Тип поля toggle - это тип ввода вкл/выкл с настраиваемыми метками.

Пример:

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

Поле URL-адреса⚓︎

Тип поля url используется для представления поля ввода текста, которое принимает URL-адрес, используя элемент input типа url.

Пример:

header.url:
  type: url
  label: 'Ваш сайт'

Недокументированные в настоящее время поля⚓︎