Фронтенд-формы⚓︎

Плагин Form дает вам возможность создавать практически любые типы веб-форм. По сути, это набор для создания форм, который вы можете использовать на своих страницах. Прежде чем идти дальше, не забудьте установить плагин Form с помощью bin/gpm install form, если он ещё не установлен .

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

Создание простой формы⚓︎

Чтобы добавить форму на страницу вашего сайта, создайте страницу и установите для её файла подкачки значение «Форма». Вы можете сделать это через панель админки или через файловую систему напрямую, указав страницу form.md.

Например, user/pages/03.your-form/form.md.

Содержимое этой страницы будет:

---
title: A Page with an Example Form
form:
  name: contact-form
  fields:
    name:
      label: Name
      placeholder: Enter your name
      autofocus: on
      autocomplete: on
      type: text
      validate:
        required: true

    email:
      label: Email
      placeholder: Enter your email address
      type: email
      validate:
        required: true

  buttons:
    submit:
      value: Submit
    reset:
      value: Reset

  process:
    email:
      from: '{{ config.plugins.email.from }}'
      to:
        - '{{ config.plugins.email.to }}'
        - '{{ form.value.email }}'
      subject: '[Отзыв] {{ form.value.name|e }}'
      body: "{% include 'forms/data.html.twig' %}"
    save:
      fileprefix: feedback-
      dateformat: Ymd-His-u
      extension: txt
      body: "{% include 'forms/data.txt.twig' %}"
    message: Спасибо за ваш отзыв!
    display: thankyou

---
# Моя форма

Здесь идет обычный **Markdown**...

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

Что происходит, когда вы нажимаете кнопку «Отправить»? Она последовательно выполняет действия process. Чтобы узнать о других действиях, проверьте доступные варианты или создайте собственные.

1. На указанный адрес электронной почты будет отправлено электронное письмо с темой «[Отзыв] [введённое имя]». Тело электронного письма определяется в файле forms/data.html.twig используемой темы.

2. В user/data создается файл для хранения входных данных формы. Шаблон определен в файле forms/data.txt.twig используемой темы.

3. Отображается подстраница «thankyou» вместе с переданным сообщением. Страница thankyou должна быть подстраницей страницы, содержащей форму.

Несколько форм⚓︎

С выпуском Form Plugin v2.0 теперь вы можете определять несколько форм на одной странице. Синтаксис похож, но каждая форма различается по имени формы, в данном случае contact-form и newsletter-form:

forms:
  contact-form:
    fields: ...
    buttons: ...
    process: ...

  newsletter-form:
    fields: ...
    buttons: ...
    process: ...

Вы даже можете использовать этот формат для отдельных форм, просто указав одну форму в разделе forms::

forms:
  contact-form:
    fields: ...
    buttons: ...
    process: ...

Отображение форм из Twig⚓︎

Самый простой способ включить форму - просто включить файл Twig в шаблон, который отображает страницу, на которой определена форма. Например:

{% include "forms/form.html.twig" %}

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

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

{% include "forms/form.html.twig" with { form: forms('contact-form') } %}

Используя этот метод, вы можете выбрать конкретное имя формы для отображения. Вы даже можете указать имя формы, определенной на других страницах. Пока все ваши имена форм уникальны на вашем сайте, Grav найдет и отобразит правильную форму!

Вы даже можете отображать несколько форм на одной странице:

# Контактная форма
{% include "forms/form.html.twig" with { form: forms('contact-form') } %}

# Подписка на новости
{% include "forms/form.html.twig" with { form: forms('newsletter-form') } %}

Альтернативный способ отображения формы - ссылаться на маршрут страницы, а не на имя формы, используя массив, например:

# Контактная форма
{% include "forms/form.html.twig" with { form: forms( {route:'/forms/contact'} ) } %}

Это найдет первую форму на странице с маршрутом /forms/contact.

Отображение форм в содержимом страницы⚓︎

Вы также можете отображать форму прямо из содержимого вашей страницы (например, default.md), даже если на этой странице не определена форма. Просто передайте в форму имя или маршрут.

---
title: Page with Forms
process:
  twig: true
cache_enable: false
---

# Контактная форма
{% include "forms/form.html.twig" with {form: forms('contact-form')} %}

# Подписка на новости
{% include "forms/form.html.twig" with {form: forms( {route: '/newsletter-signup'} ) } %}

Модульные формы⚓︎

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

В Form v2.0 теперь вы можете определять форму непосредственно на модульной подстранице, как и любую другую форму. Однако, если он не найден, плагин формы будет искать на «текущей странице», то есть на модульной странице верхнего уровня для формы, поэтому он полностью обратно совместим со способом работы 1.0.

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

Вот пример, который существует в form/modular/_form/form.md:

---
title: Модульная форма

form:
  action: '/form/modular'
  inline_errors: true
  fields:
    person.name:
      type: text
      label: Name
      validate:
        required: true

  buttons:
    submit:
      type: submit
      value: Submit

  process:
    message: "Thank you from your submission <b>{{ form.value('person.name') }}</b>!"
    reset: true
    display: '/form/modular'
---
## Модульная форма