Package Exports

@locustjs/forms
@locustjs/forms/dist/index.js
@locustjs/forms/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@locustjs/forms) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

About

This library provides utility functions to interact with forms and form elements in a web page.

🔗 Test & Demo

Check out the live demo here

Install

npm i @locustjs/forms

Usage

CommonJs

var someFn = require('@locustjs/forms').someFn;

ES6

import { someFn } from '@locustjs/forms'

Current Version

3.0.1

Main Usage: Serialize a form into JSON

<form class="my-form">
  <div>
    <label>
      <span>First Name</span>
      <input type="text" name="firstname" />
    </label>
  </div>
  <div>
    <label>
      <span>Last Name</span>
      <input type="text" name="lastname" />
    </label>
  </div>
  <div>
    <label>
      <span>Sex</span>
      <input type="radio" name="sex" value="male" /> Male
      <input type="radio" name="sex" value="female" /> Female
    </label>
  </div>
  <div>
    <label>
      <span>Age group</span>
      <select name="age-group">
        <option value="0">Not specified</option>
        <option value="1">6 and Below 6</option>
        <option value="2">7 to 12</option>
        <option value="3">13 to 19</option>
        <option value="4">20 to 45</option>
        <option value="5">46 and Over 46</option>
      </select>
    </label>
  </div>
  <div>
    <label>
      <span>I Agree</span>
      <input type="checkbox" name="agreement" />
    </label>
  </div>
</form>

Suppose the form contains the following data:

First Name: Johen
Last Name: Doe
Sex: Male
Age Group: 20 to 45

To get the form as a javascript object we can use the following code:

import { toJson } from '@locustjs/forms';

const data = toJson('.my-form');

console.log(data);
/*
  {
    "firstname": "John",
    "lastname": "Doe",
    "sex": "male",
    "age-group": "4",
    "agreement": []
  }
*/

Utility functions

Form Element Iteration

function	description
`formEachElement(selector, callback, excludes)`	iterates over one or more forms whose selector are specified in `selector` argument and calls the `callback` argument on each form element it finds. The callback function has a signature as `callback({ form, element, index, formIndex })`. Using the `excludes` parameter, we can exclude some form elements, so that they are not iterated over. This is explained in `Element Exclusion` section.
`formEach(selector, callback, excludes)`	This function carries out the same job as `formEachElement`, except that it ignores `buttons` and `fieldsets` by default, whereas `formEachElement` iterates `buttons` and `fieldsets` as well. If we specify an `excludes` argument for `formEach` it behaves the same as `formEachElement`

By default, selector is form, resulting in iterating over all elements of all <form> tags in the page.

More examples:

formEach(callback);  // iterating all elements of all forms
formEach('#my-form', callback) // iterates over elements in a form whose id is 'my-form'
formEach('#frm1, #frm2', callback) // iterates over elements in a form whose id is 'frm1' and 'frm2'
formEach('.my-form', callback) // iterates over elements in all forms whose class is '.my-form'
formEach('.container .my-form', callback) // iterates over elements in a form enclosed in .container and whose class is 'my-form'

When formEachElement or formEach find more than one form selector, they return an array. Each item in the array is an object that relates to the elements of each form read.

Form Element Manipulation

function	description
`disable(selector, excludes, mode = true)`	changes disable mode of a form and its elements based on `mode` value.
`enable(selector, excludes, mode = true)`	changes disable mode of a form and its elements based on `mode` value.
`reset(selector)`	resets a form and its elements.
`clear(selector, excludes, includeHiddenFields = false)`	clears a form and its elements. Its difference with `reset()` method is that it can selectively clear fields, i.e. ignoring a few fields specified by `excludes` parameter. Moreover, it does not reset hidden input fields by default. In order to also clear hidden fields, the third parameter should be used with `true` argument.
`readOnly(selector, excludes, mode)`	changes readonly mode of a form and its elements, based on `mode` value.
`getValue(form, elementName)`	returns value of a form element based on its name. The `form` parameter could be a form node in DOM or a selector.
`setValue(form, elementName, value)`	sets a value on a form element based on its name.

disable, enable and readOnly methods have a simpler overload as below:

disable(selector, mode = true)
enable(selector, mode = true)
readOnly(selector, mode = true)

So, the following examples are all valid:

disable();  // disables all forms
disable('#my-form') // disables the form whose id is 'my-form'
disable('.my-form') // disables all forms whose class is '.my-form'
disable('.my-form', '.ignore') // disables elements in all forms whose class is '.my-form' excluding elements with '.ignore' class
disable('.my-form', false); // set disable mode of all elements in the form to 'false'

Form Serialization/Deserialization

function	description
`toJson(selector, excludes, expandNames)`	serializes a form into json.
`fromJson(selector, obj, excludes, flattenProps)`	fills a form based on a json object.
`toArray(selector, excludes)`	serializes form element values into array.
`fromArray(selector, arr, excludes)`	fills a form based on an array of values.

Other

function	description
`isEditable(element)`	checks whether given element is a data entry element (user can potentially enter its value) or not. Editable elements are `textboxes`, `radio buttons`, `checkboxes`, `textareas` and `selects`.
`post(url, data)`	creates an arbitrary form, fills it with data and posts the form to the specified target url in HTTP POST method.

Form class

There is a helper Form class with static utility methods that eases working with forms. So, there's no need to import functions separately. We can only import Form and use its methods.

import { Form } from '@locustjs/forms';

var x = Form.toJson('#my-form');

console.log(x);

Form.clear('#my-form');

Form.fromJson('#my-form');

The Form class also provides instance methods making it more convenient when working with a form, removing the need to refer to the form over and over again.

each()
eachElement()
enable()
disable()
readOnly()
clear()
reset()
fromJson()
toJson()
fromArray()
toArray()
getValue()
setValue()

Example:

const f = new Form('#my-form');

f.each((frm, el) => console.log(el));
f.enable();
f.disable();
f.readOnly();
f.readOnly(false);
f.reset();

const x = f.toJson();

console.log(x);

f.clear();
f.fromJson(x);

const arr = f.toArray();

console.log(arr);

f.clear();

f.fromArray(arr);

console.log(f.getValue('firstname'));
console.log(f.getValue('age-group'));

f.setValue('firstname', 'John');
f.setValue('age-group', 4);

Element Exclusion

Some form utility functions receive an excludes parameter that is used to exclude form elements during their operation.

The excludes could be a selector or a custom function. In simplest form, we can apply a custom css class such as .ignore to some of our form elements and then specify this class for the excludes parameter in functions such as toJson, readOnly, disable, etc.

Example:

import { toJson, readOnly } from "@locustjs/forms";

const data = toJson('.my-form', '.ignore'); // ignore elements with .ignore css class

readOnly('.my-form', '.ignore');  // readonly all elements except those with .ignore css class

When specifying a custom function for the excludes parameter, the function should follow the following signature:

fnExclude({ form, element, index, formIndex }): bool

The function should return true or false in order to specify the element should be ignored or not.

Expanding names

The toJson function has a third parameter named exapndNames. If we use dot character in the name of our form elements and specify true for expandNames in toJson function, it will turn such form elements into object, resulting in a nested object being returned.

Example:

<form class="my-form">
  <fieldset>
    <legend>Account Info</legend>
    <label>
      <span>User Name</span>
      <input type="text" name="user.name" />
    </label>
    <label>
      <span>Password</span>
      <input type="password" name="user.pass" />
    </label>
  </fieldset>

  <fieldset>
    <legend>Personal Info</legend>
    <label>
      <span>First Name</span>
      <input type="text" name="person.firstName" />
    </label>
    <label>
      <span>Last Name</span>
      <input type="text" name="person.lastName" />
    </label>
  </fieldset>

  
</form>

import { toJson } from '@locustjs/forms';

const data = toJson('.my-form', '', true);

console.log(data);
/*
  {
    user: {
      "name": "user1",
      "pass": "1234",
    },
    person: {
      "firstName": "John",
      "lastName": "Doe",
    }
  }
*/