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 nano-seconds since 1st January 1601 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 delegate function with the signature:

object delegate( object, Dictionary<string, object> );

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 delegate of the type required by the Field formatter methods.

Arrays

• Implode(string 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
• Explode(string delimiter = "|") - Convert a string of values into an array for use with checkboxes.
  • Option: The delimiter to use

Date and time

Note that the formatting options are defined by the .NET custom date and time format string options

• DateSqlToFormat(string format) - Convert from SQL date / date time format (ISO 8601) to a format given by the options parameter.
  • Option: The format to convert to
• DateFormatToSql(string 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(string from, string 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.
• NullEmpty() - A special case of ifEmpty which will use null as the value to write to the database is an empty string is submitted. This formatting method does not provide any options.

Numeric values

• FromDecimalChar(char dec) - 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(char dec) - 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 DateSqlToFormat method being used to format the string:

Field(new Field("start_date")
    .GetFormatter(Format.DateSqlToFormat(Format.DATE_ISO_1036))
    .SetFormatter(Format.DateFormatToSql(Format.DATE_ISO_1036))
)

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 ) );

Static values

The Format class also provides a number of helper static values which can be used for converting dates and times:

• Format.DATE_ISO_8601 (Y-m-d) - Date format: 2012-03-09
• Format.DATE_ISO_822 (D, j M y) - Date format: Fri, 9 Mar 12
• Format.DATE_ISO_850 (l, d-M-y) - Date format: Friday, 09-Mar-12
• Format.DATE_ISO_1036 (D, j M y) - Date format: Fri, 9 Mar 12
• Format.DATE_ISO_1123 (D, j M Y) - Date format: Fri, 9 Mar 2012
• Format.DATE_ISO_2822 (D, j M Y) - Date format: Fri, 9 Mar 2012

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 delegate that returns a object and accepts the following input parameters:

1. object - The value to be formatted
2. Dictionary<string, object> - The collection of data for the row in question

The anonymous functions and lambda expressions available in newer versions of C# 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) => Convert.ToBoolean(val)
        ? "Done"
        : "To Do";
    )

Formatting reference documentation

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