README

FormJS

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

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:

GNU General Public License v3.0 only

jagfx / form-js

Maintainers

Details