48

Product support

Get help in the plugin support forum.

Categories

Custom Forms

Whether it's a contact form, newsletter subscription form, or a generic form, this plugin is built for just that.

What it does

It's a multi-form plugin, meaning you can supply a single rule for your preference in styling, actions, privacy, anti-spam, emailing, etc, which covers all forms on your website. Need one form to be customised differently? No problem, the forms can have custom settings which supersede the site wide settings, with fields having some custom settings which supersede its form's settings.

It includes features such as:

  • Google ReCAPTCHA
  • IP throttling
  • Form Builder
  • Events (about 26 of them) allowing you to add your own logic and callbacks
  • Validation for each field, with just a dash of intelligence
  • Custom styling of different elements
  • Caching of the form for performance improvements
  • Automatic replies to the author of the form submission (requires setting up, per form)
  • Automatic notifications to admins
  • Queueing vs immediate sending of emails
  • On Success: Hide the form, reset the form, or redirect to a URL
  • Custom HTML attributes for form fields
  • More

Custom Forms

October Plugin for self created and styled forms, with a variety of customisations, emailing, storing submissions, etc

Usage (October CMS)

Simple. Firstly you will need a form. Installing this plugin will automatically generate a basic contact form. This can be deleted or used as a reference - up to you.

Settings

There are 3 main levels of settings: Site Wide Settings > Form Settings > Field Settings.

Form and Field settings that override Site Wide and Form settings (respectively) are accompanied by an "override" checkbox, which when checked allows the respective setting be override the 'more global' version of the setting.

Certain settings are only available at global level (Google recaptcha keys, queue emails, etc), while some are only available at field level.

Creating a form

After configuring the global settings, head to the Custom Forms navigation item in the backend menu and click "Create".

Here you can enter the title of the form, and a code for it (which is used in layouts/the component for referencing the correct form).

Please Note Deferred binding on fields for forms is not configured just yet, meaning you will need to save the form before adding any fields. Feel free to open a PR for the fix to this.

After saving the form, you can now add fields by clicking the "Create fields" button

Fairly straight forward process, each field has a comment explaining the fields' purpose a little.

Validation can be configured - accepts a string of rules, | (pipe) delimited, as per normal Laravel / October Validation Rules. Only supports a single message per field at the moment.

Adding a form to a layout

As you would with component, open the layout and insert the respective component. This component comes with one required property:

  • Use Form (formCode): This references a Form via the code field. Make sure it's set correctly.
Events

Currently there are about 26 events which may fire (depending on your configurations, of course). If you feel like there's an important event missing, please open an issue or PR.

use ABWebDevelopers\Forms\Components\CustomForm;
use ABWebDevelopers\Forms\Classes\HtmlGenerator;
use ABWebDevelopers\Forms\Models\Submission;
use Validator;

// Runs at the beginning of "onRun" (when loading a page with a CustomForm)
Event::listen('abweb.forms.beforeRun', function (CustomForm $customForm) {
    // Do something...
    Log::debug('Loaded form: ' . $customForm->form->name);
});

// Runs at the end of "onRun" (when loading a page with a CustomForm)
Event::listen('abweb.forms.afterRun', function (CustomForm $customForm) {
    // Do something...
});

// Runs at the beginning of "onFormSubmit" (when submitting a CustomForm)
Event::listen('abweb.forms.beforeFormSubmit', function (CustomForm $customForm) {
    // Do something...
    Log::debug('User submitted form: ' . $customForm->form->name);
});

// Runs before validating the payload of a form. Can adjust data, rules, and messages
Event::listen('abweb.forms.beforeValidateForm', function (CustomForm $customForm, array &$data, array &$rules, array &$messages, Validator $validator) {
    // Do something...
});

// Runs if validating the payload of a form fails
Event::listen('abweb.forms.onValidateFormFail', function (CustomForm $customForm, array $data, array $rules, array $messages, Validator $validator) {
    // Do something...
});

// Runs if validating the payload of a form is successful
Event::listen('abweb.forms.afterValidateForm', function (CustomForm $customForm, array $data, array $rules, array $messages) {
    // Do something...
});

// Runs if validating the recaptcha response fails
Event::listen('abweb.forms.onRecaptchaFail', function (CustomForm $customForm, string $recaptchaResponse) {
    // Do something...
});

// Runs if validating the recaptcha response is successful
Event::listen('abweb.forms.onRecaptchaSuccess', function (CustomForm $customForm, array $data, array $rules, array $messages) {
    // Do something...
});

// Runs at the end of "onFormSubmit" (when submitting a CustomForm)
Event::listen('abweb.forms.afterFormSubmit', function (CustomForm $customForm, array $data, $response) {
    // Do something...
});

// Runs before rendering the form (or retrieving pre-rendered cache)
Event::listen('abweb.forms.beforeRenderPartial', function (CustomForm $customForm, bool $cachingEnabled) {
    // Do something...
    if ($cachingEnabled) {
        // Do something...
    }
});

// Runs after rendering the form (or retrieving pre-rendered cache). Can adjust HTML.
Event::listen('abweb.forms.afterRenderPartial', function (CustomForm $customForm, string &$html) {
    // Do something...
    $html .= '<script src="https://api.google.com/.../library.js"></script>';
});

// Runs before generating the HtmlForm instance (using HtmlElement). Can adjust the HtmlGenerator class.
Event::listen('abweb.forms.beforeGenerateHtmlElement', function (CustomForm $customForm, HtmlGenerator &$htmlGenerator) {
    // Do something...
    $htmlGenerator = new \Example\ClassThatExtendsHtmlGenerator();
    $htmlGenerator->magic();
});

// Runs after generating the HtmlForm instance (using HtmlElement). Can adjust the HtmlGenerator class.
Event::listen('abweb.forms.afterGenerateHtmlElement', function (CustomForm $customForm, HtmlGenerator &$htmlGenerator) {
    // Do something...
    $div = new \YeTii\HtmlElement\Elements\HtmlP([
        'class' => 'text-warning',
        'node' => 'Warning: Do not submit the form without reading our privacy policy.',
    ]);
    $htmlGenerator->htmlForm->addChild($div);
});

// Runs before sending notification emails. Can adjust data and recipient
Event::listen('abweb.forms.beforeSendNotification', function (CustomForm $customForm, array &$data, array &$to) {
    // Do something...
});

// Runs before validating notification recipients. Can adjust data, recipient and rules
Event::listen('abweb.forms.beforeNotificationValidation', function (CustomForm $customForm, array $data, array &$to, array &$rules, Validator &$validator) {
    // Do something...
});

// Runs if validating notification recipients fails
Event::listen('abweb.forms.onNotificationValidationFail', function (CustomForm $customForm, array $data, array $to, array $rules, Validator $validator) {
    // Do something...
    Log::info($validator->messages()->toArray());
});

// Runs if validating notification recipients is successful
Event::listen('abweb.forms.onNotificationValidationSuccess', function (CustomForm $customForm, array $data, array $to, array $rules) {
    // Do something...
});

// Runs when configuring the $message to send a notification to recipients
Event::listen('abweb.forms.onSendNotification', function (CustomForm $customForm, &$message, $to) {
    // Do something...
    $message->replyTo('noreply@domain.com');
});

// Runs after sending (or queueing) notification to recipients
Event::listen('abweb.forms.afterSendNotification', function (CustomForm $customForm, array $data, bool $success) {
    // Do something...
    if (!$success) {
        Log::debug('Dammit whats wrong now?');
    }
});

// Runs before sending auto reply email. Can adjust data, recipient name and email
Event::listen('abweb.forms.beforeSendAutoReply', function (CustomForm $customForm, array &$data, &$toEmail, &$toName) {
    // Do something...
    $toEmail = 'new@example.org';
    $toName = 'Mr. Nobody';
});

// Runs if validating auto reply recipient fails.
Event::listen('abweb.forms.onAutoReplyValidationFail', function (CustomForm $customForm, array $data, $toEmail, $toName, string $failedOn) {
    // Do something...
    if ($failedOn === 'email') {
        Log::debug('Invalid auto-reply email');
    } else { // 'name'
        Log::debug('Invalid auto-reply name');
    }
});

// Runs when configuring the $message to send an automatic reply to the user
Event::listen('abweb.forms.onSendAutoReply', function (CustomForm $customForm, &$message, $to) {
    // Do something...
    $message->bcc('mwahahaha@domain.com');
});

// Runs after sending (or queueing) auto reply email
Event::listen('abweb.forms.afterSendAutoReply', function (CustomForm $customForm, array $data, bool $success) {
    // Do something...
    if (!$success) {
        Log::debug($data);
    }
});

// Runs before saving the submission in the database. Can adjust the Submission's data
Event::listen('abweb.forms.beforeSaveSubmission', function (CustomForm $customForm, array &$submissionData) {
    // Do something...
    $submissionData['extraField'] = 'Add this to the database please';
});

// Runs after saving the submission in the database
Event::listen('abweb.forms.afterSaveSubmission', function (CustomForm $customForm, Submission $submission) {
    // Do something...
    if ($submission->url == '/') {
        $submission->delete();
    }
});

// Runs before setting email template vars. Can adjust the variables
Event::listen('abweb.forms.beforeSetTemplateVars', function (CustomForm $customForm, array &$vars) {
    // Do something...
    $vars['date'] = \Carbon\Carbon::now()->format('jS F Y');
});

Bugs and feature requests

We encourage open source, so if you find any bugs, typos, issues or think of some great features, please open an issue or PR in the GitHub repo.

  • Found the plugin useful on 19 Oct, 2020

    great plugin! 'cause there is no german translation, I build a first version and send a pull request on github

  • Found the plugin useful on 13 Oct, 2019

    it's really a great plugin, but I haven't known how to insert it on a page.

  • Found the plugin useful on 24 Aug, 2019

    its an awesone plugin ! How do i use Validation Message? I try it but it doesnt work. It shows default validation messages, Thanks

1.2.7

Add German translation

Oct 19, 2020

1.2.6

Add notification reply-to fields

Oct 16, 2020

1.2.5

Add support for HTML Attributes in TextArea field

Oct 08, 2020

1.2.4

Update lang for successful ordering of fields

Oct 08, 2020

1.2.3

Add ordering for fields

Oct 08, 2020

1.2.2

Add persmissions to the plugin

Jun 29, 2020

1.2.1

Remove obsolete foreign key constraints for tables

Feb 14, 2020

1.2.0

Fix auto reply for non-required email field - now aborts without JSON error

Oct 22, 2019

1.1.3

Fix error on submission view page

Sep 24, 2019

1.1.2

Add option to show/hide fields in certain emails

Sep 06, 2019

1.1.1

Migrate old v1.0.6 options

Sep 06, 2019

1.1.0

Change templating engine from Twig to HtmlElement. Add more field types, show description in form flag, default value field, custom attributes area

Sep 06, 2019

1.0.7

Fix missing values in the labels "for" attributes

Sep 05, 2019

1.0.6

Add events for mailable instances when sending a notification and/or reply

Jun 25, 2019

1.0.5

Add options field for select, radio and checkbox fields

Jun 25, 2019

1.0.4

Implement IP throttle

Jun 22, 2019

1.0.3

Events, more tests, more stable release

Jun 22, 2019

1.0.2

Stable release

Jun 22, 2019

1.0.1

Initialize plugin.

Jun 22, 2019

1.0.x to 1.1.x

This upgrade should be fairly simple. If you have customised field or form partials then you will need to adjust how it's been modified as we now introduce HtmlElement which handles the rendering of the form.

If you have just customised the settings, etc, you won't need to do anything.

See documentation for more information.