Skip to content
This repository has been archived by the owner on Oct 24, 2020. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


NPM version NPM download Dependency Status Dev Dependency Status Build Status Scrutinizer Code Quality

jQuery plugin submit a form without reloading the page. It send a customizable feedback after sending




  • 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>
    		<script src="node_modules/jquery/dist/jquery.min.js" ></script >
    		<script src="node_modules/jagfx-formjs/dist/formJS.min.js" ></script >
    		<script >
    			$( '#yourForm' ).formJS();
    	</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 and view, the response was process as a feedback
    Type of response Example Infos
        "type": 	"success",
        "url": 		"yourUrl (optionally entry)",
        "data" : 	{
           "title": 	"yourTitle",
           "message": 	"yourMessage"
       "type": 	"success",
       "url": 	"yourUrl (optionally entry)",
       "view" : "A HTML response"


    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'
    } );


    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'
    } );


    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>'
    } );


    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'
    } );


    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
    } );


    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
    } );


    You have some event that you can handle:

    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:

    • 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 ...
    } );


    If you need to use this plugin from the outside of it, you can trigger some event

    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>&#8987;</span>',
    		success: '<span>&#10003;</span>',
    		info:    '<span>&#128712;</span>',
    		warning: '<span>&#65111;</span>',
    		error:   '<span>&#10799;</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 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.

    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


    Unless stated otherwise all works are:

    and licensed under: