‚̧Nutritious Polygonal Meatball
    Have ideas to improve npm?Join in the discussion! ¬Ľ

    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

      1

      Version

      2.3.1

      License

      GPL-3.0

      Unpacked Size

      97.1 kB

      Total Files

      23

      Last publish

      Collaborators

      • avatar