GitHub - JAGFx/FormJS: A jQuery plugin to submit a form without reloading the page. It send a customizable feedback after sending

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

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

README.md

FormJS

DEMO

Install

NPM

Usage

Quick use

Minimal code

Response structure

Themes

Custom settings

Alert message

Keys

Icons

Form

Redirection

Callback

Events

Trigger

Full default settings

Custom style

NPM commands

License

About

Releases 8

Sponsor this project

Packages

Languages

License

JAGFx/FormJS

Sign In Required

Launching GitHub Desktop

Launching GitHub Desktop

Launching Xcode

Launching Visual Studio Code

Latest commit

Git stats

Files

About

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project

Languages