Package Exports

@analytics/form-utils
@analytics/form-utils/dist/analytics-util-forms.js
@analytics/form-utils/dist/analytics-util-forms.module.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 (@analytics/form-utils) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Form Utilities

A tiny form utility library for dealing with HTML form data in 2.41kb.

Exposes onSubmit, onChange, listen, submitForm, getFormData, & getInputData functions.

This library will work with analytics or as a standalone import in your code.

See live demo.

How to install

Install @analytics/form-utils from npm.

npm install @analytics/form-utils

API

Below is the api for @analytics/form-utils. You can import only what you need & the rest will be tree-shaken out of your bundle.

`onSubmit`

Listen to form submissions & do stuff with inputs.

This will incept form submissions & fire a custom callback before submitting the form normally

import { onSubmit } from '@analytics/form-utils'

// Add to single form
const formOne = document.querySelector('form[id=one]')
onSubmit(formOne, (event, data) => {
  console.log('form', event.target)
  console.log('form data', JSON.stringify(data, null, 2))
})

// Add to single form with options
onSubmit('form[id=two]', {
  /* Turn on debug to disable submissions and see values */
  debug: true,
  /* Turn off sensitive values filter */
  disableFilter: false,
  /* Exclude field by name or regex pattern of name attribute */
  excludeFields: [
    /private/,
    'shhhh'
  ],
  /* Custom filter function. Return false to exclude data */
  filter: (fieldName, value) => {
    if (fieldName === 'hello') {
      return false
    }
    // credit card number
    if (value.match(/^\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}$/)) {
      return false
    }
    return true
  }
}, (event, data) => {
  console.log('form', event.target)
  console.log('form data', JSON.stringify(data, null, 2))
})

// Remove onSubmit listener
const cleanUpFunction = onSubmit('form[id=three]', (event, data) => {
  console.log('form', event.target)
  console.log('form data', JSON.stringify(data, null, 2))
})
cleanUpFunction() // <-- call function to clean up listener


// Listen to all forms on page
onSubmit('all', (event, data, meta) => {
  console.log('form', event.target)
  console.log('form data', JSON.stringify(data, null, 2))
})

`onChange`

Listen to form changes & do stuff with inputs.

import { onChange } from '@analytics/form-utils'

// Add to single form with no options
const formOne = document.querySelector('form[id=one]')
onChange(formOne, (event, data) => {
  console.log('form', event.target)
  console.log('form data', JSON.stringify(data, null, 2))
})

// Add to single form with options
onChange('form[id=two]', {
  /* Turn on debug to disable submissions and see values */
  debug: true,
  /* Turn off sensitive values filter */
  disableFilter: false,
  /* Exclude field by name or regex pattern of name attribute */
  excludeFields: [
    /private/,
    'shhhh'
  ],
  /* Custom filter function. Return false to exclude data */
  filter: (fieldName, value) => {
    if (fieldName === 'hello') {
      return false
    }
    // credit card number
    if (value.match(/^\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}$/)) {
      return false
    }
    return true
  }
}, (event, data) => {
  console.log('form', event.target)
  console.log('change data', JSON.stringify(data, null, 2))
})

// Remove onChange listener
const cleanUpFunction = onChange('form[id=three]', (event, data) => {
  console.log('form', event.target)
  console.log('change data', JSON.stringify(data, null, 2))
})
cleanUpFunction() // <-- call function to clean up listener

// Listen to all forms on page
onChange('all', (event, data) => {
  console.log('form', event.target)
  console.log('form data', JSON.stringify(data, null, 2))
})

`listen`

Listen will attach onChange & onSubmit listeners to forms

import { listen } from '@analytics/form-utils'

// Add to single form with no options
const formOne = document.querySelector('form[id=one]')
listen(formOne, (event, data, type) => {
  console.log('listen type', type)
  console.log('listen form', event.target)
  console.log('listen form data', JSON.stringify(data, null, 2))
})

// Listen to all forms with options
listen({
  /* Turn on debug to disable submissions and see values */
  debug: true,
  /* Turn off sensitive values filter */
  disableFilter: false,
  /* Custom functionality handler for onSubmit */
  onSubmit: (event, data) => {
    console.log('submit form', event.target)
    console.log('submit data', JSON.stringify(data, null, 2))
  },
  onChange: (event, data) => {
    console.log('change form', event.target)
    console.log('change data', JSON.stringify(data, null, 2))
  },
  /* // Include only specific forms. This negates 'all'
  includeForms: [
    'form[id=content-form]',
    window.document.forms[1]
  ],
  */
  /* // Exclude forms by selectors or node.
  excludeForms: [
    'form[name=two]',
    window.document.forms[2]
  ],
  */
  /* Exclude field by name or regex pattern of name attribute */
  excludeFields: [
    /private/,
    'shhhh'
  ],
  /**/
  /* Custom filter function */
  filter: (fieldName, value) => {
    if (fieldName === 'hello') {
      return false
    }
    // credit card number
    if (value.match(/^\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}$/)) {
      return false
    }
    return true
  }
  /**/
})

`submitForm`

Submit form via JS

import { listen } from '@analytics/form-utils'

`getFormData`

Get values from form inputs

import { getFormData } from '@analytics/form-utils'

const form = document.querySelector('form[id=one]')
const data = getFormData(form)
console.log('data', JSON.stringify(data, null, 2))

`getInputData`

Get value from single form input

import { getInputData } from '@analytics/form-utils'

const form = document.querySelector('form[id=one]')
const inputName = 'email'
const inputData = getInputData(form, inputName)
console.log('inputData', JSON.stringify(inputData, null, 2))

`filterData`

Filter out & omit sensitive fields

import { getFormData, getInputData, filterData } from '@analytics/form-utils'

const form = document.querySelector('form[id=one]')
const inputName = 'email'
const rawData = getFormData(form, inputName)
console.log('rawData', JSON.stringify(rawData, null, 2))

const redactedData = filterData(rawData, {
  /* Exclude field by name or regex pattern of name attribute */
  excludeFields: [
    /regex/,
    'name-attribute'
  ],
  /* Custom filter function */
  filter: (fieldName, value) => {
    if (fieldName === 'hello') {
      return false
    }
    // credit card number
    if (value.match(/^\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}$/)) {
      return false
    }
    return true
  }
})
console.log('redactedData', JSON.stringify(redactedData, null, 2))