HTML Form Handler

html-form (htmf) is a minimalist library similar to HTMX and other
technologies (Behavior.js (RIP), unpoly, fixi, etc.) designed to work directly
with forms. It has a minimal API. It also makes it easy to build Multipage apps
(MPA) which works without JavaScript and the JS is just progressive enhancement.

I have successfully created offline-first applications with this library. I have
also successfully used it to create an offline-first, SPA, PWA application.

htmf is 1.9 kB minified and 1.3 kB minified and zipped.

Tests can be viewed here:

Overview

This JavaScript code provides functionality for handling HTML form submissions
with added features such as asynchronous submission, AJAX requests, and dynamic
content updates.

Features

1. Asynchronous Form Submission:
- The code listens for form submission events and handles them
asynchronously using the Fetch API.
2. Event Pub-Sub System:
- Utilizes a simple event-publishing and subscribing system to allow for
customization and extensibility.
3. Dynamic Content Updates:
- Supports dynamic content updates based on the response from the server,
including JSON and HTML responses.
4. If you know HTML forms then you know how to use this library.

Installation

Copy the file from the source code public/html-form.js or the minified version
public/html-form.min.js.

Or use npm npm i html-form and reference it like so import "html-form".

Usage

$3

When clicking the button below it will retrieve the HTML from /foo and replace
the content in the button element.

``html



Submit



`

This will replace the button element with the returned HTML from /foo. This
uses a button outside of the defined form. Native HTML for the win!

`html
Submit



`

This will replace the target element.

`html



Submit

`

$3

- html-form-events
- Create events from the reponse header.
- html-form-scroll
- Auto scroll to where you were before when content changes.
- Target scroll position after changing content.
- html-form-confirm
- When you would like to confirm a form submission.
- html-form-merge
- This uses Morphdom to merge the two HTML DOM elements.
- This is useful when you start to have too many changes on the page to track.
Then you just merge it all with ease.

$3

The HTML Form Handler (HF) library utilizes custom attributes on HTML elements
to enable various functionalities and customize the behavior of form
submissions. These attributes are designed to provide flexibility and
extensibility to meet different use cases.

1. hf

- Description: HTMF is an opt-in library. You can use all of the normal form
attributes and just add the attribute hf to enable it. Using hf-swap or
hf-target will also enable the form.

2. hf-ignore

- Description: Prevents the associated form or submitter element from being
processed by the HTML Form Handler.
- Usage:
- Add hf-ignore attribute to a form or submit button.

`html


Submit
`

3. hf-target or target

- Description: Specifies the target element for swapping content. The
library will update the content of this element based on the server response.
If you know that JS is enabled you can just use the target attribute instead.
- Usage:
- Add hf-target attribute to a form or submit button.
- The value is a query selector targeting the element where the content
should be updated.

`html


Submit
`

4. hf-swap

- Description: Defines the type of content swapping to be performed. This
attribute determines how the received HTML content should replace the target
element.
- Usage:
- Add hf-swap attribute to a form or submit button.
- Possible values: outerHTML, innerHTML, beforebegin, afterbegin,
beforeend, afterend, none.
- Default is outerHTML. This can be overriden by placing the attribute in
the body with the desired swap type.

`html


Submit
`

5. hf-transition

When placed on the body element it enables view transitions for all elements. It
can also be enabled for each swap by adding it to the submitter or form. This
behavior can also be overridden in the options settings.

`html

...

`

$3

1. hf:before

- Description: A cancelable event called befoe fetch is called.
- Usage:
- Subscribe to the hf:before event.

`javascript
doc.addEventListener("hf:before", e => {
// Handle script-loaded event
});
`

2. hf:after

- Description: A cancelable event called befoe fetch is called.

3. hf:swap

- Description: A cancelable event called when the text content from the
fetched data is parsed and before the content is swapped.

3. hf:swapped

- Description: A cancelable event called after the content was swapped.

4. hf:completed

- Description: Called when no other operations will be performed.

$3

The HTML Form Handler library sends a custom header to the server to help
identify AJAX requests and provide additional information.

`
HF-Request: true
`

- Description: This header is sent with each AJAX request initiated by the
HTML Form Handler.
- Purpose: Identifies the request as originating from the HTML Form Handler,
allowing the server to distinguish between regular and AJAX requests.

$3

The HTML Form Handler library provides the ability to include custom headers in
the server's response, facilitating additional information or actions on the
client side.

These can override the client target/swap.

`
hf-target:
`

`
hf-swap:
`

$3

When a response is given outside of a 200 response a special handler will be
treated for that response.

1. 204 No Content
- Description: This will do nothing. This is useful for sending a custom
event with a response to the user, e.g., letting the user know the
information was saved.
2. Redirected
- Description: This will redirect the page to the specified response
URL.

Version

$3

- Fixed redirects.
- Added ability to override hf-target and hf-swap attributes with header
values.

- Make view transitions opt-in

- Rewrite inspired by fixi.
- Removed scrolling (put in separate package).
- Removed script loading.
- Removed some of the swap types.
- Added none swap type.
- Removed handling anything but HTML content type.

$3

Removed constraint on only allowing POST and GET calls.
Added ability to cancel swap.
Added ability to opt-in with just an "hf" attribute.
Added ability to use a different swapping mechanism.

Ignore submissions which do not include one of the attributes hf-target or
hf-select.

$3

In target allow value "this" to target the same element as the target.

Fix bugs from the change.

Prefer submitter over form for preventing repeat submissions before the previous
submission is completed. This allows for buttons to share a form and be
indepedent.

$3

Fixed how a form reset is done.

Fixed event to match documented event naming.

Fixed preventDefault being called for dialog method.

Fixed bugs which occurred during the rewrite.

$3

Substantial changes in this one. Fixed errors, use getAttribute to get the
attributes to avoid conflicts with form names. Fixed other errors. Standardized
event naming and attribute naming. Code clean up. Removed the JS Doc typing.
Changed how double click detection is handled. Fixed 205 response to reset form.

$3

Add ability to handle scripts returned in the HTML snippets.

$3

Improved scrolling experience. Made it more like
mpa-enhancer.

$3

Add ability to scroll target a location on a page after swapping in new HTML.

$3

Basically a rewrite.

- Improved scrolling.
- Use hf-target instead of target.
- Added more hf-swap types similar to HTMX which works with
insertAdjacentHTML.
- Use submitter instead of activeElement to determine override of form
values.
- 204 response is now ignored

$3

- Removed the 205 event in favor of more generalized events.
- Added more similar events to what HTMX has but more limited.
- Made events have the capability of being asynchronous. This allows for adding
classes.
- Swap with event rather than directly calling it. This will allow for
extensions that add a class to the newly created HTML.

$3

Introduced event for return status of 205 (Reset Content).

$3

Fixed bug when a button which created the event doesn't exist.

$3

Added more events and made events cancelable.

Added events: hf:completed and hf:redirected.

$3

Added auto scroll for when appending above the input.

$3

Bug fix - preventDefault() wasn't called.
Bug fix - For http status of 204 or 400 don't print content type error message.

$3

Removed click and submit methods as requestSubmit is
available.
Note, a polyfill might be needed.

Removed debounce helper (which removes all helpers for this project). Just use
underscore.js or any other library
implementation of it.

$3

Added ability to submit the form directly through htmf. Removed the ability of
click to submit the form through the button click.

$3

Prevent double submits. Added ability to send events from JSON in a header.
Added ability to delete elements with empty string.

$3

Default to innerHTML swap type. Determine target from the form itself.

$3

Removed hf-hidden attribute as this is redundant - use the noscript` html tag
instead.