Frontend Forms

The Form plugin gives you the ability to create virtually any type of frontend form. It is essentially a form construction kit, available for you to use in your own pages. Before going any further, don't forget to install the Form plugin with bin/gpm install form if it's not installed yet.

To get an understanding of how the Form plugin works, let's start by going over how to create a simple form.

Create a simple single form

To add a form to a page of your site, create a page, and set its Page File to "Form". You can do it via the Admin Panel, or via filesystem directly by naming the page form.md.

So, for example, user/pages/03.your-form/form.md.

The contents of this page will be:

 1---
 2title: A Page with an Example Form
 3form:
 4    name: contact-form
 5    fields:
 6        name:
 7          label: Name
 8          placeholder: Enter your name
 9          autofocus: on
10          autocomplete: on
11          type: text
12          validate:
13            required: true
14
15        email:
16          label: Email
17          placeholder: Enter your email address
18          type: email
19          validate:
20            required: true
21
22    buttons:
23        submit:
24          type: submit
25          value: Submit
26        reset:
27          type: reset
28          value: Reset
29
30    process:
31        email:
32          from: "{{ config.plugins.email.from }}"
33          to:
34            - "{{ config.plugins.email.to }}"
35            - "{{ form.value.email }}"
36          subject: "[Feedback] {{ form.value.name|e }}"
37          body: "{% include 'forms/data.html.twig' %}"
38        save:
39          fileprefix: feedback-
40          dateformat: Ymd-His-u
41          extension: txt
42          body: "{% include 'forms/data.txt.twig' %}"
43        message: Thank you for your feedback!
44        display: thankyou
45
46---
47
48# My Form
49
50Regular **markdown** content goes here...

This is enough to show a form in the page, below the page's content. It is a simple form with a name, email field, two buttons: one to submit the form and one to reset the fields. For more information on the available fields that are provided by the Form plugin, check out the next section.

What happens when you press the Submit button? It executes the process actions in series. To find out about other actions, check out the available options or create your own.

1. An email is sent to the email entered, with the subject [Feedback] [name entered]. The body of the email is defined in the forms/data.html.twig file of the theme in use.

2. A file is created in user/data to store the form input data. The template is defined in forms/data.txt.twig of the theme in use.

3. The thankyou subpage is shown, along with the passed message. The thankyou page must be a subpage of the page containing the form.

Multiple Forms

With the release of Form Plugin v2.0, you are now able to define multiple forms in a single page. The syntax is similar but each form is differentiated by the name of the form, in this case contact-form and newsletter-form:

 1forms:
 2    contact-form:
 3        fields:
 4            ...
 5        buttons:
 6            ...
 7        process:
 8            ...
 9
10    newsletter-form:
11        fields:
12            ...
13        buttons:
14            ...
15        process:
16            ...

You can even use this format for single forms, by just providing one form under forms::

 1forms:
 2    contact-form:
 3        fields:
 4            ...
 5        buttons:
 6            ...
 7        process:
 8            ...

Displaying Forms from Twig

The easiest way to include a form is to simply include a Twig file in the template that renders the page where the form is defined. For example:

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

This will use the Twig template provided by the Form plugin itself. In turn, it will render the form as you have defined in the page, and handle displaying a success message, or errors, when the form is submitted.

There is however a more powerful method of displaying forms that can take advantage of the new multi-forms support. With this method you actually pass a form: parameter to the Twig template specifying the form you wish to display:

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

Using this method, you can choose a specific name of a form to display. You can even provide the name of a form defined in other pages. As long as all your form names are unique throughout your site, Grav will find and render the correct form!

You can even display multiple forms in one page:

 1# Contact Form
 2{% include "forms/form.html.twig" with { form: forms('contact-form') } %}
 3
 4# Newsletter Signup
 5{% include "forms/form.html.twig" with { form: forms('newsletter-form') } %}

An alternative way to display a form is to reference the page route rather than the form name using an array, for example:

 1# Contact Form
 2{% include "forms/form.html.twig" with { form: forms( {route:'/forms/contact'} ) } %}

This will find the first form from the page with route /forms/contact

Displaying Forms in Page Content

You can also display a form from within your page content (for example default.md) directly without that page even having a form defined within it. Simply pass the name or route to the form.

 1---
 2title: Page with Forms
 3process:
 4  twig: true
 5cache_enable: false
 6---
 7
 8# Contact Form
 9{% include "forms/form.html.twig" with {form: forms('contact-form')} %}
10
11# Newsletter Signup
12{% include "forms/form.html.twig" with {form: forms( {route: '/newsletter-signup'} ) } %}

Modular Forms

With previous versions of the Form plugin, to get a form to display in a modular sub-page of your overall modular page, you had to define the form in the top-level modular page. This way the form would be processed and available to display in the modular sub-page.

In Form v2.0, you can now define the form directly in the modular sub-page just like any other form. However, if not found, the form plugin will look in the 'current page', i.e. the top-level modular page for a form, so it's fully backwards compatible with the 1.0 way of doing things.

You can also configure your Modular sub-page's Twig template to use a form from another page, like the examples above.

Here's an example that exists at form/modular/_form/form.md:

 1---
 2title: Modular Form
 3
 4form:
 5  action: '/form/modular'
 6  inline_errors: true
 7  fields:
 8    person.name:
 9      type: text
10      label: Name
11      validate:
12        required: true
13        
14  buttons:
15    submit:
16      type: submit
17      value: Submit
18      
19  process:
20    message: "Thank you from your submission <b>{{ form.value('person.name') }}</b>!"
21    reset: true
22    display: '/form/modular'  
23---
24
25## Modular Form