npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

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

  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. Script Execution:
    • Handles script execution within the received HTML content to ensure proper functionality.
  5. Scroll Management:
    • Manages scroll positions before and after form submissions to provide a seamless user experience.
  6. 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.

  1. 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>
  1. 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>
  1. 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.
<form hf-swap="innerHTML">
  <!-- Form content -->
</form>

<button type="submit" hf-swap="append">Submit</button>
  1. 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.
<form hf-select=".select-container,#other-item">
  <!-- Form content -->
</form>

<button type="submit" hf-select=".select-container,#other-item">Submit</button>
  1. hf-scroll-ignore
  • Description: Prevents automatic scrolling after a form submission.
  • Usage:
    • Add hf-scroll-ignore attribute to a form or submit button.
<form hf-scroll-ignore>
  <!-- Form content -->
</form>

<button type="submit" hf-scroll-ignore>Submit</button>
  1. 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.
<form hf-scroll-to="#result-section">
  <!-- Form content -->
</form>

<button type="submit" hf-scroll-to=".result-section">Submit</button>
  1. 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>
  1. hf-focus-skip
  • Description: Skips focusing on elements after a form submission.
  • Usage:
    • Add hf-focus-skip attribute to form elements.
<form hf-focus-skip>
  <!-- Form content -->
</form>

Eventing

  1. hf:script-loaded
  • Description: An event triggered after a script is successfully loaded.
  • Usage:
    • Subscribe to the hf:script-loaded event.
doc.addEventListener("hf:script-loaded", e => {
  // Handle script-loaded event
});
  1. 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.

  1. 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.
  2. 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.
  3. 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 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

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.