Skip to content
This repository has been archived by the owner. It is now read-only.
master
Switch branches/tags
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

FormJS

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

DEMO

Install

NPM

  • 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

    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
    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:

    • 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:

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

    Trigger

    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

    License

    Unless stated otherwise all works are:

    and licensed under: