Browse Source

Add information in README

This adds the motivation on using the library, with the pitfalls on
using other form libraries.
master
TheoryOfNekomata 3 years ago
parent
commit
4455d9c827
1 changed files with 25 additions and 4 deletions
  1. +25
    -4
      README.md

+ 25
- 4
README.md View File

@@ -4,7 +4,28 @@ Extract form values through the DOM.

## Motivation

There are many ways to lay out forms.
Forms are used to package related data, typically sent to an external location or processed internally. In the browser,
the default behavior of submitting form data is not always preferred, as this is done through loading a document,
typically the same document, as soon as the form is submitted. In addition, [applications have limited control over how
the data are formatted on submission](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#dom-fs-enctype)
with this approach. This is why the new way of sending form data is done through AJAX/fetch requests, wherein the data
are serialized into formats like JSON. To turn form data into a specific format requires access to the elements holding
the values to each field in the form.

Some libraries for extracting form values query field elements in the DOM, which is inefficient since they need to
traverse the DOM tree in some way, using methods such as `document.getElementsByTagName()` and
`document.querySelector()`.

Upon retrieving the field values somehow, some libraries attempt to duplicate the values of the fields as they change,
for instance by attaching event listeners and storing the new values into some internal object or map, which can be
retrieved by some other exposed function.

With `formxtr`, there is no need to traverse the DOM for individual fields to get their values. Provided the fields are
associated to the form (either as a descendant of the `<form>` element or [associated through the `form=""`
attribute](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#attr-fae-form)) and has a valid
`name`, the values of these fields can be easily extracted, using the `form.elements` attribute built-in to the DOM and
used for getting its currently associated fields. With this, only the reference to the form is needed. The current state
of the field elements are already stored in the DOM, waiting to be accessed.

## Installation

@@ -42,7 +63,7 @@ const form: HTMLFormElement = document.getElementById('form');
// individual submitters can be considered
const submitter = form.querySelector('[type="submit"][name="type"][value="client"]');

const values = getFormValues(form, submitter);
const values = getFormValues(form, { submitter });

const processResult = (result: Record<string, unknown>) => {
throw new Error('Not yet implemented.');
@@ -53,7 +74,7 @@ form.addEventListener('submit', async e => {
const { target: form, submitter } = e;
e.preventDefault();

const values = getFormValues(form, submitter);
const values = getFormValues(form, { submitter });

// Get the form values and send as request to some API
const response = await fetch(
@@ -77,4 +98,4 @@ form.addEventListener('submit', async e => {

## Tests

The library has been tested on JSDOM through Jest, and the real DOM using Cypress.
The library has been tested on the static DOM using JSDOM and Jest, and the real dynamic DOM using Cypress.

Loading…
Cancel
Save