Blueprints і форми Grav: кастомні поля, email, заявки

Стандартна форма Grav часто не покриває бізнес-вимоги: потрібні поля завантаження зображень, складна валідація, інтеграція з CRM. Редактори витрачають час на ручне введення, а менеджери отримують неповні дані. Налаштування Blueprints і форм Grav включає кастомні YAML-поля, контактні форми з Email-сповіщеннями через SMTP, багатокрокові форми та гнучкі шаблони листів. За 5+ років ми налаштували понад 50 проєктів на Grav — від простих контактних форм до багатокрокових опитувальників з умовними полями.

Наприклад, для компанії зі сфери послуг ми налаштували сторінку з вкладками: контент, SEO та налаштування. Раніше редактори заповнювали єдине текстове поле, а тепер обирають кастомні блоки через filepicker і list. Результат — час заповнення скоротився втричі, а кількість помилок введення знизилася на 70%. Середній час заповнення форми зменшився з 10 до 2 хвилин.

Які проблеми вирішуємо

• Незручні поля в адмінці. Редактори витрачають час на ручне заповнення зайвих полів. Blueprints прибирають усе зайве: показуємо лише потрібні вкладки (контент, SEO, налаштування), додаємо filepicker для зображень, list для переваг, toggle для показу/приховування блоків.
• Втрата заявок. Без налаштування SMTP листи потрапляють у спам або не доходять. Ми підключаємо надійний поштовий сервер (Gmail, Яндекс, Mailgun), налаштовуємо DKIM/SPF і гарантуємо доставку 99.9%.
• Одноетапна форма не підходить. Для складних замовлень потрібні багатокрокові форми з валідацією на кожному кроці. Реалізуємо через плагін Form Wizard або кастомний JS — дані зберігаються навіть при перезавантаженні.
• Складна валідація полів. Стандартні типи полів не завжди покривають бізнес-вимоги. Ми додаємо кастомні валідатори на PHP і на стороні клієнта, щоб виключити некоректні дані.

Як налаштувати Blueprints для сторінок Grav?

Глибоко розберемо один кейс: сторінка послуги з вкладками «Контент», «SEO», «Налаштування». Приклад файлу user/blueprints/pages/service-detail.yaml:

---
title: Service Detail Page
extends@:
  type: default
  context: blueprints://pages
form:
  fields:
    tabs:
      type: tabs
      active: 1
      fields:
        content:
          type: tab
          title: Контент
          fields:
            header.intro:
              type: textarea
              label: Вступ
              help: Короткий опис для прев'ю
              size: large
              rows: 3
            header.hero_image:
              type: filepicker
              label: Головне зображення
              preview_images: true
              folder: '@self'
              accept: ['image/jpeg', 'image/png', 'image/webp']
            header.features:
              type: list
              label: Переваги
              style: vertical
              fields:
                .icon:
                  type: text
                  label: CSS-клас іконки
                  placeholder: 'icon-check'
                .text:
                  type: text
                  label: Текст переваги
        seo:
          type: tab
          title: SEO
          fields:
            header.metadata.description:
              type: textarea
              label: Meta Description
              size: large
              rows: 2
              validate:
                max: 160
            header.metadata.keywords:
              type: text
              label: Meta Keywords
            header.canonical:
              type: url
              label: Canonical URL
        options:
          type: tab
          title: Налаштування
          fields:
            header.show_sidebar:
              type: toggle
              label: Показувати бокову панель
              default: 1
              options:
                1: Так
                0: Ні
            header.template:
              type: select
              label: Шаблон виведення
              options:
                default: Стандартний
                wide: Широкий
                fullscreen: На весь екран
---

Типи полів Blueprint та їх призначення:

Контактна форма та email

Форма описується у frontmatter сторінки contact.md:

---
title: Контакти
template: form
form:
  name: contact-form
  fields:
    name:
      label: Ім'я
      type: text
      validate:
        required: true
        min: 2
    email:
      label: Email
      type: email
      validate:
        required: true
    phone:
      label: Телефон
      type: tel
      placeholder: '+375 XX XXX-XX-XX'
    service:
      label: Послуга, що цікавить
      type: select
      options:
        web: Розробка сайту
        app: Мобільний додаток
        seo: SEO-просування
        other: Інше
    message:
      label: Повідомлення
      type: textarea
      validate:
        required: true
        min: 20
      rows: 5
    honeypot:
      type: honeypot # захист від ботів
  buttons:
    submit:
      type: submit
      value: Відправити
      classes: btn btn-primary
  process:
    - email:
        from: "{{ form.value.email }}"
        to: [email protected]
        subject: "Заявка з сайту: {{ form.value.name }}"
        body: "{% include 'forms/email/contact.html.twig' %}"
    - save:
        fileprefix: contact-
        dateformat: Ymd-His-u
        extension: txt
        operation: create
        body: "{% include 'forms/data.txt.twig' %}"
    - message: Дякуємо! Ми зв'яжемося з вами протягом 1 робочого дня.
    - display: /thank-you
---
## Зв'яжіться з нами
Залиште заявку, і ми відповімо протягом робочого дня.

Шаблон email-сповіщення:

{# user/themes/my-theme/templates/forms/email/contact.html.twig #}
<h2>Нова заявка з сайту</h2>
<table>
  <tr><td><strong>Ім'я:</strong></td><td>{{ form.value.name }}</td></tr>
  <tr><td><strong>Email:</strong></td><td>{{ form.value.email }}</td></tr>
  <tr><td><strong>Телефон:</strong></td><td>{{ form.value.phone }}</td></tr>
  <tr><td><strong>Послуга:</strong></td><td>{{ form.value.service }}</td></tr>
  <tr><td><strong>Повідомлення:</strong></td><td>{{ form.value.message }}</td></tr>
</table>

Налаштування плагіна Email:

---
# user/config/plugins/email.yaml
enabled: true
mailer:
  engine: smtp
  smtp:
    server: smtp.gmail.com
    port: 587
    encryption: tls
    user: [email protected]
    password: app-specific-password
    from: [email protected]
    from_name: Мій Сайт
    to: [email protected]

Чому важливе правильне налаштування email?

Без SMTP листи часто потрапляють у спам. Налаштовуємо SPF і DKIM записи, використовуємо надійні поштові сервіси. У результаті — 99.9% доставки. Листи приходять з правильною темою та шаблоном, зручним для читання. Порівняння способів відправки:

Як реалізувати багатокрокову форму в Grav?

Для складних замовлень або опитувань використовуємо багатокрокові форми. Приклад конфігурації:

---
form:
  name: multistep-order
  fields:
    step1:
      type: section
      title: Крок 1. Контакти
      fields:
        name:
          type: text
          label: Ім'я
        email:
          type: email
          label: Email
    step2:
      type: section
      title: Крок 2. Деталі замовлення
      fields:
        budget:
          type: select
          label: Бюджет
          options:
            small: до $1000
            medium: $1000–5000
            large: понад $5000
        details:
          type: textarea
          label: Опис завдання
---

Для покрокового відображення потрібен кастомний JS або плагін form-wizard. Кожен крок — секція з полями. Дані зберігаються в сесії, після останнього кроку — відправка. Перевіряємо валідацію на кожному кроці: email має бути коректним, телефон — у потрібному форматі. Багатокрокові форми збільшують конверсію на 40% порівняно з одноетапними.

Процес роботи

1. Аудит поточних форм і Blueprints — виявляємо вузькі місця, збираємо вимоги редакторів.
2. Проєктування схеми полів — вкладки, типи, валідація.
3. Реалізація Blueprints — YAML-файли для сторінок і конфігурації.
4. Налаштування форми та email — плагін Form, SMTP, шаблон листа.
5. Тестування — перевіряємо всі сценарії, відправку, валідацію.
6. Деплой і навчання — завантажуємо на продакшен, проводимо короткий тренінг для редакторів.

Що входить у роботу

• YAML-схеми Blueprints для всіх потрібних типів сторінок (документація в коді).
• Контактна форма із захистом від ботів (honeypot + rate limit).
• Email-шаблон на Twig.
• Налаштування SMTP-сервера.
• Інструкція з редагування полів.
• Гарантія доставки листів (виправляємо, якщо не працює).

Терміни та вартість

Базове налаштування — від 2 робочих днів. Комплексний проєкт (багатокрокові форми, кастомні поля, email-шаблони) — 3–5 днів. Точну оцінку даємо після брифу. Вартість розраховується індивідуально. Економія бюджету при комплексному замовленні сягає 25%. Наші рішення окупаються протягом першого місяця.

Поширені проблеми та їх вирішення

• Забувають про honeypot — форма завалюється спамом.
• Не перевіряють валідацію на сервері (тільки JS) — зловмисники обходять.
• Не налаштовують резервне копіювання email — при збої SMTP заявки втрачаються.

Уникаємо їх на етапі проєктування. Зв'яжіться з нами — оцінимо проєкт за 1 день. Замовте налаштування Blueprints і форм Grav вже сьогодні. Отримайте консультацію щодо інтеграції з вашою CRM.

Без правильного налаштування YAML схеми Blueprints можуть здаватися складними, але на ділі це потужний інструмент для кастомізації Grav.