Installations
npm install simple-form-manager-v2
Developer Guide
Typescript
Yes
Module System
CommonJS
Node Version
16.15.0
NPM Version
8.10.0
Releases
Unable to fetch releases
Contributors
Unable to fetch Contributors
Languages
TypeScript (100%)
validate.email 🚀
Verify real, reachable, and deliverable emails with instant MX records, SMTP checks, and disposable email detection.
Developer
behaack
Download Statistics
Total Downloads
6,076
Last Day
1
Last Week
1
Last Month
7
Last Year
496
GitHub Statistics
MIT License
1 Stars
31 Commits
1 Watchers
1 Branches
1 Contributors
Updated on Sep 04, 2023
Bundle Size
5.22 kB
Minified
1.48 kB
Minified + Gzipped
Package Meta Information
Latest Version
1.7.0
Package Id
simple-form-manager-v2@1.7.0
Unpacked Size
89.65 kB
Size
50.51 kB
File Count
10
NPM Version
8.10.0
Node Version
16.15.0
Total Downloads
Cumulative downloads
Total Downloads
6,076
Last Day
0%
1
Compared to previous day
Last Week
0%
1
Compared to previous week
Last Month
-93.4%
7
Compared to previous month
Last Year
-51.8%
496
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dev Dependencies
2
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

No vulnerabilities found.

No security vulnerabilities found.