Formatters

Often the data that is stored in the database is not in a format that is suitable for display or manipulate by the end user. A common example of this is a timestamp - the number of seconds since 1st January 1970 means little to anyone, even experienced developers, but it is a useful format to hold the data in, since it can be sorted and filtered quickly in the database. For this reason the Field class provides get and set formatters - specifically the getFormatter and setFormatter methods.

Terminology

Before we start on the formatters, we need to define get and set:

• Get formatter: Format for client-side from server data (i.e. server -> client)
• Set formatter: Format for server-side from client data (i.e. client -> server)

Formatter methods

Each Field instance has getFormatter() and setFormatter() methods, both of which accept identical options, the only difference is the direction of data travel upon which they apply their formatting rules, as described above. These methods take a single parameter - a function with the signature (in TypeScript notation):

( value: any, data: object ): string

Where:

• The return value is the formatted value
• Input 1 is the value read from the database (get) or from the client (set)
• Input 2 is the data for the whole row

Ready to use formatters

The Editor libraries provider a number of method that are ready to use to perform formatting on the Field class instances. These methods are available as static members of the Format class. Each method returns a function of the type required by the Field formatter methods.

Arrays

• implode(delimiter) - Convert an array of values from a checkbox into a string which can be used to store in a text field in a database.
  • Option: The delimiter to use - default value: |.
• explode(delimiter) - Convert a string of values into an array for use with checkboxes.
  • Option: The delimiter to use - default value: |.

Date and time

Note that the formatting options are defined by the Moment.JS library which is used to format date and time strings in the Editor Node.JS libraries.

• sqlDateToFormat(format) - Convert from SQL date / date time format (ISO 8601) to a format given by the options parameter.
  • Option: The format to convert to
• formatToSqlDate(format) - Convert from from a format given by the options parameter to a format that SQL servers will recognise as a date (ISO 8601).
  • Option: The format to convert from
• dateTime(from, to) - Convert from one date / time format to another
  • Option: The format to convert from
  • Option: The format to convert to

Empty values

• ifEmpty() - Set the value to write to the database if an empty string is submitted from the client-side. This could be null, - or something more complex such as No value set.
  • Option: The value that will be written to the database if an empty string is submitted.

Numeric values

• fromDecimalChar(decimalCharacter) - Convert a number from using any character other than a period (dot) to one which does use a period. This is useful for allowing numeric user input in regions where a comma is used as the decimal character. Use with a set formatter.
  • Option: The character used as the decimal mark - Default is a comma.
• toDecimalChar(decimalCharacter) - Convert a number with a period (dot) as the decimal character to use a different character (typically a comma). Use with a get formatter.
  • Option: The character to use as the decimal mark - Default is a comma.

Examples

The following example shows the sqlDateToFormat method being used to format the string:

Field(new Field("start_date")
    .getFormatter(Format.sqlDateToFormat('M/D/YYYY'))
    .setFormatter(Format.formatToSqlDate('M/D/YYYY'))
)

Use ifEmpty formatter to set different values for empty submitted data:

new Field( 'name' ).setFormatter( Format.ifEmpty( null ) );
new Field( 'age' ).setFormatter( Format.ifEmpty( 0 ) );

Custom formatters

If the provided methods above don't suit the kind of formatting you are looking for, it is possible to provide custom formatting methods. The getFormatter() and setFormatter() Field methods will accept a function that returns an value and accepts the following input parameters:

1. value (any) - The value to be formatted
2. row (Object) - The collection of data for the row in question

An anonymous function or an arrow function are excellent for defining formatter methods quickly and easily. A custom formatter method that simply formats a boolean into a string might look like:

new Field("Status")
    .getFormatter( (val, data) => val
        ? "Done"
        : "To Do";
    )

Formatting reference documentation

The Editor Node.JS reference documentation details the pre-built formatting methods available and also the interfaces used by the libraries if you wish to develop your own.