From 4455d9c8273f85f071928565230d96d1a231a831 Mon Sep 17 00:00:00 2001
From: TheoryOfNekomata <allan.crisostomo@outlook.com>
Date: Sun, 16 May 2021 13:05:37 +0800
Subject: [PATCH] Add information in README

This adds the motivation on using the library, with the pitfalls on
using other form libraries.
---
 README.md | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 93b4746..9cc0c05 100644
--- a/README.md
+++ b/README.md
@@ -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.