Grav Blueprints and Forms Setup

Grav Blueprints and Forms Setup

Blueprints in Grav — YAML description of form fields: for editing pages in admin and theme/plugin configuration. Form — plugin for creating contact and other forms directly in page frontmatter without PHP code.

Blueprints for Pages

Blueprint defines which fields editor sees when editing a page of given type. File located in user/blueprints/pages/ or user/themes/my-theme/blueprints/pages/.

# 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: Full Screen

Blueprint Field Types

Contact Form via Form Plugin

Form is described in page contact.md frontmatter:

---
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: '+1 XXX XXX-XX-XX'

    service:
      label: Interested Service
      type: select
      options:
        web: Web 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: Submit
      classes: btn btn-primary

  process:
    - email:
        from: "{{ form.value.email }}"
        to: [email protected]
        subject: "Request from site: {{ 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 respond during business hours.

Email Notification Template

{# user/themes/my-theme/templates/forms/email/contact.html.twig #}
<h2>New Request from Site</h2>
<table>
    <tr><td><strong>Name:</strong></td><td>{{ form.value.name }}</td></tr>
    <tr><td><strong>Email:</strong></td><td>{{ form.value.email }}</td></tr>
    <tr><td><strong>Phone:</strong></td><td>{{ form.value.phone }}</td></tr>
    <tr><td><strong>Service:</strong></td><td>{{ form.value.service }}</td></tr>
    <tr><td><strong>Message:</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]

Multi-Step Form

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: more than $5000
        details:
          type: textarea
          label: Task Description

For step-by-step display, custom JS or form-wizard plugin is needed.