Get Bricks

Form Element

October 10, 2022

The Bricks’ “Form” element is an out-of-the-box element to build and place forms on any page built with Bricks. The form element lets you build custom forms with the following form field types:

  • Email
  • Text
  • Textarea
  • Telephone
  • Number
  • URL
  • Checkbox
  • Select (dropdown)
  • Radio
  • Password
  • Datepicker
  • File upload
  • Hidden (since Bricks 1.3.5)

You can define actions triggered by form submissions like sending an email notification, redirecting to a certain page, communicating to SendGrid or Mailchimp servers, or user login/registration. If this is not enough, you can also develop your own actions.

The form element also integrates with Google reCaptcha V3 to protect your sites from fraudulent activities, spam, and abuse.

Since Bricks 1.3.5, the form fields settings support Dynamic Data.

How to use the Form element

Actions

The form actions run when the form is submitted. You may set one or multiple actions for your form. They will run in sequence according to the order defined, except for the “Redirect” action which will run after all other actions.

For each action, you’ll have a separated group of settings.

Bricks Form element - email action settings
Form element: email action settings

Email

The email form action sends one email on form submission. By default, it is configured to send the email to the site administrator email containing all the form fields content.

You may customize the form email action with the following settings:

  • Subject: The email subject
  • Send to email address: Fill in the email recipients. You may choose to send the email to the website administrator or to a custom email address (it accepts multiple email addresses, separated by comma)
  • From email address: The email address that shows as the sender
  • From name: The name that shows as the sender
  • Reply to email address: In case the recipient replies to the email, this email will be used instead of the “From email address”
  • Email content: In case you want to personalize the email content message. For the default message containing all the fields, leave this field empty.
  • Error message: The message that will be presented to the site’s user if the email fails for some reason.
  • HTML email: In case you want the email to formatted as HTML. Off will send a plain text email.
Form element: field ID

Email dynamic fields

In certain scenarios, it could be useful to get some of the submitted form fields’ content to populate the email action settings.

To use the submitted data in the settings you just need to grab the field ID (which you’ll find on the fields settings) and wrap it using the syntax: {{form_field_id}}

You may use the dynamic fields in the subject, custom email address, email content, from name, and from email settings.

Since Bricks 1.2 you may also use the {{referrer_url}} tag in the above fields to insert the URL of the page where the form was submitted.

Form element: registration action settings

User Login & Registration

The User Login and Registration form actions let you build custom login or registration forms without coding.

When selecting one of these actions you’ll need to map the form fields to be used as login & password (in the case of the Login form action) or to the email, password, username, first/last name (in the case of the Registration form action).

Redirect

This form action redirects the user from the form page to a different page on your site. You may set the redirection to the admin area or to a custom URL, and set the redirection to happen only after a specific period of time.

The Redirect form action is only triggered after all the other actions run successfully.

Custom

The custom action will allow you to hook into the action bricks/form/custom_action and run your custom code.

The action callback will receive the $form object which exposes the following methods to get the form settings, the form fields, and the form uploaded files (if needed):

Settings: $form->get_settings()

This method exposes an associative array with the form settings (fields and actions settings) similar to this:

Array
(
    [fields] => Array
        (
            [0] => Array
                (
                    [type] => text
                    [label] => Name
                    [placeholder] => Your Name
                    [id] => 15bc57
                )

            [1] => Array
                (
                    [type] => email
                    [label] => Email
                    [placeholder] => Your Email
                    [required] => 1
                    [id] => 3db633
                )

            [2] => Array
                (
                    [type] => textarea
                    [label] => Message
                    [placeholder] => Your Message
                    [required] => 1
                    [id] => f65f2c
                )
            ...

        )

    [submitButtonStyle] => primary
    [actions] => Array
        (
            [0] => email
            ...
        )

    [successMessage] => Message successfully sent. We will get back to you as soon as possible.
    [emailSubject] => Contact form request
    [emailTo] => admin_email
    [fromName] => bricks
    [emailErrorMessage] => Submission failed. Please reload the page and try to submit the form again.
    [htmlEmail] => 1
    [mailchimpPendingMessage] => Please check your email to confirm your subscription.
    [mailchimpErrorMessage] => Sorry, but we could not subscribe you.
    [sendgridErrorMessage] => Sorry, but we could not subscribe you.
    ...
)

Fields values: $form->get_fields()

This method exposes an associative array with the submitted values for each form field, together with the post Id and the form Id:

Array
(
    [form-field-15bc57] => John Doe
    [form-field-3db633] => john.doe@example.com
    [form-field-f65f2c] => Thank you for using Bricks!
    ...
    [postId] => 167
    [formId] => yrnkmt
    ...
    [referrer] => https://example.com/contact
)

Submitted files: $form->get_uploaded_files()

This method exposes an associative array with the properties of the submitted files, grouped by the form field Id:

Array
(
    [form-field-sajbjc] => Array
        (
            [0] => Array
                (
                    [file] => /.../public/wp-content/uploads/2022/03/my-uploaded-file.png
                    [url] => https://example.com/wp-content/uploads/2022/03/my-uploaded-file.png
                    [type] => image/png
                )

            [1] => Array
                (
                    [file] => /.../public/wp-content/uploads/2022/03/my-other-file.png
                    [url] => https://example.com/wp-content/uploads/2022/03/my-other-file.png
                    [type] => image/png
                )
            ...

        )

)

Example #1 Basic setup

<?php 
function my_form_custom_action( $form ) {  
  // $fields = $form->get_fields();
  // $formId = $fields['formId'];
  // $postId = $fields['postId'];
  // $settings = $form->get_settings();
  // $files = $form->get_uploaded_files();
  
  // Perform some logic here...

  // Set result in case it fails
  $form->set_result([
    'action' => 'my_custom_action',
    'type'    => 'success', //or danger or info
    'message' => esc_html__('Oh my custom action failed', 'bricks'),
  ]);
}
add_action( 'bricks/form/custom_action', 'my_form_custom_action', 10, 1 );

Example #2 Trigger a second email after the form is submitted.

With the current Bricks version, you can only set one email notification. With this code snippet, you may trigger a second one.

<?php 
function my_form_custom_action_sending_email( $form ) {
  $fields = $form->get_fields();
  // $formId = $fields['formId'];
  // $postId = $fields['postId'];
  $settings = $form->get_settings();
  // $files = $form->get_uploaded_files();


  $to = 'recipient@example.com'; // Replace this
  $from = 'sender@example.com'; // Replace this
  $subject = 'Your Subject'; // Replace this

  if ( ! empty( $settings['emailContent'] ) ) {
    $message = $form->render_data( $settings['emailContent'] );
    $message = isset( $settings['htmlEmail'] ) ? nl2br( $message ) : $message;
  } else {
    $email = new Bricks\Integrations\Form\Actions\Email('email');
    $message = $email->get_default_message( $settings, $fields );
  }


  $headers[] = 'From: Your Name <'.$from.'>';
  $headers[] = 'Reply-to: '. $from;
  if ( isset( $settings['htmlEmail'] ) ) {
    $headers[] = 'Content-Type: text/html; charset=UTF-8' . "\r\n";
  }

  $result = wp_mail( $to, $subject, $message, $headers );

  // $form->set_result([
  //  'action' => 'my_custom_action',
  //  'type'    => 'success', //or danger or info
  //  'message' => esc_html__('Oh my custom action failed', 'bricks'),
  // ]);
}
add_action( 'bricks/form/custom_action', 'my_form_custom_action_sending_email', 10, 1 );

Spam protection (Google reCaptcha V3)

The Bricks form element supports the latest Google reCaptcha V3 mechanism. To enable it, first, create a site key and a site secret key and then add both in your admin area under: Bricks > Settings > API Keys

After adding the keys, enable the reCaptcha setting when editing the Form element in the builder under the “Spam Protection” control group.

If you still get a lot of spam, you might need to tweak the score threshold level. The threshold is configured to 0.5 by default. Google reCaptcha V3 API returns a value between 0.0 and 1.0, where 0.0 is very likely a bot and 1.0 is very likely a human interaction. To increase the Bricks threshold, please use the following PHP snippet:

add_filter( 'bricks/form/recaptcha_score_threshold', function( $score ) {
    // Bricks default is 0.5
    $score = 0.8; 
    return $score;
}, 10, 1 );

Setting the threshold to 0.8 means Bricks will only accept form submissions with higher scores (more likely to be human interactions).

Customize the date picker field

Bricks (1.5+) uses the Flatpickr datetime picker javascript library which can be extended, localized or customized according to the available options.

To change the library initialization options, use the bricks/element/form/datepicker_options filter, like so:

add_filter( 'bricks/element/form/datepicker_options', function( $options, $element ) {
    $options['locale'] = [
        'firstDayOfWeek' => 1 // Set Monday as the first week day
    ];

    return $options;
}, 10, 2 );

The filter callback function accepts two arguments:

Localize the date picker strings

Flatpickr supports l10n for a variety of languages. You would need to load the language package by placing the following instructions into the Bricks Settings > Custom Code > Body (footer) scripts:

<script src="https://npmcdn.com/flatpickr/dist/l10n/XX.js"></script>

<script>
   window.flatpickr.localize(window.flatpickr.l10ns.XX)
</script>

Replace the XX with the language code you need (e.g. de for German, pt for Portuguese, …).

If you need to adjust the language on a specific form, you would need to load the language package as explained in the first line of the code above but then you may use the Bricks filter to load the language for a specific form element

add_filter( 'bricks/element/form/datepicker_options', function( $options, $element ) {
    if ( $element->id === 'abcdef' ) {
      // localize the form "abcdef" element 
      $options['locale'] = 'XX';
    }

    return $options;
}, 10, 2 );

Integrations

The Form element integrates with Mailchimp & Sendgrid. Allowing you to add new contacts to your email lists. Make sure you’ve added your Mailchimp/Sendgrid API keys as described below.

When editing your form element you have to select Mailchimp or Sendgrid under “Actions” so the form knows to add the submitted email address to your list.

Once you’ve selected the proper action a new “Mailchimp” or “Sendgrid” control group should appear. There you have to select the list you want to add this new contact to, and the “Email field” of your form that contains the email address.

Mailchimp

The Mailchimp form action allows you to automatically communicate your form data (email, first name, and last name) to a Mailchimp list and group.

To use the Mailchimp action you need to create a Mailchimp account and then get an API key.

Add the API key to the “Bricks > Settings > API Keys > Mailchimp API” key in order to be able to use this form action.

SendGrid

The SendGrid form action allows you to automatically communicate your form data (email, first name, and last name) to a SendGrid list.

To use the SendGrid action you need to create a SendGrid account and then get an API key.

Add the API key to the Bricks > Settings > API Keys > SendGrid API key in order to be able to use this form action.