html-form
v0.9.3
Published
A library for RESTful web development with an enhancement of forms.
Downloads
165
Readme
HTML Form Handler
html-form
(htmf) is a minimalist library similar to HTMX and other
technologies (Behavior.js (RIP), unpoly, 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 4.1 kB minified and 2.2 kB minified and zipped.
A Todo MVC example can be found 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
- Asynchronous Form Submission:
- The code listens for form submission events and handles them asynchronously using the Fetch API.
- Event Pub-Sub System:
- Utilizes a simple event-publishing and subscribing system to allow for customization and extensibility.
- Dynamic Content Updates:
- Supports dynamic content updates based on the response from the server, including JSON and HTML responses.
- Script Execution:
- Handles script execution within the received HTML content to ensure proper functionality.
- Scroll Management:
- Manages scroll positions before and after form submissions to provide a seamless user experience.
- Event-Based Customization:
- Allows customization of various events like "hf:request-before," "hf:request-after," "hf:json," "hf:swap," and more.
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
HTML Form Handler Attributes
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.
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.
<form hf-ignore>
<!-- Form content -->
</form>
<button type="submit" hf-ignore>Submit</button>
hf-target
- Description: Specifies the target element for swapping content. The library will update the content of this element based on the server response.
- 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.
<form hf-target="#result-container">
<!-- Form content -->
</form>
<button type="submit" hf-target=".result">Submit</button>
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
,append
,prepend
,beforebegin
,afterbegin
,beforeend
,afterend
,oob
.
- Add
<form hf-swap="innerHTML">
<!-- Form content -->
</form>
<button type="submit" hf-swap="append">Submit</button>
hf-select
- Description: Specifies a query selector all for selecting specific elements within the received HTML content to replace existing elements.
- Usage:
- Add
hf-select
attribute to a form or submit button.
- Add
<form hf-select=".select-container,#other-item">
<!-- Form content -->
</form>
<button type="submit" hf-select=".select-container,#other-item">Submit</button>
hf-scroll-ignore
- Description: Prevents automatic scrolling after a form submission.
- Usage:
- Add
hf-scroll-ignore
attribute to a form or submit button.
- Add
<form hf-scroll-ignore>
<!-- Form content -->
</form>
<button type="submit" hf-scroll-ignore>Submit</button>
hf-scroll-to
- Description: Specifies the element to which the page should scroll after a form submission.
- Usage:
- Add
hf-scroll-to
attribute to a form or submit button. - The value is a query selector targeting the element to scroll to.
- Add
<form hf-scroll-to="#result-section">
<!-- Form content -->
</form>
<button type="submit" hf-scroll-to=".result-section">Submit</button>
hf-scroll-skip
- Description: Skips scrolling entirely after a form submission.
- Usage:
- Add hf-scroll-skip attribute to the body element.
<body hf-scroll-skip>
<!-- Page content -->
</body>
hf-focus-skip
- Description: Skips focusing on elements after a form submission.
- Usage:
- Add
hf-focus-skip
attribute to form elements.
- Add
<form hf-focus-skip>
<!-- Form content -->
</form>
Eventing
hf:script-loaded
- Description: An event triggered after a script is successfully loaded.
- Usage:
- Subscribe to the
hf:script-loaded
event.
- Subscribe to the
doc.addEventListener("hf:script-loaded", e => {
// Handle script-loaded event
});
hf:request-before
,hf:request-after
,hf:json
,hf:swap
,hf:response-error
,hf:completed
- Description: Events triggered at different stages of the form submission process.
- Usage:
- Subscribe to these events for customization.
doc.addEventListener("hf:json", e => {
// Handle JSON response event
});
doc.addEventListener("hf:swap", e => {
// Handle content swap event
});
// ... and so on
Headers Sent to the Server
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.
Headers Sent to the Client
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.
hf-events
- Description: A custom header included in the server's response to specify events to be triggered on the client side.
- Format: JSON format containing event names as keys and corresponding event details as values.
Example:
hf-events: {"eventName1": {"detail1": "value1"}, "eventName2": {"detail2": "value2"}}
hf-reset
This will reset the submitting form.
Special response status
When a response is given outside of a 200 response a special handler will be treated for that response.
200 OK
- Description: Indicates a successful response.
- Handling: The library processes the response based on its content
type.
- If the content type is JSON (application/json), it triggers the
hf:json
event with the parsed JSON data. - If the content type is HTML (text/html), it triggers the
hf:swap
event with the received HTML content. - For other content types, the library does not perform additional handling.
- If the content type is JSON (application/json), it triggers the
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.
- Redirected
- Description: This will redirect the page to the specified response URL.
Version
0.7.*
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.
0.7.0
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.
0.6.0
Add ability to handle scripts returned in the HTML snippets.
0.5.0
Improved scrolling experience. Made it more like mpa-enhancer.
0.4.0
Add ability to scroll target a location on a page after swapping in new HTML.
0.3.0
Basically a rewrite.
- Improved scrolling.
- Use
hf-target
instead oftarget
. - Added more
hf-swap
types similar toHTMX
which works withinsertAdjacentHTML
. - Use
submitter
instead ofactiveElement
to determine override of form values. - 204 response is now ignored
0.20
- 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.
0.10
Introduced event for return status of 205 (Reset Content).
0.8
Fixed bug when a button which created the event doesn't exist.
0.7
Added more events and made events cancelable.
Added events: hf:completed
and hf:redirected
.
0.6
Added auto scroll for when appending above the input.
0.51
Bug fix - preventDefault()
wasn't called.
Bug fix - For http status of 204 or 400 don't print content type error message.
0.5
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.
0.4
Added ability to submit the form directly through htmf
. Removed the ability of
click
to submit the form through the button click.
0.3
Prevent double submits. Added ability to send events from JSON
in a header.
Added ability to delete elements with empty string.
0.2
Default to innerHTML
swap type. Determine target from the form itself.
0.1
Removed hf-hidden
attribute as this is redundant - use the noscript
html tag
instead.