This document contains information for an outdated version (3.1) and may not be maintained any more. If some of your projects still use this version, consider upgrading as soon as possible.


This FormField subclass lets you display an editable date, either in a single text input field, or in three separate fields for day, month and year. It also provides a calendar date picker.

The following example will add a simple DateField to your Page, allowing you to enter a date manually.



class Page extends SiteTree {

    private static $db = array(
        'MyDate' => 'Date',

    public function getCMSFields() {
        $fields = parent::getCMSFields();

            DateField::create('MyDate', 'Enter a date')

        return $fields;

Custom Date Format

A custom date format for a DateField can be provided through setConfig.

// will display a date in the following format: 31-06-2012
DateField::create('MyDate')->setConfig('dateformat', 'dd-MM-yyyy'); 

The formats are based on Zend_Date constants.

Min and Max Dates

Sets the minimum and maximum allowed date values using the min and max configuration settings (in ISO format or strtotime()).

    ->setConfig('min', '-7 days')
    ->setConfig('max', '2012-12-31')

Separate Day / Month / Year Fields

The following setting will display your DateField as three input fields for day, month and year separately. HTML5 placeholders 'day', 'month' and 'year' are enabled by default.

    ->setConfig('dmyfields', true)
    ->setConfig('dmyseparator', '/') // set the separator
    ->setConfig('dmyplaceholders', 'true'); // enable HTML 5 Placeholders

Any custom date format settings will be ignored.

Calendar Picker

The following setting will add a Calendar to a single DateField, using the jQuery UI DatePicker widget.

    ->setConfig('showcalendar', true);

The jQuery DatePicker doesn't support every constant available for Zend_Date. If you choose to use the calendar, the following constants should at least be safe:

Constant xxxxx
d numeric day of the month (without leading zero)
dd numeric day of the month (with leading zero)
EEE dayname, abbreviated
EEEE dayname
M numeric month of the year (without leading zero)
MM numeric month of the year (with leading zero)
MMM monthname, abbreviated
MMMM monthname
y year (4 digits)
yy year (2 digits)
yyyy year (4 digits)

Unfortunately the day- and monthname values in Zend Date do not always match those in the existing jQuery UI locale files, so constants like EEE or MMM, for day and month names could break validation. To fix this we had to slightly alter the jQuery locale files, situated in /framework/thirdparty/jquery-ui/datepicker/i18n/, to match Zend_Date.

At this moment not all locale files may be present. If a locale file is missing, the DatePicker calendar will fallback to 'yyyy-MM-dd' whenever day - and/or monthnames are used. After saving, the correct format will be displayed.

Formatting Hints

It's often not immediate apparent which format a field accepts, and showing the technical format (e.g. HH:mm:ss) is of limited use to the average user. An alternative is to show the current date in the desired format alongside the field description as an example.

$dateField = DateField::create('MyDate');

// Show long format as text below the field
    _t('FormField.Example', 'e.g. %s', 'Example format'),

// Alternatively, set short format as a placeholder in the field
$dateField->setAttribute('placeholder', $dateField->getConfig('dateformat'));
Fields scaffolded through DataObject::scaffoldCMSFields automatically have a description attached to them.

API Documentation

Was this article helpful?