From f296439a243ef2509628cc545c591fa3924bc2eb Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Mon, 8 Apr 2013 19:38:50 +1200 Subject: [PATCH] NEW Hints for scaffolded date/time fields --- docs/en/changelogs/3.1.0.md | 6 +++++- docs/en/reference/datefield.md | 20 ++++++++++++++++++++ model/fieldtypes/Date.php | 11 ++++++++++- model/fieldtypes/Datetime.php | 18 +++++++++++++++++- model/fieldtypes/Time.php | 11 ++++++++++- 5 files changed, 62 insertions(+), 4 deletions(-) diff --git a/docs/en/changelogs/3.1.0.md b/docs/en/changelogs/3.1.0.md index 4ba8abaad..5f7eeb5b9 100644 --- a/docs/en/changelogs/3.1.0.md +++ b/docs/en/changelogs/3.1.0.md @@ -430,4 +430,8 @@ you can enable those warnings and future-proof your code already. Before: `array('de_DE' => array('German', 'Deutsch'))`, after: `array('de_DE' => array('name' => 'German', 'native' => 'Deutsch'))`. * `SSViewer::current_custom_theme()` has been replaced with the `SSViewer.theme_enabled` configuration setting. Please use it to toggle theme behaviour rather than relying on the custom theme being set in the - (now deprecated) `SSViewer::set_theme()` call. \ No newline at end of file + (now deprecated) `SSViewer::set_theme()` call. + * Scaffolded `DateField`, `TimeField` and `DatetimeField` form field instances automatically include + formatting hints as placeholders and description text below the field itself. + If you change the date/time format of those fields, you need to adjust the hints. + To remove the hints, use `setDescription(null)` and `setAttribute('placeholder', null)`. diff --git a/docs/en/reference/datefield.md b/docs/en/reference/datefield.md index e314e209b..57053c1b8 100644 --- a/docs/en/reference/datefield.md +++ b/docs/en/reference/datefield.md @@ -60,6 +60,26 @@ HTML5 placeholders 'day', 'month' and 'year' are enabled by default. ->setConfig('dmyseparator', '/') // set the separator ->setConfig('dmyplaceholders', 'true'); // enable HTML 5 Placeholders +## Formatting Hints + +Its 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 + $dateField->setDescription(sprintf( + _t('FormField.Example', 'e.g. %s', 'Example format'), + Convert::raw2xml(Zend_Date::now()->toString($dateField->getConfig('dateformat'))) + )); + // Alternatively, set short format as a placeholder in the field + $dateField->setAttribute('placeholder', $dateField->getConfig('dateformat')); + +Note: Fields scaffolded through `[api:DataObject::scaffoldCMSFields()]` automatically +have a description attached to them. + ## Calendar Field The following setting will add a Calendar to a single DateField, using the diff --git a/model/fieldtypes/Date.php b/model/fieldtypes/Date.php index d4f593ff9..6357d2011 100644 --- a/model/fieldtypes/Date.php +++ b/model/fieldtypes/Date.php @@ -387,6 +387,15 @@ class Date extends DBField { } public function scaffoldFormField($title = null, $params = null) { - return new DateField($this->name, $title); + $field = DateField::create($this->name, $title); + + // Show formatting hints for better usability + $field->setDescription(sprintf( + _t('FormField.Example', 'e.g. %s', 'Example format'), + Convert::raw2xml(Zend_Date::now()->toString($field->getConfig('dateformat'))) + )); + $field->setAttribute('placeholder', $field->getConfig('dateformat')); + + return $field; } } diff --git a/model/fieldtypes/Datetime.php b/model/fieldtypes/Datetime.php index 7803d4976..af3f9bf79 100644 --- a/model/fieldtypes/Datetime.php +++ b/model/fieldtypes/Datetime.php @@ -87,7 +87,23 @@ class SS_Datetime extends Date implements TemplateGlobalProvider { } public function scaffoldFormField($title = null, $params = null) { - return new DatetimeField($this->name, $title); + $field = DatetimeField::create($this->name, $title); + + // Show formatting hints for better usability + $dateField = $field->getDateField(); + $dateField->setDescription(sprintf( + _t('FormField.Example', 'e.g. %s', 'Example format'), + Convert::raw2xml(Zend_Date::now()->toString($dateField->getConfig('dateformat'))) + )); + $dateField->setAttribute('placeholder', $dateField->getConfig('dateformat')); + $timeField = $field->getTimeField(); + $timeField->setDescription(sprintf( + _t('FormField.Example', 'e.g. %s', 'Example format'), + Convert::raw2xml(Zend_Date::now()->toString($timeField->getConfig('timeformat'))) + )); + $timeField->setAttribute('placeholder', $timeField->getConfig('timeformat')); + + return $field; } /** diff --git a/model/fieldtypes/Time.php b/model/fieldtypes/Time.php index 7f9e58ea1..39a335571 100644 --- a/model/fieldtypes/Time.php +++ b/model/fieldtypes/Time.php @@ -71,7 +71,16 @@ class Time extends DBField { } public function scaffoldFormField($title = null, $params = null) { - return new TimeField($this->name, $title); + $field = TimeField::create($this->name, $title); + + // Show formatting hints for better usability + $field->setDescription(sprintf( + _t('FormField.Example', 'e.g. %s', 'Example format'), + Convert::raw2xml(Zend_Date::now()->toString($field->getConfig('timeformat'))) + )); + $field->setAttribute('placeholder', $field->getConfig('timeformat')); + + return $field; } }