jagfx / form-js
Envoie de formulaire en AJAX avec feedback utilisateur
Requires
- components/jquery: 3.1.*
This package is not auto-updated.
Last update: 2025-01-28 18:54:59 UTC
README
FormJS
jQuery plugin submit a form without reloading the page. It send a customizable feedback after sending
DEMO
Install
NPM
<!DOCTYPE html> <html lang="en" > <head > <meta charset="UTF-8" /> <title >FormJS</title > <link rel="stylesheet" href="node_modules/jagfx-formjs/dist/css/theme-flat/formJS-flat.css" /> </head > <body > <form id="yourForm" method="post" > <button class="btn" type="submit">Submit</button> </form> <script src="node_modules/jquery/dist/jquery.min.js" ></script > <script src="node_modules/jagfx-formjs/dist/formJS.min.js" ></script > <script > $( '#yourForm' ).formJS(); </script> </body > </html >
Response structure
The response MUST be in JSON and match with this structure
The distinction of response type it's on the field data
or view
:
- If you return a response with the
data
field, the response was processed as a feedback. - If you return a response with the
view
field, the response was processed as a view - If you return a response with the
data
andview
, the response was process as a feedback
Themes
You have 3 themes available for the alert:
- Bootstrap 3/4 (
theme-bs.css
) - Custom (
theme-cust.css
) - Flat (
theme-flat.css
)
You can choose it by including corresponding CSS
Custom settings
Alert message
You can customise the default error message (Unexpected for example)
$( '#yourForm' ).formJS( { alerts: { unexpected: { title: 'Custom unexpected error title', message: 'Custom unexpected error message' }, failSend: { title: 'Custom fail send data error title', message: 'Custom fail send data error message' } } } );
Keys
The keys are suffix added after 'formjs' class into alertContainer
. Its use for style customisation.
Note: If you change it, you MUST rebuild style with SCSS builder
$( '#yourForm' ).formJS( { keys: { success: 'success-custom', info: 'info-custom', warning: 'warning-custom', error: 'error-custom' } } );
Icons
You can change the icon, set html icon as you want and use icons pack as you want:
<i></i> balise
<span></span> balise
<img /> balise
- Text also (You need to embrace the text with html balise)
$( '#yourForm' ).formJS( { icons: { loading: '<span class="fas fa-circle-notch fa-spin"></span>', success: '<i class="fas fa-check-square"></i>', info: '<span class="ti-info"></span>', warning: '<img src="myIcon.svg" />', error: '<span>ERR</span>' } } );
Form
If you have a custom header request, you can pass into this setting. The url
, method
and data
cannot be modified
Also, you can change the formJS container and submit button identifier.
Note: If you change container, you MUST rebuild style with correct container.
$( '#yourForm' ).formJS( { form: { ajaxSettings: { async: false, beforeSend: function (xhr){ xhr.setRequestHeader('Authorization', make_base_auth(username, password)); } }, alertContainer: '.customContainer', btnSubmit: '.myCustomBtnID' } } );
Redirection
You can redirect the user after an Ajax request. A message will be added after error title.
You can change this message and delay before the redirection
$( '#yourForm' ).formJS( { redirection: { message: 'Custom redirect message', delay: 2500 } } );
Callback
At the end of precess, a callback is called. You can set. The current alert is passed to function parameter.
$( '#yourForm' ).formJS( { callback: function ( currentAlert ) { // Do something with currentAlert } } );
Events
You have some event that you can handle:
For the formjs:error
, you can know the origin of the error:
AjaxSuccessCallback
: An error during the ajax success callbackAjaxFailCallback
: An error during the ajax fail callbackPreSubmit
: An error during the submitting process
var $form = $( '#yourForm' ).formJS(); $form.on( 'formjs:write-alert', function ( e, currentAlert ) { // Do something with the current alert ... } );
Trigger
If you need to use this plugin from the outside of it, you can trigger some event
var $form = $( '#yourForm' ).formJS(); $( '#anotherSendingButton' ).click( function () { $form.trigger( 'formjs:send-form' ); } );
Full default settings
var settings = { alerts: { unexpected: { title: 'Error', message: 'Unexpected error occurred' }, failSend: { title: 'Error', message: 'Unable to send data' } }, keys: { success: 'success', info: 'info', warning: 'warning', error: 'error' }, icons: { loading: '<span>⌛</span>', success: '<span>✓</span>', info: '<span>🛈</span>', warning: '<span>﹗</span>', error: '<span>⨯</span>' }, form: { ajaxSettings: { contentType: false }, alertContainer: '.formJS', btnSubmit: '.btn[type="submit"]', enableWriteAlert: true }, redirection: { message: 'Automatic redirection in a second', delay: 1100 }, callback: function ( currentAlert ) { } };
Custom style
You have SCSS files to allow you to create custom styles.
In formJSFolder/scss/
, you can find _core*.scss
files. Use it as the base structure of your custom style.
Create a folder named with theme name and add to file:
_variables.scss
: Contain YOUR theme variable. It uses to override core variablesyour-theme-name.scss
: Contain all customisation for type of alert:Success
,Info
,Warning
andError
. Use preset from one of existing templates
At the end of customisation, run npm run scss:dist
to generate your style css file and minified too.
You must include node_module
folder into you sass converter to build a new stylesheet.
If necessary, install bourbon
$ npm i --only=dev $ npm i --no-save bourbon
NPM commands
Remove old css files
$ npm run scss:clean
Generate css files
$ npm run scss:build
Launch scss watcher to generate css file at change
$ npm run scss:watch
Generate css dist files
$ npm run css:dist
Generate js dist files
$ npm run js:dist
Generate css and js dist files
$ npm run gulp:default
License
Unless stated otherwise all works are:
- Copyright © SMITH Emmanuel
and licensed under: