NEW Hints for scaffolded date/time fields

docs/en/changelogs/3.1.0.md

@@ -431,3 +431,7 @@ you can enable those warnings and future-proof your code already.
  * `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.
+ * 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 @@ 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;
 	}
 }

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;
 	}
 	
 	/**

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;
 	}
 	
 }