Simple Form Manager V2

Simple Form Manager V2 (SFMv2) is a javascript class you can use to manage your html forms. It can be used with Angular, React, Vue or any other javascript library for framework. Good form management requires an an tremendous amount boilerplate and redundant code to manage state, and validate user input. Most solutions are complicated, highly opinionated and tend to be framework.

SFMv2 can be usued with any one of the dozens of UI components available to you. Simple Form Manager does not takeover your forms or shroud your forms in obscurity so you do not understand what is happening to your data, SFMv2 is lightweight, simple and is easy to reason about. SFMv2 internal objects are fully exposed to you, the developer, so you can see what is going with your data.

SFMv2 is a complete re-write of the orginial Simple Form Manager and has a completely different interface. Unlike the original version of Simple Form Manager, this version does not require you to put a wrapper around your components for it to work. With Simple Form Manager V2 you just wire your components it, and it works!

SFM and SFMv2 are inspired by Vuelidate, the excellent form validation system written for Vue.

Installation

npm install simple-form-manager-v2

or

yarn add simple-form-manager-v2

Simple Form Manager V2 Interface Summary

Properties

fields: object,

fieldScheme: readonly object

form: readonly object,

data: readonly object,

all: readonly object,

formSubmittable: readonly boolean

running: readonly boolean

Methods

start(tickSpeed: number): void

stop(): void

toggleValidationNode(fieldName: string, validator: any, value: any: void

setFieldValidationStatus: (fieldName: string, validator: string, value: boolean) => void

setFieldStatus: (fieldName: string, isValid: boolean, errorMsg: string) => void

restoreForm(): void

resetForm(): void

resetField(fieldName: string): void

showFieldError(fieldName: string): boolean

setValue(fieldName: string, value: any): void

setTouched(fieldName: string, value: boolean): void

setObjectValue(fieldName: string, value: object): void

setValues(values: object): void

onBlur(fieldName: string): void - DEPRECATED

onUpdateValue(fieldName: string, value: any): void - DEPRECATED

onUpdateObjectValue(fieldName: string, value: any): void - DEPRECATED

A full description of these properties and methods can be found futher down in this document.

Usage (Getting started)

Instantiate Simple Form Manager V2

1import FM from 'simple-form-manager-v2'
2import myFormSchema from './src/form-schemas/myFormSchema.js'
3const fm = new FM(myFieldSchema)

But what is myFormSchema in the code sample above you ask. It is a javascript object describing your form and the validation rules for each field. See below for how to structure your form schema and how to write a validation function.

Usage (A simple example)

Simple Form Manager V2 will work with any framework. The example I use here is for a VueJs use case.

1// userFormSchema.js
2import { required } from 'vuelidate/lib/validators'
3
4export default {
5  userName: {
6    required: {
7      validator: required,
8      errorMessage: 'User Name is required'
9    }
10  }
11}

1// userForm.vue
2<template>
3  <form @submit.prevent="onSubmit">
4    <!-- 
5      We will show field errors here...
6      Only show if the field has been 'touched', i.e. received and lost focus
7    -->
8    <div v-if="(!fm.fields.userName.valid && fm.fields.userName.touched)">
9      <div>{{ fm.fields.userName.errorMessage }}</div>
10    </div>
11    <!-- 
12      Each field in your form is set-up as follows
13    -->        
14    <input
15      @blur="fm.onBlur('userName')"
16      v-model="fm.fields.userName.value" 
17      type="text" 
18    />
19    <!-- 
20      Note: We can disable the submit button if there is an error
21      in one or more of the fields or if the form values are unchanged
22    -->     
23    <input 
24      type="submit" 
25      value="Submit"
26      :disabled="!(fm.form.dirty && fm.form.valid)"
27    >
28  </form>
29</template>
30<script>
31import { defineComponent, onMounted, onUnmounted, ref } from 'vue';
32import FM from './assets/CFormManagerV2'
33import Schema from './assets/userFormSchema'
34
35export default defineComponent({
36  name: 'user-form',
37  setup() {
38    // Instantiate Form Manager
39    // We are using Vue3 so this is done inside a ref()
40    const fm = ref(new FM(Schema))
41
42    // When page is mounted set-up the form
43    onMounted(() => {
44      // Initial value of userName field
45      fm.value.fields.userName.value = 'Joe Blow'
46      // CRITICAL - start form manager AFTER field 
47      // values have been initialized
48      fm.value.start()
49    })
50    
51    // CRITICAL - to prevent memory leaks, 
52    // stop form manager when page is unMounted
53    onUnmounted(() => {
54      fm.value.stop()
55    })
56
57    const onSubmit = () => {
58      // Notice a nice package of your form data is available  
59      // fm.data
60      console.log('Submit: ', fm.value.data)
61      fm.value.resetForm()      
62    }
63
64    return {      
65      fm, // We must make fm available to the form
66      onSubmit
67    }
68  }
69});
70</script>

Form Schema Explained

In the Userage sction above, we had a form schema name myFormSchema. Here is a simple example of a form schema.

1// I am getting my validator functions here from npm package 
2// vuelidate. You can write your own or find others on npm.
3import { required, email } from 'vuelidate/lib/validators' 
4
5export default {
6  // the form descibed in this file had three fields:
7  //   - userId
8  //   - userName
9  //   - email
10  userId: {}, // no validation rules, in the interface the id is likely read-only
11  username: {
12    required: { // validation rule for username
13      validator: required, 
14      errorMessage: 'Username is required'
15    }  
16  },
17  // email is the other field variable name in your form
18  email: {
19    required: { 
20      validator: required, // Must me a function, see below for details
21      errorMessage: 'Email is required' // Must be a string
22    },
23    validEmail: { // validation rule #2 for email
24      validator: email,
25      errorMessage: 'Email is not a proper email format'      
26    }
27    validEmail: { // validation rule #2 for email
28      validator: maxLength(100),
29      errorMessage: 'Email may not exceed 100 characters'      
30    }    
31  }
32}

Notice that each of the fields usermame and email in the form schema above has node(s) below them - these are validation rule nodes. You may have as many validation rules (or none at all) for each field as you like and you may give them any name that you like.

The only requirement for each validation rule is that each validation rule node must have two sub-nodes: validator & errorMessage. The validator node must be assigned a function, this fn is used to validated the value assigned to field. The errorMessage node is assigned a string that your form can you to display to the user is the validation rule fails.

That's it! To summarize: a form schema consists of the follow structure:

field-node(s)
  validation-rule-node(s)
    validator: function
    errorMessage: string

Validation Functions Explained

A validator function takes one of the following two forms:

1// Validation rule with no parameter (i.e. required)
2fn(valueToBeValidated) => { return boolean }
3
4// Validation rule with one, or more parameters (i.e. maxLength(100))
5fn(valueToBeValidated => fn2 => (parameters...) => { return boolean })

You may use write your own validaiton function or you can import 3rd-party validators from npm. An excellent libray I use comes from vuelidate.

Simple Form Manager V2 Methods

constructor(formSchema): void

Return value: None

Parameters:

formSchema (javascript object): See a detailed description above in the section entitled Form Schema Explained

Description: Instantiates Simple Form Manager V2 object

Usage

1import FM from 'simple-form-manager-v2'
2import myFormSchema from './src/form-schemas/loginFormSchema.js'
3const fm = new FM(loginFormSchema.js)

start(tickSpeed): void

Return value: None

Parameters:

tickSpeed (integer; optional, default is 25): Frequncy, in milliseconds, with which form is scanned for changes. This will determine how responsive the form is to user input.

Description: Starts Form Manager V2 into tracking user input in the form. Before starting Form Manager, field values should first be initialized. On the first tick after start, the orginalValue (see field proprty below) is set to initial value of the field.

Usage

1 // starts tracking user input with a frequency of 1 second
2fm.start(1000)

stop(): void

Return value: None

Parameters: None

Description: Stops Simple Field Manager V2 from tracking user input. Internally User Manager. It is highly recommented that you issue a stop on field manager after each start to avoid memory leaks.

Usage

1// starts tracking user input with a frequency of 1 second
2fm.stop() 

setValue(fieldName, value): void

Return value: None

Parameters:

fieldName (string): The name of the field provided in the Form Schema

value (any): The new value to be assigned to 'value' property of the field referenced by fieldName

Description: This a helper function to make it easier to set the value property for the field provided. This method is best used by wiring it to the onChange event for that field in question.

Usage

1// change the value of the 'lastName' field to and empty string (i.e. '')
2fm.setTouched('lastName', '')

setValues(values): void

Return value: None

Parameters:

values (object): An object containing key-value pairs with the keys matching the field names provided in the Form Schema

Description: This a helper function to make it easier to set the values for the fields provided in the Form Schema. If a field name in the object does not match the field name in the Field Schema, it is ignored.

Usage

1let person = {
2  FirstName: 'Mary',
3  MiddleInitial: 'L',
4  LastName: 'Henderson'
5}
6// sets the values of the fields: FirstName, MiddleInitial & LastName 
7fm.setValues(person)

setTouched(fieldName, value): void

Return value: None

Parameters:

fieldName (string): The name of the field provided in the Form Schema

value (boolean): Optional - The new value to be assigned to 'touched' property of the field referenced by fieldName. If a value is not provided the default value is true

Description: This a helper function to make it easier to set the touched value for the field provided. This method is best used by wiring it to the onBlur event for that field in question.

Usage

1// sets the touched value for the password field to true
2fm.setValue('password') 

setObjectValue(fieldName, value): void

Return value: None

Parameters:

fieldName (string): The name of the field provided in the Form Schema

value (object): The new value to be assigned to the 'objectValue' property field referenced by fieldName. The object value property is helpful for holding an object returned by dropdown

Description: This a helper function to make it easier to set the value property for the field provided. This functions is best used by wiring it to the onChange event for that field in question.

Usage

1let country = { 
2  countryCode: 'CH', 
3  countryName: 'Switzerland',
4  capital: 'Bern'
5}
6
7// change the objectValue of the 'countryCode' field to country
8fm.setUpdateModelValue('countryCode', country)

onBlur(fieldName): void

DEPRECATED - replaced by setTouched

Return value: None

Parameters:

fieldName (string): The name of the field provided in the Form Schema

Description: This a helper function to make it easier to set the touched value for the field provided to true. This method is best used by wiring it to the onBlur event for that field in question.

Usage

1// sets the touched value for the password field to true
2fm.onBlur('password') 

onUpdateValue(fieldName, value): void

DEPRECATED - replaced by setValue

Return value: None

Parameters:

fieldName (string): The name of the field provided in the Form Schema

value (any): The new value to be assigned to 'value' property of the field referenced by fieldName

Description: This a helper function to make it easier to set the value property for the field provided. This method is best used by wiring it to the onChange event for that field in question.

Usage

1// change the value of the 'lastName' field to and empty string (i.e. '')
2fm.onUpdateValue('lastName', '')

setFieldValidationStatus: (fieldName: string, validator: string, value: boolean) => void

Return value: None

Parameters:

fieldName (string): The name of the field provided in the Form Schema

validator (string): The name of the validator provided in the Form Schema

value (boolean): The new value to be assigned to the 'valid' status of the validator

Description: There are times when the validation criteria for a field requires more information than is contained within the field itself. An example of this is a Password form with a Password and a Password confirmation field. This method allows you to calculate the validation status of a field and set the validation value.

Usage

1const formScheme = {
2  password: {
3    required: {
4      validator: required,
5      message: 'Password is required'
6    }
7  },
8  confirmationPassword: {
9    matchesPassword: {
10      validator: null, // No validator, this is handled outside of Form Manager
11      message: 'Password and Confirmation Password do not match'
12    }
13  }  
14}
15
16// change the 'valid' status of the 'confirmationPassword' to false
17fm.setFieldStatus('confirmationPassword', 'matchesPassword', false)

setFieldStatus: (fieldName: string, isValid: boolean, errorMsg: string) => void

Return value: None

Parameters:

fieldName (string): The name of the field provided in the Form Schema

isValid (boolean): The validation status of the field

errorMsg (string): The error message to be displayed if the field is not valid

Description: Sets the validation status of a field to true or false. If the field is not valid, the error message is also set.

Usage

1// change the 'valid' status of the 'confirmationPassword' to false
2fm.setFieldStatus('confirmationPassword', false, 'Password and Confirmation Password do not match')

onUpdateObjectValue(fieldName, value): void

DEPRECATED - replaced by setUpdateObjectValue

Return value: None

Parameters:

fieldName (string): The name of the field provided in the Form Schema

value (any): The new value to be assigned to the 'objectValue' property field referenced by fieldName. The object value property is helpful for holding an object returned by dropdown

Description: This a helper function to make it easier to set the value property for the field provided. This functions is best used by wiring it to the onChange event for that field in question.

Usage

1// change the value of the 'lastName' field to and empty string (i.e. '')
2fm.onUpdateModelValue('countryCode', { 
3  countryCode: 'CH', 
4  countryName: 'Switzerland',
5  capital: 'Bern'
6})

toggleValidationNode(fieldName, validationRule, value): void

Return value: None

Parameters:

fieldName (string): A string representing the name of the field provided in the Form Schema

validationRule (string): A string representing the name of the validation rule provided in the Form Schema

Description:

Use this function to true on and off validation rules established in the Form Schema. If value is not provided, the rule is toggled, otherwise the rule is set to the value provided.

Usage

1// sets the 'required' validation rule for the 'socialSecurityNumber'
2// field to false
3fm.toggleValidationNode('socialSecurityNumber', 'required', false) 

showFieldError(fieldName): boolean

Return value: boolean

Parameters:

fieldName: A string representing the name of the field provided in the Form Schema

Description: This a helper function which return true if the field is both invalid and has been touched (i.e. has recieved and lost focus).

Usage

1// return true if the 'password' field is both invalid and touched
2fm.showFieldError('password') 

resetForm(): void

Return value: none

Parameters: none

Description: Restores the form and the field attributes for the fields, while returing the field values to their orginial values.

Usage

1//
2// Values before resetting the form
3//
4
5// Field values
6console.log(fm.fields)
7// returns
8{
9  "userName": {
10    "dirty": true,
11    "touched": true,
12    "value": "janejohnson",
13    "originalValue": "sallysmith",
14    "valid": true,
15    "errorMessage": ""
16  },
17  "phoneNumber": {
18    "dirty": true,
19    "touched": true,
20    "value": "999QQQQQQQ",
21    "originalValue": "888-999-1234",
22    "valid": false,
23    "errorMessage": "Not a valid phone number"
24  }  
25}
26
27// Form values
28console.log(fm.form)
29// returns
30{
31  "dirty": true,
32  "valid": false,
33  "touched": true
34}
35
36//
37// Values after resetting the form
38//
39fm.resetField('userName')
40console.log(fm.fields.userName)
41// Field values
42console.log(fm.fields)
43// returns
44{
45  "userName": {
46    "dirty": false,
47    "touched": false,
48    "value": "sallysmith",
49    "originalValue": "sallysmith",
50    "valid": true,
51    "errorMessage": ""
52  },
53  "phoneNumber": {
54    "dirty": false,
55    "touched": false,
56    "value": "888-999-1234",
57    "originalValue": "888-999-1234",
58    "valid": false,
59    "errorMessage": "Not a valid phone number"
60  }  
61}
62
63// Form values
64console.log(fm.form)
65// returns
66{
67  "dirty": false,
68  "valid": false,
69  "touched": false
70}

resetForm(): void

Return value: none

Parameters: none

Description: Resets the form and the field attributes for the fields, while preserving the field values.

Usage

1//
2// Values before resetting the form
3//
4
5// Field values
6console.log(fm.fields)
7// returns
8{
9  "userName": {
10    "dirty": true,
11    "touched": true,
12    "value": "janejohnson",
13    "originalValue": "sallysmith",
14    "valid": true,
15    "errorMessage": ""
16  },
17  "phoneNumber": {
18    "dirty": true,
19    "touched": true,
20    "value": "999QQQQQQQ",
21    "originalValue": "888-999-1234",
22    "valid": false,
23    "errorMessage": "Not a valid phone number"
24  }  
25}
26
27// Form values
28console.log(fm.form)
29// returns
30{
31  "dirty": true,
32  "valid": false,
33  "touched": true
34}
35
36//
37// Values after resetting the form
38//
39fm.resetField('userName')
40console.log(fm.fields.userName)
41// Field values
42console.log(fm.fields)
43// returns
44{
45  "userName": {
46    "dirty": false,
47    "touched": false,
48    "value": "janejohnson",
49    "originalValue": "janejohnson",
50    "valid": true,
51    "errorMessage": ""
52  },
53  "phoneNumber": {
54    "dirty": false,
55    "touched": false,
56    "value": "999QQQQQQQ",
57    "originalValue": "999QQQQQQQ",
58    "valid": false,
59    "errorMessage": "Not a valid phone number"
60  }  
61}
62
63// Form values
64console.log(fm.form)
65// returns
66{
67  "dirty": false,
68  "valid": false,
69  "touched": false
70}

resetField(fieldName): void

Return value: none

Parameters:

fieldName: A string representing the name of the field provided in the Form Schema

Description: Resets the field atributes for the field provided in fieldName, while preserving the field value.

Usage

1console.log(fm.fields.userName)
2// returns
3{
4  "dirty": true,
5  "touched": true,
6  "value": "janejohnsonaaaaaaaaaaaaaaaaaaaaaa",
7  "originalValue": "",
8  "valid": false,
9  "errorMessage": "User Name exceeds 15 charcters"
10}
11
12fm.resetField('userName')
13console.log(fm.fields.userName)
14// returns
15{
16  "dirty": false,
17  "touched": false,
18  "value": "janejohnsonaaaaaaaaaaaaaaaaaaaaaa",
19  "originalValue": "janejohnsonaaaaaaaaaaaaaaaaaaaaaa",
20  "valid": false,
21  "errorMessage": "User Name exceeds 15 charcters"
22}

Simple Form Manager V2 Properties

running: boolean (readonly)

Description: This value is set by the methods start() and stop().

Usage

1fm.start()
2console.log(fm.running)
3// returns 
4true

fields: javascript object (read | write)

Description: A collection of javascript field objects, as determined by the Field Schema. For each field porvided by the Form Scheme, there are the following sub-properties:

• value: any
• dirty: boolean
• touched: boolean
• orginalValue: any
• valid: boolean
• errorMessage: string

Usage

1// Read Example
2console.log(fm.fields)
3// returns 
4{
5  "userName": {
6    "dirty": true,
7    "touched": true,
8    "value": "jdoe",
9    "originalValue": "",
10    "valid": true,
11    "errorMessage": ""
12  },
13  "password": {
14    "dirty": true,
15    "touched": true,
16    "value": "hello1",
17    "originalValue": "",
18    "valid": false,
19    "errorMessage": "Passwords must be at least 8 charcters and consist of at least 1 special charcter "
20  }
21}
22
23// Write Example
24fm.fields.userName.value = 'johnDoe'
25fm.fields.phoneNumber.value = '999-999-1212'
26fm.start()

1<!-- 
2Vue JS: Databinding to field object 'fm.fields.userName.value'
3-->
4<input
5  @blur="fm.onBlur('userName')"
6  v-model="fm.fields.userName.value" 
7  type="text" 
8/>
9
10<!-- 
11React JS: Databinding to field object 'fm.fields.userName.value'
12-->
13
14handleChange = (e) => {
15  /// ...handle update
16},
17handleBlur = (e) => {
18  /// ...handle update
19},
20render(){
21  return (
22    <input
23      value="{this.state.fm.fields.userName.value" 
24      onChange={this.handleChange}
25      onBlur={this.handleBlur}
26      type="text" 
27    />
28  )
29}

Though these properties are read/write, with the exception of orginalValue, value, Form Manager will overwrite your changes (if it is running) with the tickSpeed provided at start(). As such, you will only ever want to directly update value

form: javascript object (readonly)

Description: A javascript field object representing the status of the form. The properties of this form object are:

• dirty: boolean
• touched: boolean
• valid: boolean

Usage

1console.log(fm.form)
2///returns (example)
3{
4  "dirty": false,
5  "valid": true,
6  "touched": true
7}

formSubmittable: boolean (readonly)

Description: A helper property that it true if the form is both 'dirty' and 'valid', otherwise it is set to false

Usage:

1// ********************
2// **** Example #1 ****
3// ********************
4console.log(fm.form)
5// returns
6{
7  "dirty": false,
8  "valid": true,
9  "touched": true
10}
11console.log(fm.formSubmittable)
12 // returns
13 false
14
15// ********************
16// **** Example #2 ****
17// ********************
18console.log(fm.form)
19// returns
20{
21  "dirty": true,
22  "valid": true,
23  "touched": true
24}
25console.log(fm.formSubmittable)
26 // returns
27 true

fieldScheme: javascript object (readonly)

Description: A collection of javascript field objects as determined by the Field Schema that was provider in the constructor at instantiation.

Usage

1import FM from 'simple-form-manager-v2'
2import myFormSchema from './src/form-schemas/myFormSchema.js'
3const fm = new FM(myFieldSchema)
4console.log(fm.scheme)
5//returns
6{
7  "userName": {
8    "required": {
9      "errorMessage": "User Name is required",
10      "isActive": true
11    }
12  }
13}
14
15fm.toggleValidationNode('userName', 'required', false) 
16//returns
17{
18  "userName": {
19    "required": {
20      "errorMessage": "User Name is required",
21      "isActive": false
22    }
23  }
24}

data: javascript object (readonly)

Description: A collection of javascript field objects, as determined by the Field Schema that represents the values of each field provided.

Usage

1import FM from 'simple-form-manager-v2'
2import myFormSchema from './src/form-schemas/myFormSchema.js'
3const fm = new FM(myFieldSchema)
4fm.fields.userName = 'sallysmith'
5fm.fields.phone = '000-888-9999'
6fm.fields.income = '999999'
7console.log(fm.data)
8{
9  "userName": "sallysmith",
10  "phone": "000-888-9999",
11  "income": "999999",
12  "age": null
13}

all: javascript object (readonly)

Description: A collection of all of the javascript objects listed above:

• fields
• scheme
• form
• data

This is made available primarily for debugging your form code