Reference: Form Options

Name

There are no required options for forms. However as outlined in the Frontend Forms overview, it is highly recommend to at least have a form name:

 1form:
 2    name: my-form

This must be unique for your Grav site. This is because the form's name serves as a unique identifier for this form through the system. A form can be referenced by this name from any other page.

Method

This option allows you to control if the form should be submitted via POST or GET. The default is POST. Also note, if you have a file field in your form, the method will also get enctype="multipart/form-data" appended:

 1form:
 2    method: GET

Action

The action by default is going to be the route as the current page. This makes sense most of the time because the form needs to be processed by the same page that houses the form. There are times when you want to override the action however to either specify a different file extension (.json perhaps) or even target a specific page anchor:

 1form:
 2    action: '/contact-us#contact-form'

You can even process the form on another page if that page is where you want to handle the results. This can also be used as a technique to alter the template of the response from the one used in the original form:

 1form:
 2    action: /contact-us/ajax-process

Where you have a page file called form-messages.html.twig that returns just the message data. Alternatively you can use the approach below...

Template

Usually the page's Twig template that displays the form is perfectly capable of handling any success/failure messages or in-line validation responses. However sometimes it's useful to send the form response back using a different Twig template. A good example of this is when you want to process your form via Ajax. You probably only want the HTML for the success/failure messages to be returned by the template, so these can be injected back into the page by JavaScript:

 1form:
 2    template: form-messages

ID

The ability to set a form-level CSS id field. If not provided the form's name is used.

 1form:
 2    id: my-form-id

Classes

You can also set explicit classes on the form. There are no default values here.

 1form:
 2    classes: 'form-style form-surround'

Attributes

Adding custom attributes to the form element. Using the example below, replace key with your attribute and value with the attribute's value.

 1form:
 2    attributes:
 3        key: value

Inline Errors

Setting Inline Errors in the form's markdown file or definition enables the display of in-line errors, an important troubleshooting tool.

 1form:
 2    inline_errors: true

Client-side Validation

Turning client-side validation off will enable you to see in-line errors and detailed server-side validation that go beyond the HTML5 client-side validation. You can disable client-side validation through form.yaml or in the form definition.

 1form:
 2    client_side_validation: false

XSS Checks

By default, Grav 1.7 and later versions enable various XSS checks in all the forms. The default settings can be found from Security Configuration. However you can override these settings per form or per field, for example you can disable XSS checks in the whole form by:

 1form:
 2    xss_check: false

You can enable or disable individual rules by overriding the main configuration. The rules which are not overridden will fall back to use security configuration:

 1form:
 2    xss_check:
 3        enabled_rules:
 4            on_events: false
 5            invalid_protocols: false
 6            moz_binding: false
 7            html_inline_styles: false
 8            dangerous_tags: false

Even better, you can also allow specific protocols and tags:

 1form:
 2    xss_check:
 3        safe_protocols:
 4            - javascript
 5        safe_tags:
 6            - iframe

Keep Alive

You can ensure your forms do not fail to submit when your session expires, by enabling the keep_alive option on the form. By enabling this, an AJAX request will be made to Grav before your session expires to keep it 'fresh':

 1form:
 2    keep_alive: true

Fieldsets

You can set up <fieldset></fieldset> tags for the fields in your form using the fieldset: designation in the form.

 1form:
 2    name: Example Form
 3    fields:
 4        example:
 5            type: fieldset
 6            id: my-fieldset
 7            legend: 'Test Fieldset'
 8            fields:
 9                first_field: { type: text, label: 'First Field' }
10                second_field: { type: text, label: 'Second Field' }

The above form outputs as follows:

 1<form action="/grav/example/forms" class="" id="my-example-form" method="post" name="Example Form">
 2  <fieldset id="my-fieldset">
 3    <legend>Test Fieldset</legend>
 4    <div class="form-group">
 5      <div class="form-label-wrapper">
 6        <label class="form-label">First Field</label>
 7      </div>
 8      <div class="form-data" data-grav-default="null" data-grav-disabled="true" data-grav-field="text">
 9        <div class="form-input-wrapper">
10          <input class="form-input" name="data[first_field]" type="text" value="">
11        </div>
12      </div>
13    </div>
14    <div class="form-group">
15      <div class="form-label-wrapper">
16        <label class="form-label">Second Field</label>
17      </div>
18      <div class="form-data" data-grav-default="null" data-grav-disabled="true" data-grav-field="text">
19        <div class="form-input-wrapper">
20          <input class="form-input" name="data[second_field]" type="text" value="">
21        </div>
22      </div>
23    </div>
24  </fieldset>
25</form>

In the above example, the fields appear within the my-fieldset fieldset. You'll also notice that the <legend></legend> tags are supported through the legend: option.