Compliance Is Freedom. Validation is Slavery.
Let's face it, form validation can be hard, really hard; just when you say to yourself "I just need to add a 'little' form validation"...BAM! it morphs into this monster of a task and attacks you from behind like a filthy disloyalist party member!
Why is form validation tricky and how does Big Brother help you ask?
Several things need to be taken into account when validating a form (even a very basic one) such as:
- The validity of each input field that has validation.
- Whether the input field is disabled or not. Required fields that are disabled should not affect the forms validity.
- Whether the input field is visible or not. Required fields that are not visible should not affect the forms validity.
- Dynamically added input fields that will affect the form's validity.
- Dynamically removed input fields will also affect the form's validity.
- Is the form dirty or pristine? Each state affects how you validate your form.
- Halting execution of the form while the form is pristine but invalid.
- Not showing validation errors on form load (pristine), even though the form is invalid.
- Pre-populating your form with values (like an edit form) and how that affects validity.
- Rolling up every input field's validty into the overall form validty and then acting on it.
- Hiding/showing elements, enabing/disabling buttons, showing/hiding message banners or any number of actions when each field's validity changes and when the overall form validity changes.
- Debugging through all of this while trying not to lose your mind.
But, do not worry. Big Brother will help you. Big Brother will protect you...if you comply.
Details Please!
Big Brother is a simple and flexible "form" validation library that handles the validation and the coordination
of
valid/invalid states of your form. It does NOT validate your fields or components themselves (that's the easy
part). Each html input field or React component tells BigBrother whether it's valid or not based on whatever
validation rules
that govern that component.
What it
does do is take the validity of each component and determines whether or not your form is valid
or
invalid while providing handy callbacks that let you do things like enable or disable a submit button, show or
hide
an error banner
or really anything else you want to do on your form that is based on it's validity.
Because Big Brother is only concerned with the form's validity it is completely decoupled from any
particular
"Front-end library or framework".
This means you can use it in either your React or your vanilla
js/jQuery
projects.
What's New in Version 2?
Big Brother is back and better than ever! Version 1, although very simple to use gave up some ground in the area of stability when forms became overly complex. This was largely due to the fact that Version 1 was based off of a "required field count" and kept track of the required fields via simple math. Big Brother V2 has gone away from using the required field count to keep track of the required components/controls in leau of a far more stable and flexible method of component registeration via their Id's. Athough this requires just a bit more setup, the payoff in flexabilty and stability is far greater.
Cool Features. For Loyalist eyes only!
Big Brother is simple, really simple. Aside from that it's flexible enough to accomodate just about any kind of form: simple, complex or completely dynamic. There's only a few public methods, a callback and a handy debug console output to use.
- Stupid Simple usage
- Works with normal JavaScript and React (Possibly the others as well)
- Extensible behavior for even more custom madness
- Can dynamically add or remove components/fields to validate
- Handy console output that shows which fields are valid are not
Installation
OR
DEMO / EXAMPLE APPS
REACT EXAMPLE
VANILLA JS EXAMPLE
Usage
Create an instance of Big Brother
Register all of your components / fields
Or you can conditionally register a single component/field
In your field or component's onChange event, call BigBrother's SetValidity method passing in the following required parameters
Example
Check the form's validity
API
registerComponents
Parameters:
An array of components/fields with the following properties:
{id} [string] the id of your input field or react component
{value} [string] the value of your component/field. Can be an empty ' ' if no default value is desired
{isValid} [boolean] the initial validity of your input field or react component (default is determined
based on the other properties)
{isRequired} [boolean] whether the component/field is required or not (default is false)
{isVisible} [boolean] whether the component/field is visible or not (default is true)
{isDisabled} [boolean] whether the component/field is visible or not (default is false)
Description: Adds components/fields to Big Brother's watchful eye.
Example:
this.bigBrother.registerComponents([
{id: 'first-name', isValid: true, value: ' ', isRequired: true, isVisible: true, isDisabled:
false},
{id: 'last-name', isValid: true, value: ' ', isRequired: true, isVisible: true, isDisabled:
false},
{id: 'email', isValid: true, value: ' ', isRequired: false, isVisible: true, isDisabled: false}
]);
registerComponent
Parameters:
An object with the following properties:
{id} [string] the id of your input field or react component
{value} [string] the value of your component/field. Can be an empty ' ' if no default value is desired
{isValid} [boolean] the initial validity of your input field or react component (default is determined
based on the other properties)
{isRequired} [boolean] whether the component/field is required or not (default is false)
{isVisible} [boolean] whether the component/field is visible or not (default is true)
{isDisabled} [boolean] whether the component/field is visible or not (default is false)
Description: Adds a single component/field to Big Brother's watchful eye.
Example:
bigBrother.registerComponent(
{id: 'first-name', isValid: true, value: ' ', isRequired: true, isVisible: true, isDisabled:
false}
);
unRegisterComponent
Parameters: {componentId} [string] the id of your component/field
Description: Dynamically removes your field or component from Big Brother's watchful eye.
Example:
this.bigBrother.unRegisterComponent(id);
setValidity
Parameters:
{isFormDirty} [boolean] whether or not the user has "attempted" to submit the form
{componentId} [string] the id of your input field or react component
{isValid} [boolean] the validity of your input field or react component
{isRequired} [boolean] whether or not this is a required field
{isVisible} [boolean] whether or not this is currently visible
{isInvalidCallback} [func] the callback you pass in that you want called if this component's validity
comes back as false (this is good for displaying an error banner)
{isValidCallback} [func] the callback you pass in that you want called if this component's validity
comes
back as true (this is good for hiding an error banner)
Description: Begins tracking that field or component's validity and calling the appropriate callback if the component is valid or not
Example:
function myOnValidationChangedHandler(componentId,
isValid, isRequired, isVisible){
bigBrother.setValidity(this.state.isFormDirty, componentId,
isValid, isRequired, true, ( ) => {
displayErrorMessage();
}, ( ) => {
dismissErrorMessage();
});
}
isValid
Description: Gets the valid state of your form. This is good for not allowing the user to submit the form until all fields are valid
Example:
function submitForm(){
this.setState({isFormDirty: true});
if (bigBrother.isValid()) {
saveFormValues();
}
else {
displayErrorMessage();
}
}