gandalf-validator
Determines who shall and shall not pass form validation in React
Note: This documentation is for version 1.X.X, for 0.X.X documentation, see README_v0.
Contents
Installation
npm install --save gandalf-validator
Usage
The Gandalf class extends React.Component, so we start by extending Gandalf.
import React from 'react';
import Gandalf from 'gandalf-validator';
class Form extends Gandalf {
componentDidMount() {
this.buildFields(fieldDefinitions);
}
...
render(){
if (!this.areFieldsReady()) {
return 'Loading...';
}
return (
<form>
...
);
}
}
export default Form;Gandalf expects the buildFields method to be called in the componentDidMount lifecycle method. buildFields takes a field definitions array as its only parameter.
It also provides the areFieldsReady method to be used in the render method to show a loading state before all the fields are generated.
Field Definitions
Example
const fieldDefinitions = [
{
name: 'name',
component: TextField,
validators: ['required'],
errorPropName: 'errorText',
props: {
hintText: 'Name',
},
debounce: 500,
},
{
name: 'age',
component: TextField,
validators: ['required', 'numeric'],
errorPropName: 'errorText',
props: {
hintText: 'Age',
},
debounce: 300,
}
];Options
| Property | Type | Description |
|---|---|---|
name |
String | Field name |
component |
React Component | The component to render |
props |
Object | Props to pass to the component |
validators |
Array | List of validators to apply to the value |
errorPropName |
String | The name of the prop in component used to display errors (optional) |
errorPropIsBool |
Boolean | Whether the errorPropName expects a boolean instead of a string (optional) |
onChangeHandler |
Function | Specify a name for the change handler function, defaults to onChange
|
getValueInOnChange |
Function | If the value in the onChange handler is something other than e.target.value, this function can get it. Takes (e, key, payload). |
children |
Array | Array of child React Components. Remember to add a key prop. |
debounce |
Integer | Milliseconds to delay validation, resets w/ each keystroke (optional) |
defaultValue |
Any | Default value for the component (optional) |
Validators
Gandalf ships with several out of the box validations. Some are very simple, requiring only a string identifier. Others are more complex, requiring an object.
Simple
requirednumericemail
To enable a simple validator, add the string identifier to the validators prop.
validators: ['required', 'numeric', 'email']Complex
minLengthmaxLengthminmaxregex
Complex validators are objects with a name and value property.
validators: [{ name: 'minLength', value: 8 }, { name: regex, value: /[^0-9]/g }]Simple + Complex
You can use both simple and complex validators on the same field.
validators: [
'required',
{ name: 'minLength', value: 8 },
{ name: regex, value: /.+\s.+/g }
]Custom Error Messages
Gandalf provides generic error messages by default, but you can pass your own to the Validator object. If you're using a simple validator, you can use an object with name and message fields as shown below.
validators: [
{ name: 'required', message: 'How dare you not fill this field?' }
{ name: 'minLength', value: 8, message: 'Your answer is too short! It must be at least 8 characters.' },
]In Practice
import React from 'react';
import Gandalf from 'gandalf-validator';
import TextField from 'material-ui/TextField';
import { Input } from 'semantic-ui-react';
class Form extends Gandalf {
componentDidMount() {
const fieldDefinitions = [
{
name: 'firstName',
component: TextInput,
validators: ['required'],
errorPropName: 'errorText',
props: {
autoComplete: 'given-name',
label: 'First Name',
},
debounce: 300,
},
{
name: 'lastName',
component: TextInput,
validators: ['required'],
errorPropName: 'errorText',
props: {
autoComplete: 'family-name',
label: 'Last Name',
},
debounce: 300,
},
{
name: 'company',
component: TextInput,
validators: ['required'],
errorPropName: 'errorText',
props: {
autoComplete: 'organization',
label: 'Company Name',
},
debounce: 300,
},
{
name: 'phone',
component: TextInput,
validators: [
'required',
{
name: 'regex',
value: /\D*([1-9]\d{2})(\D*)([1-9]\d{2})(\D*)(\d{4})\D*/,
message: 'Please enter a valid phone number',
},
],
errorPropName: 'errorText',
props: {
autoComplete: 'tel',
label: 'Phone #',
},
debounce: 700,
},
{
name: 'availability',
component: SelectField,
validators: ['required'],
errorPropName: 'errorText',
getValueInOnChange: (e, key, value) => value,
props: {
hintText: 'Availability',
},
children: [
<MenuItem key={1} value="Never" primaryText="Never" />,
<MenuItem key={2} value="Every Night" primaryText="Every Night" />,
<MenuItem key={3} value="Weeknights" primaryText="Weeknights" />,
<MenuItem key={4} value="Weekends" primaryText="Weekends" />,
<MenuItem key={5} value="Weekly" primaryText="Weekly" />,
],
},
{
name: 'colour',
component: Input,
validators: ['required'],
errorPropName: 'error',
errorPropIsBool: true,
props: {
placeholder: 'Favourite Colour',
},
debounce: 300,
},
{
name: 'email',
component: TextField,
validators: ['required', 'email'],
errorPropName: 'errorText',
props: {
hintText: 'Email',
},
debounce: 300,
},
};
this.buildFields(fieldDefinitions);
}
}Rendering
The buildFields method build your form inputs as puts them into this.state.fields. Each element is accessible via the value of its name property.
Use the areFieldsReady method to show a loading state before all the fields are generated.
render() {
const fields = this.state.fields;
if (!this.areFieldsReady()) {
return 'Loading...';
}
return (
<form>
<h1>My Form</h1>
{ fields.firstName.element } <br />
{ fields.lastName.element } <br />
{ fields.company.element } <br />
{ fields.phone.element } <br />
{ fields.availability.element } <br />
{ fields.colour.element } <br />
{ fields.email.element } <br />
<button onClick={this.handleSubmit}>Submit</button>
</form>
);
}Handling Form Submit
Gandalf provides two methods for getting form data:
// Returns form data, regardless of its validity
this.getFormData();
// If the form is valid, returns the form data, otherwise returns null
this.getCleanFormData();Recommended submit handler implementation:
handleSubmit() {
const data = this.getCleanFormData();
// If form is invalid, all error messages will show automatically
// So you can simply exit the function
if (!data) return;
// Handle valid data here
}Checking Form State
Gandalf also privides two methods for checking the current state of the form:
// Not every element on the form has been touched - it may be invalid, but not all errors are triggered
// An element is not included in this list if it has an empty validators array
this.formHasPristineElements()
// Whether the form is currently valid. Use in combination with formHasPristineElements for reliable results
this.formIsValid()It also provides a method to check if the form elements were built:
// Returns true if the buildFields() has been called and fields are created
this.areFieldsReady();Full Example
import React from 'react';
import Gandalf from 'gandalf-validator';
import TextField from 'material-ui/TextField';
import { Input } from 'semantic-ui-react';
class Form extends Gandalf {
componentDidMount() {
const fieldDefinitions = [
{
name: 'firstName',
component: TextInput,
validators: ['required'],
errorPropName: 'errorText',
props: {
autoComplete: 'given-name',
label: 'First Name',
},
debounce: 300,
},
{
name: 'lastName',
component: TextInput,
validators: ['required'],
errorPropName: 'errorText',
props: {
autoComplete: 'family-name',
label: 'Last Name',
},
debounce: 300,
},
{
name: 'company',
component: TextInput,
validators: ['required'],
errorPropName: 'errorText',
props: {
autoComplete: 'organization',
label: 'Company Name',
},
debounce: 300,
},
{
name: 'phone',
component: TextInput,
validators: [
'required',
{
name: 'regex',
value: /\D*([1-9]\d{2})(\D*)([1-9]\d{2})(\D*)(\d{4})\D*/,
message: 'Please enter a valid phone number',
},
],
errorPropName: 'errorText',
props: {
autoComplete: 'tel',
label: 'Phone #',
},
debounce: 700,
},
{
name: 'availability',
component: SelectField,
validators: ['required'],
errorPropName: 'errorText',
getValueInOnChange: (e, key, value) => value,
props: {
hintText: 'Availability',
},
children: [
<MenuItem key={1} value="Never" primaryText="Never" />,
<MenuItem key={2} value="Every Night" primaryText="Every Night" />,
<MenuItem key={3} value="Weeknights" primaryText="Weeknights" />,
<MenuItem key={4} value="Weekends" primaryText="Weekends" />,
<MenuItem key={5} value="Weekly" primaryText="Weekly" />,
],
},
{
name: 'colour',
component: Input,
validators: ['required'],
errorPropName: 'error',
errorPropIsBool: true,
props: {
placeholder: 'Favourite Colour',
},
debounce: 300,
},
{
name: 'email',
component: TextField,
validators: ['required', 'email'],
errorPropName: 'errorText',
props: {
hintText: 'Email',
},
debounce: 300,
},
};
this.buildFields(fieldDefinitions);
}
handleSubmit() {
const data = this.getCleanFormData();
// If form is invalid, all error messages will show automatically
// So you can simply exit the function
if (!data) return;
// Handle valid data here
}
render() {
const fields = this.state.fields;
if (!this.areFieldsReady()) {
return 'Loading...';
}
return (
<form>
<h1>My Form</h1>
{ fields.firstName.element } <br />
{ fields.lastName.element } <br />
{ fields.company.element } <br />
{ fields.phone.element } <br />
{ fields.availability.element } <br />
{ fields.colour.element } <br />
{ fields.email.element } <br />
<button
onClick={() => this.handleSubmit()}
disabled={() => this.formHasPristineElements() || !this.formIsValid()}
>
Submit
</button>
</form>
);
}
}Building Components for Gandalf
Some component libraries provide inputs with built in error handling.
For example, Material UI TextFields provide an errorText prop that alters the component's appearance if it exists. Similarly, Semantic UI's Input component provides a boolean error prop that turns the input red if it exists.
But what if you want to build your own component for use with Gandalf? Turns out it's pretty easy.
React Native Example
React Native provides a TextInput component. It's very similar to an HTML input in regular React, with a few tiny differences. For example it exposes an onChangeText handler instead of an onChange handler for handling input changes.
But it has no build in error handling. So let's build it. We'll call it ValidatedTextInput.
import React from 'react';
import { View, Text, TextInput } from 'react-native';
const ValidatedTextInput = (props) => (
<View>
<View>
<Text>{ props.title }</Text>
<TextInput
onChangeText={props.onChange}
placeholder={props.placeholder}
/>
</View>
{!!props.error &&
<View>
<Text>
{ props.error }
</Text>
</View>
}
</View>
);We know that we can define arbitrary props in the Fields Object.
On top of those, Gandalf passes in an error prop (string) and an onChange handler (function).
We can use the existence of error to conditionally render the error message UI. The rest is as simple as passing props to TextInput.
Now we can use ValidatedTextInput in Gandalf:
import React from 'react';
import Gandalf from 'gandalf-validator';
import { View, Text, TouchableHighlight } from 'react-native';
import ValidatedTextInput from '../components/ValidatedTextInput';
class Form extends Gandalf {
componentDidMount() {
const fields = [
{
name: 'fName',
component: ValidatedTextInput,
getValueInOnChange: value => value,
validators: ['required'],
props: {
title: 'First Name',
placeholder: 'John Doe',
},
debounce: 300,
},
};
this.buildFields(fields);
}
handleSubmit() {
const data = this.getCleanFormData();
// If form is invalid, all error messages will show automatically
// So you can simply exit the function
if (!data) return;
// Handle valid data here
}
render() {
const fields = this.state.fields;
if (!this.areFieldsReady()) {
return 'Loading...';
}
return (
<View>
{ fields.fName.element }
<TouchableHighlight onPress={this.handleSubmit}>
<Text>Submit</Text>
</TouchableHighlight>
</View>
);
}
}Contributing
File a Github Issue or fork this repo, make a PR and bump the version in the package.json file.
To build locally, use npm run build. This will transpile and uglify the library.
Running tests locally
You will need to add a .babelrc file in your local gandalf-validator directory. It is git ignored, as it can conflict with .babelrc files in projects using Gandalf.
.babelrc:
{
"presets": ["es2015"]
}
