form-fetch

AJAX fetch for HTML form submissions using form DOM data.

Installation

``bash
npm install @itrocks/form-fetch
`

Usage

With an HTML page containing a button, a form, and a div with id result,
you can fetch your form when clicking the button:

`ts
import { formFetch } from '@itrocks/form-fetch/form-fetch.js'

document.querySelector('button').addEventListener('click', async () =>
{
const htmlResponse = await formFetch(document.querySelector('form')).text()
document.getElementById('result').innerHTML = htmlResponse
})
`

Alternatively, add a submit event listener to the form
to trigger a fetch instead of a standard submission:

`ts
import { formFetchOnSubmit } from '@itrocks/form-fetch/form-fetch.js'

window.addEventListener('load', () => {
formFetchOnSubmit(document.querySelector('form'), async response => {
document.getElementById('result').innerHTML = await response.text()
})
})
`

For a streamlined approach, use xtarget
and build to automate form-fetch:

`ts
import { buildXTarget } from '@itrocks/xtarget/xtarget.js'
buildXTarget()
`

Features

form attributes
automatically set fetch() options:

- action
=> fetch resource
- form data
=> request body
- enctype
=> body encoding as FormData
or URLSearchParams
- method
=> request method

You can override these options with custom values for action
and RequestInit.

API

$3

A type alias for form submitter elements:

`ts
type FormElement = HTMLButtonElement | HTMLFormElement | HTMLInputElement
`

$3

Submits a form using fetch(),
based on form DOM data.

`ts
response = formFetch(form)
response = formFetch(form, action)
response = formFetch(form, action, init)
`

Parameters:

- form:
An HTMLFormElement
to submit with fetch().
- action:
Optional resource URL.
Defaults to form's action attribute.
- init:
A RequestInit object
for custom request settings.
- returned response:
A Promise
that resolves to a Response object,
as returned by the call to fetch().

Example:

`ts
document.querySelectorAll('form').forEach(form => {
formFetch(form)
.then(response => response.text())
.then(html => document.getElementById('result').append(html))
})
`

$3

Attaches a submit
event listener
to fetch instead of submit.

`ts
formFetchOnSubmit(element, setResponse)
formFetchOnSubmit(element, setResponse, init)
formFetchOnSubmit(element, setResponse, init, onError)
`

Parameters:

- element:
A FormElement (form, button, or input).
Passing a button or input allows intercepting submission without direct access to the form element.
- setResponse:
A callback handling the Response:
`ts
function(response: Response, target: string, form: HTMLFormElement): void
`
- response:
The retrieved Response.
- target:
The target string where the form response should be displayed,
determined by the formtarget of the submitter
or the target of the form.
- form:
The submitted HTMLFormElement.\


- init:
A callback that returns a RequestInit object
containing any custom settings to apply to the request.
- onError:
A callback that handles errors during the form submission process.
`ts
function(error: any, action: string, target: string): void
`
- error:
The thrown error.
- action:
The URL of the form submission.
- target:
The target string where the form response should be displayed,
determined by the formtarget of the submitter
or the target of the form.

$3

Determines the effective method
for fetch() submit.

`ts
method = formMethod(form)
method = formMethod(form, init)
`

Parameters:

- form:
A HTMLFormElement.
- init:
An optional RequestInit object.
If init.method is set, it is returned.
- returned method:
The return value is the calculated HTTP method, determined by the following priority of non-empty values:
- The value of init.method,
- The data-method` attribute value of the form,
- The value of the form's method attribute.