FormJS
, (*1)
jQuery plugin submit a form without reloading the page. It send a customizable feedback after sending, (*2)
Install
, (*3)
NPM
, (*4)
<, (*5)
ul>
, (*6)
Install: npm install --save jagfx-formjs
Usage
Quick use
Minimal code
<!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, (*7)
The distinction of response type it's on the field data or view:, (*8)
- 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 and view, the response was process as a feedback
| Type of response |
Example |
Infos |
| Feedback |
{
"type": "success",
"url": "yourUrl (optionally entry)",
"data" : {
"title": "yourTitle",
"message": "yourMessage"
}
}
|
|
| View |
{
"type": "success",
"url": "yourUrl (optionally entry)",
"view" : "A HTML response"
}
|
|
Themes
You have 3 themes available for the alert:, (*9)
- Bootstrap 3/4 (
theme-bs.css )
- Custom (
theme-cust.css )
- Flat (
theme-flat.css )
You can choose it by including corresponding CSS, (*10)
Custom settings
Alert message
You can customise the default error message (Unexpected for example), (*11)
$( '#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., (*12)
Note: If you change it, you MUST rebuild style with SCSS builder, (*13)
$( '#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:, (*14)
<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>'
}
} );
If you have a custom header request, you can pass into this setting. The url, method and data cannot be modified, (*15)
Also, you can change the formJS container and submit button identifier., (*16)
Note: If you change container, you MUST rebuild style with correct container., (*17)
$( '#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., (*18)
You can change this message and delay before the redirection, (*19)
$( '#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., (*20)
$( '#yourForm' ).formJS( {
callback: function ( currentAlert ) {
// Do something with currentAlert
}
} );
Events
You have some event that you can handle:, (*21)
| Event name |
Params |
When ? |
| formjs:submit |
ajaxSettings: (JsonObject) Options pass to $.ajax() method
ajaxPending: (Boolean) If an ajax request is in progress |
At the start of submitting the form and before sending the ajax request |
| formjs:ajax-success |
feedback: (JsonObject) Raw data returned by the successful $.ajax() request |
On the success ajax callback, after the parsing returned data |
| formjs:error |
place: (String) The origin of the error
message: (String) The message of the error
data: (Mixed) The additionnal data of the error |
When an error occurred during the submit process |
| formjs:write-alert |
currentAlert: (JsonObject) The feedback data returned from the ajax request |
When an alert is rendered on the DOM |
For the formjs:error, you can know the origin of the error:, (*22)
-
AjaxSuccessCallback: An error during the ajax success callback
-
AjaxFailCallback: An error during the ajax fail callback
-
PreSubmit: 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, (*23)
| Event name |
Params |
Action |
| formjs:send-form |
Start the form sending processing |
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., (*24)
In formJSFolder/scss/, you can find _core*.scss files. Use it as the base structure of your custom style., (*25)
Create a folder named with theme name and add to file:, (*26)
-
_variables.scss: Contain YOUR theme variable. It uses to override core variables
-
your-theme-name.scss: Contain all customisation for type of alert: Success, Info, Warning and Error. 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., (*27)
You must include node_module folder into you sass converter to build a new stylesheet., (*28)
If necessary, install bourbon, (*29)
$ npm i --only=dev
$ npm i --no-save bourbon
NPM commands
Remove old css files, (*30)
$ npm run scss:clean
Generate css files, (*31)
$ npm run scss:build
Launch scss watcher to generate css file at change, (*32)
$ npm run scss:watch
Generate css dist files, (*33)
$ npm run css:dist
Generate js dist files, (*34)
$ npm run js:dist
Generate css and js dist files, (*35)
$ npm run gulp:default
License
Unless stated otherwise all works are:, (*36)
and licensed under:, (*37)
Wallogit.com
JAGFx