Formatting

In DataEntry, format rules describe how a value must be formatted. Formatted rules can be defined globally or in specific instances of DataEntry.

It offers a strategy to implement:

• formatting rules to be applied on values, after successful validation
• pre-formatting rules to be applied upon field focus (i.e. when the user starts editing a field - this is only available when using built-in classes handling DOM manipulation).

Demo: example of zero-fill formatting rules..

Global formatting rules

Rules defined in Formatter.Rules are common across all instances of DataEntry. Below example demonstrates the definition of new global formatting rules.

import DataEntry from "dataentry"

// get reference to Formatter class
const Formatter = DataEntry.Formatter;

Formatter.Rules.badass = function (value) {
  if (!value) return value;
  return value.replace(/a/g, "4").replace(/s/g, "5");
}

Instance specific formatting rules

Instance specific validation rules can also be defined when creating the instance of DataEntry:

import DataEntry from "dataentry"

// get reference to Formatter class
const Formatter = DataEntry.Formatter;

var a = new DataEntry({
  // specify one additional validation rule for the instance of dataentry:
  formatRules: {
    badass: function (value) {
      if (!value) return value;
      return value.replace(/a/g, "4").replace(/s/g, "5");
    }
  },
  schema: {
    // the format rule can then be used with multiple fields defined in the dataentry schema:
    "field_a": { validation: ["none"], format: ["badass"] },
    "field_b": { validation: ["required"], format: ["badass"] }
  }
})

ES6 class definition

Format rules can also be defined using the ES6 class syntax, defining new types of DataEntry.

import DataEntry from "dataentry";

// example:
class PaymentsAreaDataEntry extends DataEntry {
  // {...} implement here constructor to extend the rules for this kind of DataEntry
  // alter `this.formatter.rules` to add new rules for a class of DataEntry
}

Using format rules

Formatting rules can be used:

• explicitly
• implicitly

Explicit formatting

Formatting can be declared explicitly inside each dataentry schema, a simple example is a required field, that is automatically formatted to be trimmed, and to replace multiple spaces " " into single spaces " ".

var dataentry = new DataEntry({
  schema: {
    name: {
      validation: ["required"],
      format: ["cleanSpaces"] // trims and removes multiple spaces after successful validation
    }
  }
});

Implicit formatting

If the DataEntry useImplicitFormat option is different than false, then formatting rules are implicitly set when a validation rule has a name that matches the name of a formatting rule. For example:

      schema: {
        phoneNumber: {
          validation: ["phone"]
        },

If a phone formatting rule is defined inside the Formatter.Rules object, it will be automatically used to format the values for this field (in the example above, the "phoneNumber" field).

Define a custom format rule

This example shows how to implement a custom format rule, for a phone number supporting country prefix:

    Formatter.Rules.phone = {
      fn: function (value) {
        if (!value) return value;
        var parts = value.replace(/\s/g, "").match(/[0-9\+]{1,3}/g);
        if (parts) {
          return parts.join(" ");
        }
        return value;
      }
    };

Preformatting rules

Preformatting rules are formatting rules that are applied on fields upon focus. For example, imagine a situation in which a decimal field may contain a "0,0" value, but upon focus this value should be replaced by an empty string "". Or, imagine a "zero-filled" numeric value, like "00000010", that upon focus should be automatically set to "10" before the user starts typing.

Pre-formatting rules can only be defined explicitly, using the preformat option for a field schema. In following example, a field with name "name", is configured to be zero-filled up to 3 characters length, and removing the zeroes upon focus. In this example the DomBinder class is used, which automatically takes care of formatting input field values on focus and blur events.

    const dataentry = new DataEntry({
      element: wrapper,
      marker: DomDecorator,
      harvester: DomHarvester,
      binder: DomBinder,
      schema: {
        name: {
          validation: ["required"],
          format: [{ name: "zero-fill", length: 3 }],
          preformat: ["zero-unfill"]
        }
      }
    })

The rules for pre-formatting are the same defined for formatting, so they are defined in the same way.