FormSender is a component to send forms with ajax. It includes a plugin and a small javascript file without dependencies like jQuery.

Install

Install FormSender with Extras module, then place a call to the client handler in the templates:

<script>
document.addEventListener('DOMContentLoaded', function() {
    new FormSender();
})
</script>

Client handler script is included automatically, if you are using standard Evo pages. If not, you should include it manually:

<script defer src="assets/plugins/formsender/formsender.min.js"></script>

Now forms having required markup will be sent via ajax to the /forms url (it can be changed in the plugin settings).

Forms Markup

The form itself should be placed into the block having form-wrapper class (by default), and the blocks where error messages will be displayed should have the data-field attribute:

data-field="field_name"

Example:

<div class="form-wrapper">
   <form>
      <input type="hidden" name="formid" value="message">
      <div class="form-group" data-field="name">
         <label for="name">Name</label>
         <input type="text" class="form-control" id="name" name="name">
      </div>
      <div class="form-group" data-field="email">
         <label for="email">Email address</label>
         <input type="email" class="form-control" id="email" name="email">
      </div>
      <div class="form-group" data-field="message">
         <label for="message">Example textarea</label>
         <textarea class="form-control" id="message" rows="3" name="message"></textarea>
      </div>
   </form>
</div>

Forms settings

Form settings are stored as php files in the core/custom/forms folder. The file name must match the value of the formid field. The file specifies an array of parameters for the FormLister snippet.

You do not need to specify a form template as it is not used.

For the form above, there will be a message.php file like this:

<?php
 
return [
    'api'                => 2,
    'formid'             => 'message',
    'filters'            => [
        'name'   => ['trim', 'stripTags', 'removeExtraSpaces'],
        'email'  => ['trim', 'stripTags', 'email', 'removeExtraSpaces'],
        'message' => ['trim', 'stripTags', 'compressText'],
    ],
    'rules'              => [
        'name'   => [
            'required' => 'Введите имя',
        ],
        'email'  => [
            'required' => 'Введите email',
            'email'    => 'Введите email правильно'
        ],
        'message' => [
            'required' => 'Введите сообщение',
        ],
    ],
    'successTpl'         => '@CODE:<div class="alert alert-success">Спасибо!</div>',
    'reportTpl'          => '@CODE:[+name+]<br>[+email+]<br>[+message+]'
];

If you don't set the api parameter, it will be set automatically with the value 2. If someone suddenly forgot, the value 1 means that FormLister returns only data, and 2 also means that it returns html (in this case, a message about successful sending).

If you want to use some other FormLister based snippet, then its name should be specified in the snippet parameter:

'snippet' => 'CustomMessageForm'

Pop-up notifications

Using the alert() function to display messages from forms is not a good idea, so for beautiful notifications you can choose any appropriate library.

Then you should add messager parameter to your client handler call:

document.addEventListener('DOMContentLoaded', function () {
    new FormSender({
        messager: new FormSenderMessager(
            function (message) {
                // simple message output
            },
            function (message) {
                // error message output
            }
        )
    });
});

For example, for the Growl library it would be something like this:

document.addEventListener('DOMContentLoaded', function () {
    new FormSender({
        messager: new FormSenderMessager(
            function (message) {
                $.growl.notice({title:'', message: message});
            },
            function (message) {
                $.growl.warning({title:'', message: message});
            }
        )
    });
});

Client handler parameters

formWrapper

The selector of the block that the form is in. If the form is processed with the api=2 parameter, the contents of this block can be replaced upon successful processing.

The default is .form-wrapper

submitBtn

Button selector for submitting the form.

The default is [type=submit]

errorClass

The name of the class that is assigned to blocks marked for error output.

The default is has-error

errorMessageElement

The name of the element to display the error message.

The default is div

errorMessageClass

The name of the class to assign to the element containing the error message.

The default is help-block

successMessageText

The text of a message that can be displayed when the form is successfully processed.

The default is The form has been sent successfully

errorMessageText

The text of the message that is displayed when errors occur during the form submission process.

The default is Failed to send

url

Url of the server form handler. Specified in the FormSender plugin parameters.

The default is /forms

headers

Custom request headers.

The default is:

{
     'X-Requested-With': 'XMLHttpRequest'
}

messager

An object of the FormSenderMessager class, which implements the logic for displaying notifications.

Client Events

fs:before

Fires before a form is submitted. Can override default action.

fs:after

Fires after the form is submitted.

fs:error

Fires if errors occur while submitting the form.

fs:success

Fires when the server handler successfully processes the form. The default action can be overridden.

fs:fail

Fires if the server handler failed to process the form. Can override the default action.

Events parameters:

Parameter	Event	Description
wrapper	fs:before fs:after fs:error fs:success fs:fail	Block containing form
data	fs:before fs:after fs:error fs:success fs:fail	FormData object with form data
response	fs:after fs:success fs:fail	An object containing response data from a server handler
error	fs:error	Error data object