Grav Blueprints and Forms: Custom Fields, Email, Leads

Standard Grav forms often do not cover business requirements: you need image upload fields, complex validation, CRM integration. Editors waste time on manual input, and managers receive incomplete data. We set up Blueprints and Grav forms including custom YAML fields, contact forms with email notifications via SMTP, multi-step forms, and flexible email templates. Over 50 projects on Grav — from simple contact forms to multi-step questionnaires with conditional fields.

For example, for a service company we set up a page with tabs: content, SEO, and settings. Previously editors filled a single text field; now they select custom blocks via filepicker and list. Result — filling time reduced threefold, and input errors dropped by 70%. Average form fill time decreased from 10 to 2 minutes.

What problems we solve

• Uncomfortable fields in admin. Editors waste time on manual entry of unnecessary fields. Blueprints remove everything extra: we show only needed tabs (content, SEO, settings), add filepicker for images, list for benefits, toggle for show/hide blocks.
• Lead loss. Without SMTP, emails go to spam or don't arrive. We connect a reliable mail server (Gmail, Yandex, Mailgun), configure DKIM/SPF, and guarantee 99.9% delivery.
• Single-step form is not enough. For complex orders, multi-step forms with validation at each step are needed. We implement via Form Wizard plugin or custom JS — data is saved even on reload.
• Complex field validation. Standard field types don't always meet business requirements. We add custom validators in PHP and client-side to reject incorrect data.

How to set up Blueprints for Grav pages?

One deep case: a service page with tabs "Content", "SEO", "Settings". Example file 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: Content
          fields:
            header.intro:
              type: textarea
              label: Introduction
              help: Brief description for preview
              size: large
              rows: 3
            header.hero_image:
              type: filepicker
              label: Main image
              preview_images: true
              folder: '@self'
              accept: ['image/jpeg', 'image/png', 'image/webp']
            header.features:
              type: list
              label: Features
              style: vertical
              fields:
                .icon:
                  type: text
                  label: CSS icon class
                  placeholder: 'icon-check'
                .text:
                  type: text
                  label: Feature text
        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: Settings
          fields:
            header.show_sidebar:
              type: toggle
              label: Show sidebar
              default: 1
              options:
                1: Yes
                0: No
            header.template:
              type: select
              label: Output template
              options:
                default: Standard
                wide: Wide
                fullscreen: Fullscreen
---

Blueprint field types and their purpose:

Contact form and email

Form described in frontmatter of contact.md:

---
title: Contacts
template: form
form:
  name: contact-form
  fields:
    name:
      label: Name
      type: text
      validate:
        required: true
        min: 2
    email:
      label: Email
      type: email
      validate:
        required: true
    phone:
      label: Phone
      type: tel
      placeholder: '+375 XX XXX-XX-XX'
    service:
      label: Service of interest
      type: select
      options:
        web: Website development
        app: Mobile app
        seo: SEO promotion
        other: Other
    message:
      label: Message
      type: textarea
      validate:
        required: true
        min: 20
      rows: 5
    honeypot:
      type: honeypot # bot protection
  buttons:
    submit:
      type: submit
      value: Send
      classes: btn btn-primary
  process:
    - email:
        from: "{{ form.value.email }}"
        to: [email protected]
        subject: "Site request: {{ 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: Thank you! We will contact you within 1 business day.
    - display: /thank-you
---
## Contact us
Leave a request and we will answer within a business day.

Email notification template:

{# 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 plugin configuration:

# 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: My Site
    to: [email protected]

Why correct email configuration is important?

Without SMTP, emails often land in spam. We configure SPF and DKIM records, use reliable mail services. Result — 99.9% delivery. Emails arrive with correct subject and readable template. Comparison of sending methods:

How to implement multi-step form in Grav?

For complex orders or surveys, we use multi-step forms. Example configuration:

form:
  name: multistep-order
  fields:
    step1:
      type: section
      title: Step 1. Contacts
      fields:
        name:
          type: text
          label: Name
        email:
          type: email
          label: Email
    step2:
      type: section
      title: Step 2. Order details
      fields:
        budget:
          type: select
          label: Budget
          options:
            small: up to $1000
            medium: $1000–5000
            large: over $5000
        details:
          type: textarea
          label: Task description

For step-by-step display, custom JS or the form-wizard plugin is required. Each step is a section with fields. Data is saved in session, after last step — submit. We validate at each step: email must be correct, phone in required format. Multi-step forms increase conversion by 40% compared to single-step.

Work process

1. Audit of current forms and Blueprints — identify bottlenecks, gather editor requirements.
2. Design field schema — tabs, types, validation.
3. Implement Blueprints — YAML files for pages and configuration.
4. Configure form and email — Form plugin, SMTP, email template.
5. Testing — check all scenarios, sending, validation.
6. Deploy and training — upload to production, conduct short training for editors.

What's included in the work

• YAML Blueprint schemas for all needed page types (documentation in code).
• Contact form with bot protection (honeypot + rate limit).
• Email template in Twig.
• SMTP server configuration.
• Instructions for field editing.
• Email delivery guarantee (fix if not working).

Timelines and cost

Basic setup — from 2 business days. Complex project (multi-step forms, custom fields, email templates) — 3–5 days. We provide an accurate estimate after briefing. Cost is calculated individually. Budget savings with a comprehensive order reach 25%. Our solutions pay off within the first month.

Common problems and their solution

• Honeypot is forgotten — form gets flooded with spam.
• Server-side validation is not checked (only JS) — attackers bypass.
• Email backup is not configured — on SMTP failure, leads are lost.

We avoid these at the design stage. Contact us — we will evaluate your project in 1 day. Order Grav Blueprints and form setup today. Get a consultation on integration with your CRM.

Without proper configuration, YAML Blueprint schemas may seem complex, but in fact they are a powerful tool for customizing Grav.