Publish your own packages to the world's most popular software ecosystem with npm Pro.Get started »

jagfx-formjs

2.3.1 • Public • Published

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:

    Install

    npm i jagfx-formjs

    DownloadsWeekly Downloads

    16

    Version

    2.3.1

    License

    GPL-3.0

    Unpacked Size

    97.1 kB

    Total Files

    23

    Last publish

    Collaborators

    • avatar