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:
- 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. Supports dynamic data, and since 1.7.1 form validation through a new action hook.
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 separate group of settings.
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 a 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: Enable to send HTML formatted emails. Leave disabled to send a plain text email.
Confirmation email (since 1.7.2)
Let the person who submitted a form know that you have received their email by automatically sending out a custom confirmation email whenever the form is submitted.
We highly recommend properly setting up SMTP to ensure the best possible email delivery from your website. There are plenty of free WordPress plugins available that let you configure this within a few minutes. A search for “WordPress SMTP” should bring up countless articles & plugins for it.
If the “From name” & “From email address” you have set under the “Confirmation Email” settings inside the Form element isn’t used, you have to check if any plugin and/or custom code is overwriting/forcing another name & email address.
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”, “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.
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 'error' 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 'error' 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 );In certain cases, you would like to redirect user to a page based on certain URL parameter values. In such scenario, you are not able to use on the Custom redirect URL field. This is because the form was submitted in AJAX and the current page URL param will not be sent along the AJAX call.
To solve this, you can first place the url parameter into a hidden field.
Then choose Custom action, and follow below code as an example
<?php
add_action( 'bricks/form/custom_action', 'redirect_to_my_key', 10, 1 );
function redirect_to_my_key( $form ) {
$form_fields = $form->get_fields();
$form_id = $form_fields['formId'];
// Check if the form id is the one you want
if( $form_id !== 'cyrozb' ) return;
// oeckxw is the hidden field Id where I placed the
$my_key = isset( $form_fields['form-field-oecdxz'] ) ? $form_fields['form-field-oecdxz'] : '';
if( $my_key ) {
// Now you get the hidden field value and redirect to the page you want, for example:
$redirect_to = get_site_url() . '/?key=' . $my_key;
// If the hidden field value is a URL, just redirect to it instead of following my code
// $redirect_to = $my_key;
$form->set_result(
[
'action' => 'my_custom_redirect', // This is the action name, you can set it to anything you want
'type' => 'redirect', // Must be set to 'redirect'
'redirectTo' => $redirect_to,
'redirectTimeout' => 0 // Need to delay ? Set a timeout in milliseconds
]
);
}
}Form validation
Bricks 1.7.1 provides a new filter named bricks/form/validate that allows you to validate every form submission and return error messages if your custom validation fails. The first $errors param is an array with each item being an error message. And the second $form param is the instance of the form that has been submitted.
The following code example validates the submitted email address for the form field ID 7e30aa.
If no user account with this email address exists on this site, the validation fails, an error message is displayed, and no email will be sent.
add_filter( 'bricks/form/validate', function( $errors, $form ) {
$form_settings = $form->get_settings();
$form_fields = $form->get_fields();
$form_id = $form_fields['formId'];
// Skip validation: Form ID is not 'kfbqso'
if ( $form_id !== 'kfbqso' ) {
// Early return the $errors array if it's not target form
return $errors;
}
// Get submitted field value of form field ID '7e30aa'
$email_address = $form->get_field_value( '7e30aa' );
// Error: Email from registered user (show error message, and don't send email)
if ( ! email_exists( $email_address ) ) {
// Add error message to the $errors message array
$errors[] = esc_html__( 'This email address is not in our system, sorry.', 'bricks' );
}
// Make sure to always return the $errors array
return $errors;
}, 10, 2 );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:
- $options – array of Flatpickr options
- $element – the Bricks element object
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.