SnapAjaxForms
Instantly turn an HTML form element into an AJAX request just by adding an attribute.
Dependencies
Requires jQuery's AJAX.
Usage
Make your web apps feel snappier by converting server-side requests into AJAX requests.
Instantiate SnapAjaxForms
new SnapAjaxForms();
Just add the data-ajax
attribute to any form you'd like to convert.
<form action="/url" method="POST" data-ajax>
...
</form>
Install
With NPM
npm install @stegopop/snap-ajax-forms
With a CDN
<script src="https://cdn.jsdelivr.net/npm/@stegopop/snap-ajax-forms"></script>
Browser Support
This project is transpiled to support back to IE11.
Options
Below are optional features that can be configured via an options object passed the the SnapAjaxForms constructor, or via data attributes.
Selector
By default, any form with the data-ajax
attribute will submit with SnapAjaxForms.
You may modify this with a css style selector in the options object.
new SnapAjaxForms({
select: "form.snap"
});
reCAPTCHA
Note: SnapAjaxForms only supports reCAPTCHA v3.
Added Google reCAPTCHA to SnapAjaxForms is super simple. Just add a recaptcha object with a version and siteKey as in the options object.
<script src="https://www.google.com/recaptcha/api.js?render=YourKeyHere11111111111111111111111111111"></script>
<script>
new SnapAjaxForms({
recaptcha: {
version: "v3",
siteKey: "YourKeyHere11111111111111111111111111111"
},
});
</script>
Then add the data-ajax-recaptcha
attribute to any form you'd like to protect.
<form action="/url" method="POST" data-ajax data-ajax-recaptcha>
...
</form>
Note: This version of the Google reCAPTCHA is score-based. If you wanted to perform certain actions based on that score,
then pass the score
from Google's Site Verify Response. You can access that in the form submit event, or the done
, always
, or fail
callbacks.
Showing Errors
Displaying errors in form inputs requires you to specify where you'd like the error to show.
Do that with the data-ajax-errors
attribute.
<form action="/url" method="POST" data-ajax>
<label for="favorite_sandwich">
<input type="text" name="favorite_sandwich" id="favorite_sandwich" required>
<div data-ajax-errors="favorite_sandwich"></div>
</label>
</form>
Then when the server finds an error, return a JSON message with this format for errors.
{
"errors": {
"favorite_sandwich": {
"messages": [
"This is the 'favorite_sandwich' error message.",
"There could multiple errors."
]
}
}
}
Submission Events
If you assign your form an id, then an event will be dispatched whenever your form is submitted.
Whatever casing you use for your form id will be converted to kebab-casing for the event name.
Example: <form id="testForm">
requires listening like this addEventListener("test-form-submit", function() { ... })
<form id="snap-example" action="/url" method="POST" data-ajax>
...
</form>
<script>
document.querySelector("#snap-example").addEventListener("snap-example-submit", function(data) {
console.log("Recieved an event");
});
</script>
Callbacks
Another way to call code after a submission is with the AJAX callback attributes.
- done
- fail
- always
- beforeSend
Pass the name of a JavaScript function to the attribute.
<form action="/url" method="POST"
data-ajax
data-ajax-done="doneCallbackExample"
data-ajax-fail="failCallbackExample"
data-ajax-always="alwaysCallbackExample"
data-ajax-before-send="beforeSendCallbackExample">
...
</form>
Pass the return data to your done callback function by adding a data argument to your function.
function doneCallbackExample(data) {
...
}
function failCallbackExample(data) {
...
}
function alwaysCallbackExample(data) {
...
}
function beforeSendCallbackExample() {
...
}
Disable Submit Button Duration
By default, the submission button for your form will be disabled for 1.5 seconds after submission to prevent multiple submissions.
You modify this disabled duration by setting submitDisabledDuration
in the options object passed to the SnapAjaxForms class.
new SnapAjaxForms({
submitDisabledDuration: 3000
});
Or you may disable it by setting the value to 0.
Multiple Submit Buttons
You may add multiple submit buttons to your form.
Adding a name and value to your buttons will allow you see which submitter was pressed from the backend.
Only the submitter element name and value will be submitted.
Just like the browser default, if you press enter in your form, the first submit element will be the one that submits the form.