Working with web forms can be tedious and time-consuming. Many of the tools that exist today require individual setup and handling for each form element. Furthermore, the current set of tools can be rigid and limiting in their functionality.
FormsJs was built with three main classes: Populator, Validator, and Serializer. Each class is instantiated with a different configuration, giving you the flexibility to use the appropriate tool for the job.
The job of the populator is, naturally, to populate forms. You give it a list of all the elements you want populated, with the values you want, and it does the rest. Here's a sample configuration array:
With this configuration, we are telling the form to autofill the email address and check the box to sign them up for newsletters. The type parameter specifies the type of element to target. Currently, FormsJs supports 'text,' 'radio,' 'checkbox,' and 'select' as strings.
The elementSelector parameter specifies the specific element to target using a jQuery selector (i.e. '[name=email],' '#email,' etc.).
The value parameter is the value to be populated. Text boxes, radio buttons, and select lists all take strings. Checkboxes take an array of strings to account for the possibility of groups of checkboxes with the same selector.
To use this configuration on your form, create a new Populator with the populatorConfig:
Then, when you're ready to populate the form, you just call the populate method on your populator.
Once the user has completed the form, you'll want to validate the information before submitting. The Validator class handles this for all of the form's elements. Using a configuration array similar to the populator, the validator also looks for a type and an elementSelector. Additionally, it also looks for an array of validations giving each element the ability to match several different validations (i.e. 'required' and 'minLength'). Here's a sample validator configuration:
As you can see, within the validations parameter, a 'type' and an 'errorMessage' are specified. Certain validations also have an additional parameter depending on their type (i.e. 'minLength' and 'maxLength' both also require a 'length'). Currently, FormsJs supports the following validation types: 'required,' 'email,' 'minLength,' 'maxLength,' 'regExp,' and 'matchingInput'.
These types should cover the majority of form validation needs. However, we also included a 'customMatcher' should you need any specific validating. This validator requires a third parameter—a callback function that takes a value to be matched against and returns true or false.
To use the validatorConfig in your form, create a new validator with your configuration:
The Validator Class has two methods:
validator.isValid() will return true or false. Calling
validator.errors() will return
an object with the elementSelector and an array of its error messages. If our email address was
left blank, this would return:
As you can see, FormsJs gives you complete control over how to validate a form and display the errors.
After you have a complete and valid form, you need to serialize the data to be passed to the server. As with the other classes, FormsJs gives you complete control over how to do this. Start by creating a serializer configuration:
In addition to the usual 'type' and 'elementSelector' parameters, the serializer has an optional 'dataKey' parameter. This allows you to specify the exact way the field should be sent to your database. If a 'dataKey' is not specified, FormsJs will use the HTML name attribute from your element.
As with the previous classes, create a new Serializer with your configuration:
serializer.serialize() will return a JSON object, with each key being the specified dataKey
(or element name) and the current value of the form:
When we first used FormsJs for one of our projects, we noticed an interesting problem. We had a page with multiples of the same form (think add additional records). Because of this, our elementSelector was duplicated on our page and we couldn't properly select the form we wanted to work with. To fix this problem, we added a scope to our constructors. The populator, validator, and serializer now all take an optional scope parameter on initialization. This scope paramater is a jQuery selector as a string. Here's an example:
Hopefully you can see the value that FormsJs brings to web forms. For more information and complete sample config files, check out the README on the project’s home page.