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 `
` 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) => { 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.