form-extra-events
v2.0.3
Published
Add extra events for html forms
Downloads
6,334
Readme
form-extra-events
Add extra events for submit html forms.
Install
npm install form-extra-events
Usage
This example implements adding the loading
class for all forms during submission.
import 'form-extra-events';
document.addEventListener('submitstart', function(e) {
e.target.classList.add('loading');
});
document.addEventListener('submitend', function(e) {
e.target.classList.remove('loading');
});
Documentation
Events
form-extra-events
adds the following events for all forms:
submitlast
- triggered after executing all handlers of the standardsubmit
event, here you can still cancel the standard browser behavior by callingpreventDefault()
, but this is recommended only to send a request in other ways, for example, via AJAX, that is, the request must be executed in any case;submitbefore
- triggers before the form is submitted, here you can still modify the form, but you cannot cancel the standard browser behavior by callingpreventDefault()
, i.e. the event is guaranteed to be executed before being sent;submitstart
- triggered after the form has been submitted, changes in the form will not change the request;submitend
- triggered after the form has been submitted.
Warning: the submitend
event is based on the unload
event, with all its limitations.
For example, you cannot open a window by calling window.open()
.
Also for many mobile browsers this event is not triggered.
Event params
The event object contains additional parameters:
transport {string}
- for eventssubmitbefore
,submitstart
,submitend
passes the name of the transport with which the form is transmitted. More details below in the section transports.activeButton {Element}
- for the eventssubmitlast
,submitbefore
passes the button element with which the form was sent.
Transports
The submitlast
event is introduced specifically for the implementation of various transports.
In form-plus, this event is used to submit form via AJAX.
This AJAX transport also generates the events submitbefore
, submitstart
, submitend
, but with a different parameter of the event transport
.
If you need to capture the event of a regular browser-based form submission, you need to check the transport === 'default'
parameter in the handler:
document.addEventListener('submitbefore', function(e) {
if (e.detail.transport === 'default') {
let hidden = document.createElement('input');
hidden.name = 'isNoAjax';
hidden.value = '1';
e.target.appendChild(hidden);
}
});
Detect download state
By default, the script cannot catch the end of form submission, if the browser has switched to the file download state, so in this case it does not handle the submitend
event.
Similarly, if you specify the attribute target="_blank"
for the form.
To catch the submitend
event in such cases, use the catch-download
script from the form-plus package.
Import types
There are several entry points for importing a library:
import ExtraEvents from 'form-extra-events'
- similarlyregister-with-shims
;import ExtraEvents from 'form-extra-events/standard'
- easy import without polyfills for ie11, register is required;import ExtraEvents from 'form-extra-events/with-shims'
- import with shims for ie11, register is required;import ExtraEvents from 'form-extra-events/with-polyfills'
- import with polyfill for ie11, register is required;import ExtraEvents from 'form-extra-events/register'
- import without polyfills for ie11, auto-register;import ExtraEvents from 'form-extra-events/register-with-shims'
- import with shims for ie11, auto-register;import ExtraEvents from 'form-extra-events/register-with-polifills'
- import with polyfill for ie11, auto-register.
Differences shims from polyfills you can read in polyshim package.
When directly include the script from the dist
folder to the browser, you can get an ExtraEvent instance via window.FormExtraEvents.default
.
Registration and name of events
When importing a package without register, you need to register it. When registering, you can replace the event names:
import ExtraEvents from 'form-extra-events/with-shims';
ExtraEvents.register({
eventLast: 'last',
})
Methods
register([settings])
- register librarysettings {Object} [{}]
- settings@return {Object}
- returns the current settings
unregister()
- unregister librarygetSettings()
- returns the current settings@return {Object}
getSendingForm()
- returns the current form being submitted@return {HTMLFormElement|null}
setShim([setClosest[, setObjectAssign[, setCustomEvent]]])
- sets shims for non-cross-browser methodssetClosest {Function|null}
- shim forElement.prototype.closest
setObjectAssign {Function|null}
- shim forObject.assign
setCustomEvent {Function|null}
- shim fornew CustomEvent
Settings
eventLast {string} ['submitlast']
- name of eventsubmitlast
eventBefore {string} ['submitbefore']
- name of eventsubmitbefore
eventStart {string} ['submitstart']
- name of eventsubmitstart
eventEnd {string} ['submitend']
- name of eventsubmitend
Testing
For tests, you need to install selenium-drivers for browsers. To run tests, use:
npm test
Browsers support
- Internet Explorer 11+
- Other modern browsers
For old browsers use version 1.x.