Bring the best of OSS JavaScript development to your projects with npm Orgs - private packages & team management tools.Learn more »

jagfx-formjs

2.1.0 • Public • Published 24 days ago

FormJS

jQuery plugin to send a html form over ajax request with feedback system

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

{
    "type": 	"success",
    "url": 		"yourUrl (optionally entry)",
    "data" : 	{
        "title": 	"yourTitle",
        "message": 	"yourMessage"
    }
}

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.

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

Keywords

install

npm i jagfx-formjs

weekly downloads

version

2.1.0

license

GPL-3.0

homepage

github.com

repository

github

last publish

24 days ago

collaborators

Test with RunKit

Report a vulnerability