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">
</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 |
