Getting started

DataEntry is a forms validation library implementing Promise based validation of fields. One of its main objectives is to enable the implementation of validation and formatting strategies that are consistent across whole applications. To achieve this objective, DataEntry is designed to:

• support both global validation rules and rules defined when instantiating a DataEntry
• enable the definition of validation and formatting schema in a declarative way
• unify the code that decorates the fields, marking them in valid, invalid or neutral state

This is both to avoid code repetition and to avoid tedious operations like implementing the validation code in every single view, which doesn't scale well when many people work on different parts of an application.

The library is designed to clearly separate functions that do business logic from classes that read / write values and mark fields as valid or invalid. See Core classes and design for more information.

What DataEntry is not

DataEntry is not a templating engine. It doesn't create HTML forms, nor populates the values of HTML input elements with values read from objects. DataEntry is only concerned with validation, which can be of objects in memory, or HTML elements. In the latter case, whether the HTML of a form is generated using a server side engine, or the templating engine of client side libraries or frameworks, DataEntry can be used to validate the values of these forms. The only exception is formatting of values inside input fields: DataEntry has built-in features to automatically format values after successful validation (this feature can be turned off as desired), which is a simple case to handle.

How to use

DataEntry can be used installing npm package or downloading distribution files.

Use with distribution files

DataEntry library can be used downloading and using distribution files, in distribution folder.

<script src="dataentry.js"></script>

Only import one of the JavaScript files, as each of them includes the core classes and is designed to be used independently. Programmers who prefer to let other frameworks handle DOM manipulation (such as Vue.js, React or Knockout) should either use dataentry.js and implement their own classes for decorator and marker (see classes documentation) or evaluate and try to use the built-in dataentry-context.js file. While programmers who don't mind having the library handling DOM manipulation and setting event handlers, can use dataentry-dom.js and dataentry.css files.

File	Description
dataentry.js	Core classes only: DataEntry, Validator and Formatter (require custom implementation of harvester and marker objects)
dataentry-dom.js	Core classes with built-in features involving DOM manipulation
dataentry-context.js	Core classes with built-in features to work with in-memory objects only
dataentry.css	Css rules for built-in DOM classes

Install using npm

DataEntry library can be installed using npm (npm page).

npm install dataentry

Modules can then be imported using CommonJS syntax:

var DataEntry = require("dataentry")
var DataEntryDom = require("dataentry/dom")
// var DataEntryContext = require("dataentry/context")

Or ES6 import syntax:

import DataEntry from "dataentry"
import DataEntryDom from "dataentry/dom"

// example of configuration to use built-int methods for DOM manipulation:
DataEntry.configure({
  marker: DataEntryDom.DomMarker,
  harvester: DataEntryDom.DomHarvester,
  binder: DataEntryDom.DomBinder
})

Example using built-in methods completely abstracted from DOM manipulation:

import DataEntry from "dataentry"
import DataEntryContext from "dataentry/context"

// example of configuration to use built-int methods without DOM manipulation:
DataEntry.configure({
  marker: DataEntryContext.ContextMarker,
  harvester: DataEntryContext.ContextHarvester
})

Objectives

The objectives of the DataEntry library are:

• to enable the implementation of application-wide validation strategy: centralizing the logic that displays error messages, marks fields in valid or invalid state, and applies validation and formatting rules
• to simplify the implementation of fields validation in new applications
• to simplify the definition of asynchronous validation rules (for example, rules involving AJAX requests)
• to provide a simple way to define new validation and formatting rules

Features

• ES6 source code
• Unit tested source code
• Promise based validation of fields and forms
• automatic decoration of fields (valid state, invalid state, neutral)
• logic to define validation rules
• logic to define formatting rules
• logic to apply pre-formatting rules (formatting to be applied upon field focus)
• logic to define constraints (disallow certain inputs, e.g. only positive integer values, only letters, .etc)
• good documentation, in GitHub wiki
• raised exceptions include a link to GitHub wiki, with instructions on how they can be resolved

Pluggable design

The library is designed to clearly separate functions that do business logic from classes that read / write values and mark fields as valid or invalid. See Core classes and design for more information.

Promise based validation

See the dedicated wiki page, about validation schema and use of promises.

Demos

React demo.