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

$3

###### fields: object,
###### fieldScheme: readonly object
###### form: readonly object,
###### data: readonly object,
###### all: readonly object,
###### formSubmittable: readonly boolean
###### running: readonly boolean

$3

###### 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
`javascript
import FM from 'simple-form-manager-v2'
import myFormSchema from './src/form-schemas/myFormSchema.js'
const 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.

`javascript
// userFormSchema.js
import { required } from 'vuelidate/lib/validators'

export default {
userName: {
required: {
validator: required,
errorMessage: 'User Name is required'
}
}
}
`
`html
// userForm.vue


`

Form Schema Explained

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

`javascript
// I am getting my validator functions here from npm package
// vuelidate. You can write your own or find others on npm.
import { required, email } from 'vuelidate/lib/validators'

export default {
// the form descibed in this file had three fields:
// - userId
// - userName
// - email
userId: {}, // no validation rules, in the interface the id is likely read-only
username: {
required: { // validation rule for username
validator: required,
errorMessage: 'Username is required'
}
},
// email is the other field variable name in your form
email: {
required: {
validator: required, // Must me a function, see below for details
errorMessage: 'Email is required' // Must be a string
},
validEmail: { // validation rule #2 for email
validator: email,
errorMessage: 'Email is not a proper email format'
}
validEmail: { // validation rule #2 for email
validator: maxLength(100),
errorMessage: 'Email may not exceed 100 characters'
}
}
}
`

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:
`javascript
// Validation rule with no parameter (i.e. required)
fn(valueToBeValidated) => { return boolean }

// Validation rule with one, or more parameters (i.e. maxLength(100))
fn(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
`javascript
import FM from 'simple-form-manager-v2'
import myFormSchema from './src/form-schemas/loginFormSchema.js'
const fm = new FM(loginFormSchema.js)
`

$3

###### 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
``javascript
// starts tracking user input with a frequency of 1 second
fm.start(1000)
``

$3

###### 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
``javascript
// starts tracking user input with a frequency of 1 second
fm.stop()
``

$3

###### 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
``javascript
// change the value of the 'lastName' field to and empty string (i.e. '')
fm.setTouched('lastName', '')
``

$3

###### 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
``javascript
let person = {
FirstName: 'Mary',
MiddleInitial: 'L',
LastName: 'Henderson'
}
// sets the values of the fields: FirstName, MiddleInitial & LastName
fm.setValues(person)
``

$3

###### 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
``javascript
// sets the touched value for the password field to true
fm.setValue('password')
``

$3

###### 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
``javascript
let country = {
countryCode: 'CH',
countryName: 'Switzerland',
capital: 'Bern'
}

// change the objectValue of the 'countryCode' field to country
fm.setUpdateModelValue('countryCode', country)
``

$3

###### 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
``javascript
// sets the touched value for the password field to true
fm.onBlur('password')
``

$3

###### 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
``javascript
// change the value of the 'lastName' field to and empty string (i.e. '')
fm.onUpdateValue('lastName', '')
``

$3

###### 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
``javascript
const formScheme = {
password: {
required: {
validator: required,
message: 'Password is required'
}
},
confirmationPassword: {
matchesPassword: {
validator: null, // No validator, this is handled outside of Form Manager
message: 'Password and Confirmation Password do not match'
}
}
}

// change the 'valid' status of the 'confirmationPassword' to false
fm.setFieldStatus('confirmationPassword', 'matchesPassword', false)
``

$3

###### 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
``javascript
// change the 'valid' status of the 'confirmationPassword' to false
fm.setFieldStatus('confirmationPassword', false, 'Password and Confirmation Password do not match')
``

$3

###### 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
``javascript
// change the value of the 'lastName' field to and empty string (i.e. '')
fm.onUpdateModelValue('countryCode', {
countryCode: 'CH',
countryName: 'Switzerland',
capital: 'Bern'
})
``

$3

###### 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
``javascript
// sets the 'required' validation rule for the 'socialSecurityNumber'
// field to false
fm.toggleValidationNode('socialSecurityNumber', 'required', false)
``

$3

###### 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
``javascript
// return true if the 'password' field is both invalid and touched
fm.showFieldError('password')
``

$3

###### 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

``javascript
//
// Values before resetting the form
//

// Field values
console.log(fm.fields)
// returns
{
"userName": {
"dirty": true,
"touched": true,
"value": "janejohnson",
"originalValue": "sallysmith",
"valid": true,
"errorMessage": ""
},
"phoneNumber": {
"dirty": true,
"touched": true,
"value": "999QQQQQQQ",
"originalValue": "888-999-1234",
"valid": false,
"errorMessage": "Not a valid phone number"
}
}

// Form values
console.log(fm.form)
// returns
{
"dirty": true,
"valid": false,
"touched": true
}

//
// Values after resetting the form
//
fm.resetField('userName')
console.log(fm.fields.userName)
// Field values
console.log(fm.fields)
// returns
{
"userName": {
"dirty": false,
"touched": false,
"value": "sallysmith",
"originalValue": "sallysmith",
"valid": true,
"errorMessage": ""
},
"phoneNumber": {
"dirty": false,
"touched": false,
"value": "888-999-1234",
"originalValue": "888-999-1234",
"valid": false,
"errorMessage": "Not a valid phone number"
}
}

// Form values
console.log(fm.form)
// returns
{
"dirty": false,
"valid": false,
"touched": false
}
``

$3

###### Return value: none
###### Parameters: none
###### Description: Resets the form and the field attributes for the fields, while preserving the field values.
###### Usage

``javascript
//
// Values before resetting the form
//

// Field values
console.log(fm.fields)
// returns
{
"userName": {
"dirty": true,
"touched": true,
"value": "janejohnson",
"originalValue": "sallysmith",
"valid": true,
"errorMessage": ""
},
"phoneNumber": {
"dirty": true,
"touched": true,
"value": "999QQQQQQQ",
"originalValue": "888-999-1234",
"valid": false,
"errorMessage": "Not a valid phone number"
}
}

// Form values
console.log(fm.form)
// returns
{
"dirty": true,
"valid": false,
"touched": true
}

//
// Values after resetting the form
//
fm.resetField('userName')
console.log(fm.fields.userName)
// Field values
console.log(fm.fields)
// returns
{
"userName": {
"dirty": false,
"touched": false,
"value": "janejohnson",
"originalValue": "janejohnson",
"valid": true,
"errorMessage": ""
},
"phoneNumber": {
"dirty": false,
"touched": false,
"value": "999QQQQQQQ",
"originalValue": "999QQQQQQQ",
"valid": false,
"errorMessage": "Not a valid phone number"
}
}

// Form values
console.log(fm.form)
// returns
{
"dirty": false,
"valid": false,
"touched": false
}
``

$3

###### 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

``javascript
console.log(fm.fields.userName)
// returns
{
"dirty": true,
"touched": true,
"value": "janejohnsonaaaaaaaaaaaaaaaaaaaaaa",
"originalValue": "",
"valid": false,
"errorMessage": "User Name exceeds 15 charcters"
}

fm.resetField('userName')
console.log(fm.fields.userName)
// returns
{
"dirty": false,
"touched": false,
"value": "janejohnsonaaaaaaaaaaaaaaaaaaaaaa",
"originalValue": "janejohnsonaaaaaaaaaaaaaaaaaaaaaa",
"valid": false,
"errorMessage": "User Name exceeds 15 charcters"
}
``

Simple Form Manager V2 Properties

$3

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

``javascript
fm.start()
console.log(fm.running)
// returns
true
``

$3

###### 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

``javascript
// Read Example
console.log(fm.fields)
// returns
{
"userName": {
"dirty": true,
"touched": true,
"value": "jdoe",
"originalValue": "",
"valid": true,
"errorMessage": ""
},
"password": {
"dirty": true,
"touched": true,
"value": "hello1",
"originalValue": "",
"valid": false,
"errorMessage": "Passwords must be at least 8 charcters and consist of at least 1 special charcter "
}
}

// Write Example
fm.fields.userName.value = 'johnDoe'
fm.fields.phoneNumber.value = '999-999-1212'
fm.start()
``

``html

@blur="fm.onBlur('userName')"
v-model="fm.fields.userName.value"
type="text"
/>



handleChange = (e) => {
/// ...handle update
},
handleBlur = (e) => {
/// ...handle update
},
render(){
return (
value="{this.state.fm.fields.userName.value"
onChange={this.handleChange}
onBlur={this.handleBlur}
type="text"
/>
)
}
``

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

$3

###### 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
``javascript
console.log(fm.form)
///returns (example)
{
"dirty": false,
"valid": true,
"touched": true
}
``

$3

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

``javascript
//
// * Example #1 *
//
console.log(fm.form)
// returns
{
"dirty": false,
"valid": true,
"touched": true
}
console.log(fm.formSubmittable)
// returns
false

//
// * Example #2 *
//
console.log(fm.form)
// returns
{
"dirty": true,
"valid": true,
"touched": true
}
console.log(fm.formSubmittable)
// returns
true
``

$3

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

###### Usage

``javascript
import FM from 'simple-form-manager-v2'
import myFormSchema from './src/form-schemas/myFormSchema.js'
const fm = new FM(myFieldSchema)
console.log(fm.scheme)
//returns
{
"userName": {
"required": {
"errorMessage": "User Name is required",
"isActive": true
}
}
}

fm.toggleValidationNode('userName', 'required', false)
//returns
{
"userName": {
"required": {
"errorMessage": "User Name is required",
"isActive": false
}
}
}
``

$3

###### Description: A collection of javascript field objects, as determined by the Field Schema that represents the values of each field provided.
###### Usage
``javascript
import FM from 'simple-form-manager-v2'
import myFormSchema from './src/form-schemas/myFormSchema.js'
const fm = new FM(myFieldSchema)
fm.fields.userName = 'sallysmith'
fm.fields.phone = '000-888-9999'
fm.fields.income = '999999'
console.log(fm.data)
{
"userName": "sallysmith",
"phone": "000-888-9999",
"income": "999999",
"age": null
}
```

$3

###### 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