jaster-validate v0.2.0

Overview

jaster-validate is an ES6 form validation library with a focus on creating reusable validation components which can be mix-and-matched together to easily choose between how the UI and logic are handled during form validation.

There are several core types to this library that allows its customisation:

• The UI Handlers
• The Logic Handlers
• The Selectors
• The Rules
• The Policies

Policies

Policies are basically a collection that consist of a UI handler, Logic handler, and a selector.

Policies are used to mix-and-match these three core classes, which allows most of the customisation of this library.

For example, you can have a UI handler that is based on Bootstrap, and you can have another UI handler based on Semantic UI (for some reason this imaginary project uses both).

You can make a boostrap-no-submit policy that consists of the boostrap ui handler, the no-submit-form logic handler, and the default selector.

You can then also make a semantic-no-submit policy that is almost the same, except the UI handler is now using the semantic ui handler.

So now we have two policies, both of which use the same selector and logic handler, but also use different ui handlers. So they function the same way behind the scenes, but they update the UI for a bootstrap/semantic-ui specific theme.

This is the core idea behind having policies: reusability, and composition.

Selectors

A problem some validation libraries have is that they simply assume which elements inside a form the user wants to validate, and in some cases (such as heavily CSSed custom input fields with a specific markup layout) they can lack core pieces of data it may need for validation as they may not be present inside of conventional tags such as <input>.

This library tries to solve this problem with the use of the use of selectors. Each policy will specify a selector to use.

When a form is validated (e.g. Validation.validateForm("my form", null, "my policy")) the validator needs to know which elements inside of the form that it needs to attempt to validate. As I've already explained, this library doesn't hard code a list of elements that it will validate, so it needs a way to know what list of elements it should be using.

This is where a selector comes in. During validation of a form, the validator will pass the form to the policy's selector, and the selector will then return an array of elements to be validated.

Selectors can be created by the user and registered via the Validation.addSelector function, so this should solve most problems revolving around certain elements not being registered for validation.

I admit this is a very very niche case, to the point there's pretty much no actual use for this, but it's a simple enough addition that it may as well exist.

I feel that it's so niche in fact, that when defining a policy (using Validation.definePolicy) you don't even need to specify which selector the policy should use. It will just use the default, built-in selector if you don't specify one.

Built-in selectors:

UI and Logic handlers

As explained in the policies section, it is useful to be able to seperate the UI side of validation handling from the logic side of it.

So quite simply, UI handlers contain the code for updating the UI (and additional callbacks useful for UI), while logic handlers contain the code for any additional logic being done during validation (such as call preventDefault() on the form submit event).

There are currently no built-in UI handlers, as this is subjective for every webpage/site.

Built-in handlers:

Rules and Rulesets

Rules, as the name implies, are simply rules that an element has to pass if it doesn't want to fail validation.

Rules are global, so don't need to be specified on a per-policy basis (though I may add this feature in the future).

The rules that an element is to be tested under are specified in a ruleset, which is basically a list of rule names (and any parameters that they need) that the element will be subject to.

If you are validating a single element manually via code, then you can usually pass the ruleset as a parameter to a function (e.g. Validation.validateElement(myElem, 'not-empty')).

If you are validating an entire form, then rulesets have to be defined using a data-ruleset attribute, e.g. <input data-ruleset='not-empty' />.

The most basic format for a ruleset is to simply state a name: not-empty

Rulesets can be given parameters. Parameters are seperated by the '&' character (which can be escaped using \&), and have their whitespace trimmed at the start and end of them. When passing parameters to a rule, you must put a colon (':') after the rule name: some-multi-param-rule: This is param 0 & This is param 1 \& and param 2 does not exist

Multiple rules can be specified in a ruleset by seperating them with a semi-colon (';'), which can also be escaped: not-empty; regex: ^[abc]$

While not the greatest format in the world, it should suffice for most uses. In the future I may allow rules to specify a format string, so that the validator can automatically ensure that parameters are passed in the correct format, but for now rules are responsible for vetting their parameters.

Parameters are always passed to rules as strings, so rules may need to do additional conversion.

Built-in rules:

Further Reading

• Getting Started