jagfx-formjs

2.0.0 • Public • Published 2 months ago

Feedback jQuery plugin

jQuery plugin to give feedback to user with ajax request

DEMO

Fonts

Quicksand regular

Install

NPM

Install: npm install --save jagfx-formjs

Module: require('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/@fortawesome/fontawesome-free-webfonts/css/fa-solid.css" >
        <link rel="stylesheet" href="node_modules/@fortawesome/fontawesome-free-webfonts/css/fa-brands.css" >
        <link rel="stylesheet" href="node_modules/@fortawesome/fontawesome-free-webfonts/css/fontawesome.css" >
        
        <link rel="stylesheet" href="node_modules/jagfx-formjs/dist/css/theme-flat/formJS-flat.css" id="styleAlert" >
    </head >
    <body >
        <form id="yourForm" method="post" >
            <button class="btn" type="submit">Submit</button>
        </form>
        
        <script >
            $( '#youForm' ).formJS();
        </script> 
    </body >
</html >

Note: By default, the font used is "Quicksand Regular". If you want to change it, you can override or create a custom style

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 theme 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 by 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. It 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

By default, i use Fontawesome regular icons pack.

You can change it, set html icon as you want and use icons pack as you want:

<i></i> balise
<span></span> balise
<img /> balise
Text also

$( '#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:   'ERR'
    }
} );

Form

If you have custom header request, you can pass into this setting. The url, method and data can't be modified

Also, you can change de 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 user after 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 are called. You can set. The current alert is passed to function parameter

$( '#yourForm' ).formJS( {
    callback: function ( currentAlert ) {
        // Do something with currentAlert
    }
} );

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 class="fas fa-circle-notch fa-spin"></span>',
        success: '<span class="fas fa-check"></span>',
        info:    '<span class="fas fa-info"></span>',
        warning: '<span class="fas fa-exclamation-triangle"></span>',
        error:   '<span class="fas fa-fire"></span>'
    },
    form:        {
        ajaxSettings:   {
            contentType: false
        },
        alertContainer: '.formJS',
        btnSubmit:      '.btn[type="submit"]'
    },
    redirection: {
        message: 'Automatic redirection in a second',
        delay:   1100
    },
    callback:    function ( currentAlert ) {
    }
};

Custom style

You have SCSS files to allow you to create custom style.

In formJSFolder/scss/, you can find _core*.scss files. Use it as base structure of your custom style. Create a folder named with theme name and add two file:

_variables.scss: Contain YOUR theme variable. It use to override core variables
your-theme-name.scss: Contain all customisation for type of alert: Success, Info, Warning and Error. Use preset from on of existing template

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.0.0

license

GPL-3.0

homepage

github.com

repository

github

last publish

2 months ago

collaborators

Test with RunKit

Report a vulnerability