form

Renders an HTML form that sends out an email to the passed email address, and saves the message to the database, so the user can find it under ‘Messages’ in the site dashboard. Inside the 'form' tag, the 'submitted_form_fields' object will be available.

Arguments

The form tag accepts the following arguments:

for
The Plate object that represents the form. (Required)

to
The email address where the message is sent. (Required: if no register_form_confirmation 'to' is specified)
This can be:

A string containing one email address, or multiple comma-separated email addresses.
An array containing strings of individual email addresses.

subject

The subject that is used for the email sent to the email filled in at to. (Not required, default: 'Message sent from %{site}')

See https://plate.atlassian.net/wiki/spaces/DOCS/pages/30245050/register+form+confirmation+field for the subject of the confirmation email.

error_msg
The error message that is used in the ‘request’ object (alert attribute) when the form is invalid and doesn’t get sent. (Not required, default: ‘Something went wrong while sending the message.’)

success_msg
Same as error_msg, but for the message when the form does send (request attribute: notice). (Not required, default: ‘Thank you for your message. We will reply as soon as possible.’)

success_url
The url where the user is redirected to after a successful form submission. (Not required, by default the user gets redirected to the page where the submitted form was located)

enable_recaptcha(accepted values: true, skip_js)
Inserts an invisible Captcha (Google reCaptcha v3) inside the form, to prevent the form being used for spam. Set the value to 'true' for a regular implementation. If you need to handle the Captcha token generation yourself, set the value to 'skip_js'. Read the tutorial to learn how to do this.

Note that Plate does not add the credits for Google for the use of their ReCaptcha system. It is your own responsibility to add credits for Google on your page if you enable ReCaptcha.

Note2 You need to add {% include_plate_scripts "recaptcha_scripts" %} somewhere on the page that has the form on it. The form will not be submitted if the scripts are not included on the page! (go to docs about the include tag)

output_as
Only accepts 'json' as value. Returns a JSON hash that can be used as a payload when POSTing to the form_messages endpoint as a JSON request. See form | JSON endpoint for more info on how the request works.

Advanced inputs

The following inputs should only be used with proper understanding of the implications on security:

enable_cdn

If this input is enabled, (set to true), then Plate gets configured to not perform CSRF protection based on a timed secret. This should be used whenever a CDN or cached forms are used. Note: You must enable recaptcha for this form when enable_cdn is set to true.

Examples

Input:

{% form for: form, to: form.email, success_url: form.success_page_link, enable_recaptcha: true %}
  {% for field in form.field_lines %}
    {% include field %}
  {% endfor %}
  <div>
    <input type="submit" >
  </div>
{% endform %}

Output:

<form action="/form_messages" method="post" accept-charset="utf-8">
  <!-- Fields -->
  <div><input type="submit" value="Send"></div>
</form>

Every other attribute that you pass will be parsed as HTML attribute in the HTML form-tag.

Input:

{% form class: "contact-form" %}

Output:

<form action="/form_messages" method="post" accept-charset="utf-8" class="contact-form">
  <!-- Fields -->
</form>

`submitted_form_fields` object

Inside the 'form' block, you have access to the 'submitted_form_fields' object. This is a liquid object, representing all the (non-file) fields that were submitted. This allows you to keep your form fields filled when a validation error occurred.

For example, you can use this object when rendering a form field, as follows:

{% form ... %}
    {% for field in form.fields %}
        <input type="{{field.type}}" name="{{field.name | form_input_name}}" value="{{submitted_form_fields[field.name]}}"/>
        {% register_form_field field.name %}
    {% endfor %}
{% endform %}

By setting the value of the input field to the value in the 'submitted_form_fields' object, this input field will retain its value when the form is rendered again after a validation error on submitting the form.

JSON endpoint

Also accepts parameter output_as, which currently only accepts "json" as value. If this parameter is set, no html is returned, but everything needed for the payload to create a form message is returned in JSON format. This looks like this:

{
  "fields": [... meta info about all registered fields],
  "meta_hash": "... encrypted hash with metadata about the form, should be sent with json request"
}

With this you can call the following endpoint in order to create a form message through a JSON request:

POST /form_messages
Accept: application/json

{
  "form_message": {
    "content": {
      "content_field_a" => "value",
      "file_field_b" => {
        "base64": true,
        "filename": "my-image.png",
        "body": "base-64-string..."
      }
    },
    "meta_hash": "... meta hash from json"
  }
}

Recaptcha and JSON endpoints

It is possible to use Recaptcha when you send in the form request to the JSON endpoint. To do this you first determine the action name of your Recaptcha request. In a regular form, Plate handles this for you, but with a JSON request you have to do this yourself. It has to be a unique name for that page. For this example we’ll use test-1234 as the action name.

First make sure enable_recaptcha is enabled for your form and all necessary JS is loaded (See the enable_recaptcha section of this article). Then you have to fetch the Recaptcha token with JS. You do this by loading the recaptcha scripts, and fetching the token with a callback. When you have the token, you can send the request to the endpoint inside the callback

loadRecaptcha("test-1234", function(token) {
  axios({
    method: 'post',
    url: '/form_messages',
    data: {
      "form_message": {
        ... json from example
      },
      "recaptcha_action": "test-1234",
      "g-recaptcha-response": token
    }
  });
})