Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

HTML5 Date Fields #6766

Merged
merged 7 commits into from
Apr 3, 2017
Merged

HTML5 Date Fields #6766

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ac6d4f3
Move DateField->placeholders to subclass
chillu Mar 30, 2017
326aa37
API HTML5 date/time fields, remove member prefs (fixes #6626)
chillu Mar 30, 2017
3b94d14
MERGE
chillu Apr 3, 2017
a70de91
Fix DatetimeFieldTest
chillu Apr 3, 2017
e969346
Fixed tests
chillu Apr 3, 2017
5b2106a
Corrected i18n docs
chillu Apr 3, 2017
e3fbd1d
Fixed coding conventions
chillu Apr 3, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 13 additions & 46 deletions docs/en/02_Developer_Guides/03_Forms/Field_types/02_DateField.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,11 @@ summary: How to format and use the DateField class.
# DateField

This `FormField` subclass lets you display an editable date, in a single text input field.
It also provides a calendar date picker.
It implements the [HTML5 input date type](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date)
(with `type=date`). In supported browsers, this will cause a localised date picker to appear for users.
HTML5 date fields present and save ISO 8601 date formats (`y-MM-dd`),
since the browser takes care of converting to/from a localised presentation.
Browsers without support receive an `<input type=text>` based polyfill.

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

Expand Down Expand Up @@ -34,65 +38,28 @@ The following example will add a simple DateField to your Page, allowing you to
## Custom Date Format

A custom date format for a [api:DateField] can be provided through `setDateFormat`.
This is only necessary if you want to opt-out of the built-in browser localisation via `type=date`.

:::php
// will display a date in the following format: 31-06-2012
DateField::create('MyDate')->setDateFormat('dd-MM-yyyy');
// will display a date in the following format: 31/06/2012
DateField::create('MyDate')
->setHTML5(false)
->setDateFormat('dd/MM/yyyy');

<div class="info" markdown="1">
The formats are based on [CLDR format](http://userguide.icu-project.org/formatparse/datetime).
The formats are based on [ICU format](http://www.icu-project.org/apiref/icu4c/classSimpleDateFormat.html#details).
</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()).
`strtotime()`).

:::php
DateField::create('MyDate')
->setMinDate('-7 days')
->setMaxDate'2012-12-31')

## Separate Day / Month / Year Fields

To display separate input fields for day, month and year separately you can use the `SeparatedDateField` subclass`.
HTML5 placeholders 'day', 'month' and 'year' are enabled by default.

:::php
SeparatedDateField::create('MyDate');

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

It is recommended to use numeric format, as `MMM` or `MMMM` month names may not always pass validation.

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)
->setMaxDate('2012-12-31')

## Formatting Hints

Expand Down
45 changes: 18 additions & 27 deletions docs/en/02_Developer_Guides/13_i18n/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,18 +71,24 @@ and default alignment of paragraphs and tables to browsers.

### Date and time formats

Formats can be set globally in the i18n class. These settings are currently only picked up by the CMS, you'll need
to write your own logic for any frontend output.
Formats can be set globally in the i18n class.
You can use these settings for your own view logic.

:::php
Config::inst()->update('i18n', 'date_format', 'dd.MM.YYYY');
Config::inst()->update('i18n', 'time_format', 'HH:mm');

Most localization routines in SilverStripe use the [Zend_Date API](http://framework.zend.com/manual/1.12/en/zend.date.overview.html).
This means all formats are defined in
[ISO date format](http://framework.zend.com/manual/1.12/en/zend.date.constants.html),
Localization in SilverStripe uses PHP's [intl extension](http://php.net/intl).
Formats for it's [IntlDateFormatter](http://php.net/manual/en/class.intldateformatter.php)
are defined in [ICU format](http://www.icu-project.org/apiref/icu4c/classSimpleDateFormat.html#details),
not PHP's built-in [date()](http://nz.php.net/manual/en/function.date.php).

These settings are not used for CMS presentation.
Users can choose their own locale, which determines the date format
that gets presented to them. Currently this is a mix of PHP defaults (for readonly `DateField` and `TimeField`),
browser defaults (for `DateField` on browsers supporting HTML5), and [Moment.JS](http://momentjs.com/)
client-side logic (for `DateField` polyfills and other readonly dates and times).

### Language Names

SilverStripe comes with a built-in list of common languages, listed by locale and region.
Expand Down Expand Up @@ -126,32 +132,17 @@ Please refer to [W3C: Introduction to IDN and IRI](http://www.w3.org/Internation

### i18n in Form Fields

Date- and time related form fields support i18n ([api:DateField], [api:TimeField], [api:DatetimeField]).

:::php
i18n::set_locale('ca_AD');
$field = new DateField(); // will automatically set date format defaults for 'ca_AD'
$field->setLocale('de_DE'); // will not update the date formats
$field->setConfig('dateformat', 'dd. MMMM YYYY'); // sets typical 'de_DE' date format, shows as "23. Juni 1982"

Defaults can be applied globally for all field instances through the `DateField.default_config`
and `TimeField.default_config` [configuration arrays](/developer_guides/configuration).
If no 'locale' default is set on the field, [api:i18n::get_locale()] will be used.

**Important:** Form fields in the CMS are automatically configured according to the profile settings for the logged-in user (`Member->Locale`, `Member->DateFormat` and `Member->TimeFormat`). This means that in most cases,
fields created through [api:DataObject::getCMSFields()] will get their i18n settings from a specific member
Date and time related form fields are automatically localised ([api:DateField], [api:TimeField], [api:DatetimeField]).
Since they use HTML5 `type=date` and `type=time` fields by default, these fields will present dates
in a localised format chosen by the browser and operating system.

The [api:DateField] API can be enhanced by JavaScript, and comes with
[jQuery UI datepicker](http://jqueryui.com/demos/datepicker/) capabilities built-in.
The field tries to translate the date formats and locales into a format compatible with jQuery UI
(see [api:DateField_View_JQuery::$locale_map_] and [api:DateField_View_JQuery::convert_iso_to_jquery_format()]).
Fields can be forced to use a certain locale and date/time format by calling `setHTML5(false)`,
followed by `setLocale()` or `setDateFormat()`/`setTimeFormat()`.

:::php
$field = new DateField();
$field->setLocale('de_AT'); // set Austrian/German locale
$field->setConfig('showcalendar', true);
$field->setConfig('jslocale', 'de'); // jQuery UI only has a generic German localization
$field->setConfig('dateformat', 'dd. MMMM YYYY'); // will be transformed to 'dd. MM yy' for jQuery
$field->setLocale('de_AT'); // set Austrian/German locale, defaulting format to dd.MM.y
$field->setDateFormat('d.M.y'); // set a more specific date format (single digit day/month)

## Translating text

Expand Down
33 changes: 27 additions & 6 deletions docs/en/04_Changelogs/4.0.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -398,6 +398,19 @@ In templates this can also be invoked as below:
<%t MyObject.PLURALS 'An item|{count} items' count=$Count %>


#### Removed Member.DateFormat and Member.TimeFormat database settings

We're using [native HTML5 date and time pickers](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date)
in `DateField` and `TimeField` now ([discussion](https://github.com/silverstripe/silverstripe-framework/issues/6626)),
where the browser localises the output based on the browser/system preferences.
In this context it no longer makes sense to give users control over their own
date and time formats in their CMS profile.
Consequently, we've also removed `MemberDatetimeOptionsetField`.

`Member->getDateFormat()` and `Member->getTimeFormat()` still exist, and default to
the [IntlDateFormatter defaults](http://php.net/manual/en/class.intldateformatter.php) for the selected locale.


#### New asset storage mechanism

File system has been abstracted into an abstract interface. By default, the out of the box filesystem
Expand Down Expand Up @@ -1495,19 +1508,25 @@ New `DatetimeField` methods replace `getConfig()` / `setConfig()`:

New `DateField` methods replace `getConfig()` / `setConfig()`:

* `getShowCalendar()` / `setShowCalendar()`
* `getDateFormat()` / `setShowCalendar()`
* `getDateFormat()` / `setDateFormat()`
* `getMinDate()` / `setMinDate()`
* `getMaxDate()` / `setMaxDate()`
* `getPlaceholders()` / `setPlaceholders()`
* `getClientLocale` / `setClientLocale`
* `getLocale()` / `setLocale()`
* option `dmyfields` is now superceded with an `SeparatedDateField` class

The `DateField` has changed behavior:

* `DateField` no longer provides a jQuery UI date picker (`showcalendar` option),
and uses [HTML5 date pickers](https://www.wufoo.com/html5/types/4-date.html) by default instead.
* `DateField` provides an optional polyfill for
[browsers without HTML5 date picker support](http://caniuse.com/#feat=input-datetime)
* The `dmyfields` option has been replced with native HTML5 behaviour (as one single `<input type=date>`).
* `getClientLocale` / `setClientLocale` have been removed (handled by `DateField->locale` and browser settings)

New `TimeField` methods replace `getConfig()` / `setConfig()`

* `getTimeFormat()` / `setTimeFormat()`
* `getLocale()` / `setLocale()`
* `getClientConfig()` has been removed (in favour of `setHTML5()`)

#### <a name="overview-template-removed"></a>Template and Form Removed API
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need to add notes on the removal of MemberDatetimeOptionsetField to this section.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe mention DateField_View_JQuery too here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done


Expand Down Expand Up @@ -1549,7 +1568,9 @@ New `TimeField` methods replace `getConfig()` / `setConfig()`
* `set_source_file_comments()`
* `get_source_file_comments()`
* `getOption`
* `setOption`
* `setOption`
* Removed `MemberDatetimeOptionsetField` (no replacement)
* Removed `DateField_View_JQuery` (replaced with native HTML5 support in `DateField`)

### <a name="overview-i18n"></a>i18n API

Expand Down
Loading