Formatters - legacy

The following documentation is for Editor's PHP libraries prior to v1.7 which introduced a more functional approach to the formatting values, providing better integration with IDE auto-completion and matching the PHP and .NET libraries for Editor. If you are developing a new project, please refer to the current formatting documentation, but also be aware that care has been taken to ensure that the 1.7 libraries remain compatible with the older style of formatter setup.

If you decide to update your 1.6 or earlier formatters to 1.7, normally this is simply a case of removing the quotes around the function string, adding parenthesis, and if any parameters were passed in, they should become arguments for the new formatter function - e.g.

->setFormatter( 'Format::ifEmpty', null );

would become:

->setFormatter( Format::ifEmpty( null ) );

The remainder of this document relates to the legacy formatting style only.

Formatter methods

Each Field instance has a getFormatter() and setFormatter() methods, both of which accept identical options, the only difference is the direction of data traversal upon which they apply their formatting rules, as described above. These methods can be given two parameters:

The formatter function to run
The formatter options

Formatter function

The formatter function given is either a function defined as a member of the Editor Format class, or a closure function which you can provide to perform custom formatting. As an example of each (note only a getFormatter is shown here for brevity, although normally a get and set formatter would be used in unison):

// Use the `datetime` formatter method
Field::inst( 'update_time' )
    ->getFormatter( 'Format::datetime', Format::DATE_ISO_8601 )

// Use a custom formatter through a closure
Field::inst( 'restore_time' )->getFormatter( function ( $val, $data, $opts ) {
    return date( 'Y-m-d', strtotime( $val ) );
} );

The formatter methods have the following signature:

Parameter 1: $val - The value to format
Parameter 2: $data - The whole data set that was submitted (useful for multiple field formatting)
Parameter 3: $opts - Formatter options (see below)
Return: The formatted value

Options

The second parameter passed into the getFormatter and setFormatter methods is optional, and can be used to customise the formatting options for the field. The exact options that are available depend upon the formatter function being used - see below for the built in options.

Ready to use formatters

Arrays

implode - 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 |
explode - Convert a string of values into an array for use with checkboxes.
- Option: The delimiter to use - default |

Dates and times

date_sql_to_format - Convert from SQL date / date time format (ISO 8601) to a format given by the options parameter.
- Option: The format to convert to using the PHP date() format options.
date_format_to_sql - 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 using the PHP date() format options.
datetime - Convert from one date / time format to another
- Option: Associative array with the parameters from and to which are the date formats to convert between using PHP date() format options.

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 - 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 - 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.

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
Format::DATE_TIMESTAMP (U) - Date format: 1331251200
Format::DATE_EPOCH (U) - Date format: 1331251200

Examples

Date time formatter:

Field::inst( 'start_date' )
    ->getFormatter( 'Format::date_sql_to_format', Format::DATE_ISO_8601 )
    ->setFormatter( 'Format::date_format_to_sql', Format::DATE_ISO_8601 )

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 )

Complete Editor example with formatter methods applied:

Editor::inst( $db, 'datatables-demo' )
    ->fields(
        Field::inst( 'first_name' )->validator( 'Validate::notEmpty' ),
        Field::inst( 'last_name' )->validator( 'Validate::notEmpty' ),
        Field::inst( 'position' ),
        Field::inst( 'email' ),
        Field::inst( 'office' ),
        Field::inst( 'extn' )->validator( 'Validate::numeric' ),
        Field::inst( 'age' )->validator( 'Validate::numeric' ),
        Field::inst( 'salary' )->validator( 'Validate::numeric' ),
        Field::inst( 'start_date' )
            ->validator( 'Validate::dateFormat', array(
                "format"  => Format::DATE_ISO_8601,
                "message" => "Please enter a date in the format yyyy-mm-dd"
            ) )
            ->getFormatter( 'Format::date_sql_to_format', Format::DATE_ISO_8601 )
            ->setFormatter( 'Format::date_format_to_sql', Format::DATE_ISO_8601 )
    )
    ->process( $_POST )
    ->json();

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.