Eleven59-laravel-nanoform NPM

Laravel Nanoform

Automagically make forms ajax, compatible with Laravel backend processing and Google ReCaptcha V3

What is it?

This module allows you to add Ajax functionality with (backend) form validation and Google ReCaptcha V3 support in a single line of code:

let myAjaxForm = new Nanoform("#my-regular-old-form-id");

Installation

Via npm

npm install eleven59-laravel-nanoform

Then in your app.js or wherever

// Laravel Vite
import {Nanoform} from 'eleven59-laravel-nanoform';

// Laravel Mix
let Nanoform = require('eleven59-laravel-nanoform');

Dependencies

This package uses jQuery ^3.0 because I was lazy.

Usage

// Initialize Form
// The second parameter with options is entirely optional, see below
let myAwesomeForm = new Nanoform("#my-awesome-form-id", {
    'successMessage': "That's awesome! You rock!"
});

This automates processing the form using Ajax instead of a full page refresh. This makes a number of assumptions, all of which are marked here. See options below for customization.

Binds ajax submit to the [type="submit"] element in the form.
Uses the form action and method fields for the ajax submit.
Automatically processes Laravel backend validation results:
- Displays all returned errors (or a default generic error message) in an .errors container
- Adds invalid class to fields that contain errors
Automatically processes Laravel success by showing the returned message (or a default success message) in a .success container
Automates showing a .loading container on form submit - and hiding it again on completion.
Automates Google Recaptcha V3 if provided (see below)

Google Recaptcha V3

To automate using Google's Score-based ReCaptcha V3, do the following:

Add <script src="https://www.google.com/recaptcha/api.js?render=[your sitekey]"></script> to your <body> or <head> html code.
Add data-sitekey="[your sitekey]" and data-action="[action]" to your <form> tag.
Add <input type="hidden" name="g-recaptcha-response" id="{{ uniqid() }}"> to your <form> html code.
Add laravel backend validation (I found josiasmontag/laravel-recaptchav3 very easy to use).

This is then auto-detected by this script and will work out of the box. Tested with Google Recaptcha V3 only.

The token automatically reloads on submit, so you can resubmit after errors without any issue.

Full example (Blade):

<!-- Put this in your <head> or, even better, at the end of the <body> -->
<script src="https://www.google.com/recaptcha/api.js?render=[your sitekey]"></script>

<!-- The form -->
<form method="POST" action="/whoop" data-sitekey="[your sitekey]" data-action="[action]">
    @csrf <!-- Because what, are you NOT using CSRF? Come on. -->  
    <input type="hidden" name="g-recaptcha-response" id="{{ uniqid() }}">
    <input type="text" name="whatsup" placeholder="I'm a Lion!">
    <button type="submit" class="btn btn-primary">OK!</button>
</form>

Don't forget to replace [your sitekey] and [action] everywhere.

Options

This thing is customizable out the wazoo

Option	Default	Description
`additionalTimeout`	`0`	Additional timeout after receiving AJAX response before processing results (in ms).
`beforeSendCallback`	`function()`	This option allows you to specify an additional callback function that will run before the form is sent to the server using AJAX.
`buttonSelector`	`[type="submit"]`	jQuery compatible element selector to bind the submit function to.
`dataType`	`json`	Predefines the datatype expected to be returned from backend processing. Don't know why you would change this, but you can.
`errorCallback`	`function(jqXHR, testStatus)`	This option allows you to specify an additional callback function that will run custom code after form submit reported an error.
`errorClass`	`invalid`	Classname to add to form fields when they contain errors according to Laravel validation
`errorMessage`	See description	Default message to show when backend returns a nondescript error or no valid data is seen in the response. Defaults: Something went wrong while processing the form. Please try again later.
`errorSelector`	`.errors` †	Container that will hold the error messages. This script assumes it will initially have the `hidden` class. This class is removed when errors are returned on form submit. It is never re-added, so hiding the errors again is your own responsibility. You can set this to `false` to skip this functionality.
`formLoadingClass`	`form-loading` †	This class will be added to the form element during loading and removed again after. This will allow you to hide the form using CSS if necessary.
`formSentClass`	`form-sent` †	This class will be added to the form element when the form was successfully processed. This will allow you to hide the form using CSS if necessary.
`loadingSelector`	`.loading` †	Container that will be shown while processing and loading the backend response. This script assumes it will initially have the `hidden` class. This class is removed when submitting the form. On success or error, the "hidden" class is automatically added to this container again. You can set this to `false` to skip this functionality.
`successCallback`	`function(data, textStatus, jqXHR)`	This option allows you to specify an additional callback function that will run custom code after form submit reported success.
`successMessage`	See description	If your backend returns `{"success": "Message"}`, then that message will be shown. Otherwise the message defaults to this string. The default is: Thank you for your inquiry.
`successSelector`	`.success` †	Container that will hold the success message. This script assumes it will initially have the `hidden` class. This class is removed when submitting the form. On success or error, the "hidden" class is automatically added to this container again. You can set this to `false` to skip this functionality.

† Containers should be placed within the <form> element. This was done to allow support for multiple forms on one page with the default settings.

Change log

Only breaking changes listed here. For other changes see commit log.

2.0.0

The main function in index.js has been renamed from Index to Nanoform to provide better compatibility with Laravel Vite. Should be no issue if you've never manually referred to this function, but if you did then this could be a breaking change.

Credits

Coded and tested by Nik Linders @ eleven59.nl

License

This project was released under the MIT license, so you can install it on top of any Backpack & Laravel project. Please see the license file for more information.

jquery

@infinitebrahmanuniverse/nolb-elev @everything-registry/sub-chunk-1568

2 years ago

3 years ago

3 years ago

3 years ago

3 years ago