NEW Hints for scaffolded date/time fields

See http://open.silverstripe.org/ticket/8337 for context.

docs/en/changelogs/3.1.0.md

@@ -427,4 +427,8 @@ you can enable those warnings and future-proof your code already.
 	 `YearlyTask` are deprecated, please extend from `BuildTask` or `CliController`,
 	 and invoke them in self-defined frequencies through Unix cronjobs etc.
  * `i18n::$common_locales` and `i18n::$common_languages` are now accessed via the Config API, and contain associative rather than indexed arrays.
-   Before: `array('de_DE' => array('German', 'Deutsch'))`, after: `array('de_DE' => array('name' => 'German', 'native' => 'Deutsch'))`.
+   Before: `array('de_DE' => array('German', 'Deutsch'))`, after: `array('de_DE' => array('name' => 'German', 'native' => 'Deutsch'))`.
+ * 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)`.

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 

model/fieldtypes/Date.php

@@ -387,6 +387,15 @@ public static function past_date($fmonth, $fday = 1, $fyear = null) {
 	}
 
 	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;
 	}
 }

model/fieldtypes/Datetime.php

@@ -87,7 +87,23 @@ public function URLDatetime() {
 	}
 
 	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;
 	}
 
 	/**

model/fieldtypes/Time.php

@@ -71,7 +71,16 @@ public function requireField() {
 	}
 
 	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;
 	}
 
 }