2014-10-19 10:32:34 +02:00
|
|
|
title: DateField
|
|
|
|
summary: How to format and use the DateField class.
|
|
|
|
|
|
|
|
# DateField
|
|
|
|
|
2017-02-14 06:19:09 +01:00
|
|
|
This `FormField` subclass lets you display an editable date, in a single text input field.
|
|
|
|
It also provides a calendar date picker.
|
2014-10-19 10:32:34 +02:00
|
|
|
|
|
|
|
The following example will add a simple DateField to your Page, allowing you to enter a date manually.
|
|
|
|
|
|
|
|
**mysite/code/Page.php**
|
|
|
|
|
|
|
|
:::php
|
|
|
|
<?php
|
|
|
|
|
|
|
|
class Page extends SiteTree {
|
|
|
|
|
|
|
|
private static $db = array(
|
|
|
|
'MyDate' => 'Date',
|
|
|
|
);
|
|
|
|
|
|
|
|
public function getCMSFields() {
|
|
|
|
$fields = parent::getCMSFields();
|
|
|
|
|
|
|
|
$fields->addFieldToTab(
|
|
|
|
'Root.Main',
|
|
|
|
DateField::create('MyDate', 'Enter a date')
|
|
|
|
);
|
|
|
|
|
|
|
|
return $fields;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
## Custom Date Format
|
|
|
|
|
2017-02-14 06:19:09 +01:00
|
|
|
A custom date format for a [api:DateField] can be provided through `setDateFormat`.
|
2014-10-19 10:32:34 +02:00
|
|
|
|
|
|
|
:::php
|
|
|
|
// will display a date in the following format: 31-06-2012
|
2017-01-26 05:20:08 +01:00
|
|
|
DateField::create('MyDate')->setDateFormat('dd-MM-yyyy');
|
2014-10-19 10:32:34 +02:00
|
|
|
|
|
|
|
<div class="info" markdown="1">
|
2017-02-14 06:19:09 +01:00
|
|
|
The formats are based on [CLDR format](http://userguide.icu-project.org/formatparse/datetime).
|
2014-10-19 10:32:34 +02:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
## Min and Max Dates
|
|
|
|
|
|
|
|
Sets the minimum and maximum allowed date values using the `min` and `max` configuration settings (in ISO format or
|
|
|
|
strtotime()).
|
|
|
|
|
|
|
|
:::php
|
|
|
|
DateField::create('MyDate')
|
2017-02-14 06:19:09 +01:00
|
|
|
->setMinDate('-7 days')
|
|
|
|
->setMaxDate'2012-12-31')
|
2014-10-19 10:32:34 +02:00
|
|
|
|
|
|
|
## Separate Day / Month / Year Fields
|
|
|
|
|
2017-02-14 06:19:09 +01:00
|
|
|
To display separate input fields for day, month and year separately you can use the `DateFieldSeparated` subclass`.
|
|
|
|
HTML5 placeholders 'day', 'month' and 'year' are enabled by default.
|
2014-10-19 10:32:34 +02:00
|
|
|
|
|
|
|
:::php
|
2017-02-14 06:19:09 +01:00
|
|
|
DateFieldSeparated::create('MyDate');
|
2014-10-19 10:32:34 +02:00
|
|
|
|
|
|
|
<div class="alert" markdown="1">
|
|
|
|
Any custom date format settings will be ignored.
|
|
|
|
</div>
|
|
|
|
|
|
|
|
## Calendar Picker
|
|
|
|
|
|
|
|
The following setting will add a Calendar to a single DateField, using the jQuery UI DatePicker widget.
|
|
|
|
|
|
|
|
:::php
|
|
|
|
DateField::create('MyDate')
|
2017-02-14 06:19:09 +01:00
|
|
|
->setShowCalendar(true);
|
|
|
|
|
|
|
|
The jQuery date picker will support most custom locale formats (if left as default).
|
|
|
|
If setting an explicit date format via setDateFormat() then the below table of supported
|
|
|
|
characters should be used.
|
2014-10-19 10:32:34 +02:00
|
|
|
|
2017-02-14 06:19:09 +01:00
|
|
|
It is recommended to use numeric format, as `MMM` or `MMMM` month names may not always pass validation.
|
2014-10-19 10:32:34 +02:00
|
|
|
|
|
|
|
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)
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
:::php
|
|
|
|
$dateField = DateField::create('MyDate');
|
|
|
|
|
|
|
|
// Show long format as text below the field
|
2017-02-14 06:19:09 +01:00
|
|
|
$dateField->setDescription(_t(
|
|
|
|
'FormField.Example',
|
|
|
|
'e.g. {format}',
|
|
|
|
[ 'format' => $dateField->getDateFormat() ]
|
2014-10-19 10:32:34 +02:00
|
|
|
));
|
|
|
|
|
|
|
|
// Alternatively, set short format as a placeholder in the field
|
2017-02-14 06:19:09 +01:00
|
|
|
$dateField->setAttribute('placeholder', $dateField->getDateFormat());
|
2014-10-19 10:32:34 +02:00
|
|
|
|
|
|
|
<div class="notice" markdown="1">
|
2016-02-17 22:21:59 +01:00
|
|
|
Fields scaffolded through [api:DataObject::scaffoldCMSFields()] automatically have a description attached to them.
|
2014-10-19 10:32:34 +02:00
|
|
|
</div>
|
|
|
|
|
|
|
|
## API Documentation
|
|
|
|
|
2016-02-17 22:21:59 +01:00
|
|
|
* [api:DateField]
|