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

In the case of the Editor libraries, we define the get and set as:

• 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 both take a single parameter - a function that itself will accept two parameters and return 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
• The return value is the formatted value

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 PHP date() method which is used to format date and time strings in the Editor PHP libraries.

• dateSqlToFormat( 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( 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 dateSqlToFormat and dateFormatToSql methods being used to format the string:

Field::inst( 'start_date' )
    ->getFormatter( Format::dateSqlToFormat( 'd-m-Y' ) )
    ->setFormatter( Format::dateFormatToSql( 'd-m-Y' ) )

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

Field::inst( 'name' )->setFormatter( Format::ifEmpty( null ) ),
Field::inst( '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 - The value to be formatted
2. row - The collection of data for the row in question

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

Field::inst( 'status' )
    ->getFormatter( function ( $val, $data ) {
                return $val
                    ? 'Done'
                    : 'To Do';
    } )

PHP API documentation

The PHP API developer documentation for the Editor PHP classes is available for detailed and technical discussion about the methods and classes discussed above.