Documentation

Usage

After installation plugin will register backend Form Builder menu position. From there you will be able to manage your forms.

There will be three sub-menus, Forms, Field types and Form logs.

Forms list all created forms.

Field types list all available field types.

Form logs list all forms submissions.

There will two examples forms included after installation. Simple contact form and default form, that will demonstrate all available fields.

Plugin will register renderForm component to use it on CMS page. After adding component to CMS page, you must inspect it (by clicking on it) and choose the form.

Plugin uses Ajax Framework to process form. Remember to add following code in layout:

{% framework extras %}
{% scripts %}

Please check if you have a following code in your layout head section.

{% styles %}

Example of placing form component on CMS page

/themes/demo/pages/contact.htm

url = "/contact"
layout = "default"

[renderForm contactForm]
formCode = "contact-form"
==
{% component 'contactForm' %}

Example of placing form component on CMS partial

/themes/demo/pages/contact.htm

url = "/contact"
layout = "default"

[renderForm contactForm]
formCode = "contact-form"
==
{% ajaxPartial "contact" %}

/themes/demo/partials/contact.htm

{% component 'contactForm' %}

Important note: For form handler to work you must use {% ajaxPartial %} instead of normal partial tag {% partial %}.

Forms

Spam Protection

If you need Spam protection for your forms I recommend to install following plugin: Spam Protection Plugin

After you install this plugin it will automatically protect all your forms. It will work out of the box.

Custom template

By default, plugin will auto generate template when Custom Template field is empty. When you need to replace default markup generated by plugin than you can write it here. You have access to special form_field() function that takes one parameter, the name of the field.

Example that will display two fields in one row:

<div class="row">
    <div class="col-6">{{ form_field('first_name') }}</div>
    <div class="col-6">{{ form_field('last_name') }}</div>
</div>

Floating labels

Simple form labels that float over your input fields. This requires to use Bootstrap 5.

Fields

Custom HTML markup for fields

You can change HTML markup for each field by going to Form Builder -> Field types and updating the field type. Recommended approach is to duplicate field type and then modify it as you wish.

Custom field types

You can create custom field types by going to Form Builder -> Field types and clicking New field type button.

For example if you want to create Email field type just duplicate the markup from Text field type and change the type of the input from text to email.

Now after saving this field it will be possible to use it in your form.

In markup section you can use Twig and following variables:

Available field types

Text

Renders a single line text box.

E-mail

Renders e-mail address field.

Phone number

Renders phone number field.

URL

Renders URL field.

Numeric

Renders numeric field.

Datetime

Renders datetime field.

Date

Renders date field.

Time

Renders time field.

Color Picker

Renders a color picker.

Textarea

Renders a multiline text box.

Dropdown

Renders a dropdown with specified options.

Checkbox

Renders a single checkbox.

Checkbox List

Renders a list of checkboxes.

Radio List

Renders a list of radio options, where only one item can be selected at a time.

reCaptcha

Renders google reCaptcha box for SPAM protection.

Please visit reCaptcha site to obtain credentials.

Next go to Settings -> Form Builder -> Google reCaptcha and fill your site key and secret.

Important note: This field must have g-recaptcha-response as field name and required|recaptcha in validation section to work properly.

Files upload

Renders a file input.

Filter fields selected by a user

To filter allowed file extensions or file types you can add custom attribute.

For example to only allow selecting files with extension .pdf or .doc.

accept=".pdf,.doc"

For example to only allow selecting images:

accept="image/*"

Validation

To make file input required just add required in validation section.

To restrict max file size to 512 kb just add max:512 in validation section.

To restrict file mime type to pdfs just add mimes:pdf in validation section.

To restrict file to images just add image in validation section.

For more available validation rules see October documentation.

Multiple files

By default file upload field only allow to upload a single file. To enable multiple file uploads in Upload options tab check Allow multiple files checkbox.

When validating multiple files to work correctly you must check Nested array based form input checkbox in validation section. This will apply validation for each uploaded file. Do not check this checkbox when using required rule.

Display mode

Display mode is just to inform backend area how to display uploaded files in form log entry. If you only allow to upload images then select image mode.

Country select

Renders a dropdown with country options.

Important note: You must install Location Plugin to use this field.

State select

Renders a dropdown with state options. This field depends on country select.

Important note: You must install Location Plugin to use this field.

Section

Renders a section heading and subheading. Useful for grouping fields.

Submit

Renders form submit button.

Form Logs

Form Builder plugin have built in simple logging information about sent form. Form log record will contain filled form data by user and corresponding file attachments.

Events

Plugin will fire formBuilder.overrideForm event which allow to change form properties before rendering the form markup.

Event::listen('formBuilder.overrideForm', function ($form) {
    // example code
    $form->css_class = 'form-horizontal';
});

Plugin will fire formBuilder.overrideField event which allow to change field properties before rendering the form markup.

Event::listen('formBuilder.extendFormData', function ($field, $form) {
    // example code
    if ($field->name === 'currency') {
        $field->default = 'USD';
    }
});

Plugin will fire formBuilder.extendFormData event which allow to change submitted form data.

Event::listen('formBuilder.extendFormData', function ($data) {
    // example code
    $data['foo'] = 'bar';

    return $data; // this line is required
});

Plugin will fire formBuilder.beforeSendMessage event before sending email. You can use this to extend Form Builder default functionality.

In your extension plugin boot method listen for this event:

Event::listen('formBuilder.beforeSendMessage', function ($form, $data) {
    // example code
    $form->from_email = 'john.doe@exampl.com';
    $form->from_name = 'John Doe';
});

You will have access to form object and array with posted data.

If you return false from this event then this will stop default behavior of sending email message.

Upgrade guide

Upgrading To 1.1.0

From version 1.1.0 plugin requires October build 300 and above.

Upgrading To 1.1.4

Added wrapper_class to field properties. Update fields type manually if you want to use this.

Upgrading To 1.2.7

Plugin will register Contact Form Template and Default Form Template. If you would like to use new mail layout you need to create it manually from the source /plugins/renatio/formbuilder/updates/mail/layouts/formbuilder/. Layout code should be specified as form_builder. Assign newly created layout to the templates by updating them manually.

Upgrading To 2.0.1

Plugin requires OctoberCMS version 2.x with Laravel 6.x and PHP >=7.3.

Drop support for OctoberCMS version 1.x.

If you upgrade from version 1.5.0, then you should reinstall plugin or apply patch with following command:

php artisan formbuilder:patch 2.0

Upgrading To 3.0.0

Plugin requires October CMS version 3.0 or higher, Laravel 9.0 or higher and PHP >=8.0.

Drop support for October CMS version 2.x.

Upgrading To 3.1.0

Major refactor of the code to use PHP 8, Laravel 9 and October CMS 3.1 features.

Please review documentation for more information about new features.

List of changes:

• Default support for Bootstrap 5
• Rewrite of field types to use Bootstrap 5
• Floating labels (only available when using Bootstrap 5)
• Custom template for the form
• Full support for RainLab Translate 2.0 and Multisite
• Rework form validation to use AjaxFramework extra features
• Multiple forms on the same page
• Improve error handling
• Improve form logs
• Granular permissions (please review them after upgrade)
• Import/Export forms
• Import/Export field types
• Export form logs
• New field types: email, phone, url, numeric, datetime, date, time, color picker
• Restore all field types to default markup
• New event formBuilder.extendFormData to allow change of submitted form data
• Spam Protection plugin support

Upgrading From 3.1.3 To 4.0.0

Before making the update please check if you are currently on 3.1.3 version of the plugin. If no, then make previous upgrades first.

Also before upgrading and running migrations please make the database backup.

This version removes responsiv/uploader-plugin support with native October ajax file upload.

The migration will add new upload field type and remove old ones. The new field type will be assigned to all old upload fields.

Please check your forms after upgrading.

For more details about new upload field type please read documentation.