Contrib.social

Update Date element documentation for #date_date_format and usage for other date types such as time

Open on Drupal.org →
Created on 17 December 2016, over 7 years ago
Updated 21 March 2023, over 1 year ago

Problem/Motivation

The class documentation on Drupal\Core\Render\Element\Date is incomplete, both for documenting properties and functionality. The Date element is used to create both <input type=date> and <input type=time> HTML elements. Other properties, eg ['#attributes']['type'] and ['#date_date_format'], are not documented at the top level. This hinders both people reading the code, and people consulting api.drupal.org for how to use this element.

Proposed resolution

Decide how much non-Drupal specific information to include (eg, document the min and max attributes), and what to refer to for more information (W3C spec? MDN?).

Update the documentation to be thorough, yet concise, based on the existing functionality.

Remaining tasks

Do we need to also mention type=datetime and type=datetime-local?

User interface changes

N/A

API changes

N/A

Data model changes

N/A

Original Report

The documentation for the Date render element is not valid. #default_value should be provided as a Y-m-d string instead of a keyed array as the documentation says.

Currently is says:

/**
 * Provides a form element for date selection.
 *
 * Properties:
 * - #default_value: An array with the keys: 'year', 'month', and 'day'.
 *   Defaults to the current date if no value is supplied.
 *
 * @code
 * $form['expiration'] = array(
 *   '#type' => 'date',
 *   '#title' => $this->t('Content expiration'),
 *   '#default_value' => array('year' => 2020, 'month' => 2, 'day' => 15,)
 * );
 * @endcode
 *
 * @FormElement("date")
 */

which should be

/**
 * Provides a form element for date selection.
 *
 * Properties:
 * - #default_value: A string representing the date formatted as Y-m-d.
 *   Defaults to the current date if no value is supplied.
 *
 * @code
 * $form['expiration'] = array(
 *   '#type' => 'date',
 *   '#title' => $this->t('Content expiration'),
 *   '#default_value' => '2020-02-15',
 * );
 * @endcode
 *
 * @FormElement("date")
 */

The default_value documentation could be improved. In the attached patch I've used "A string formatted as Y-m-d". But for someone not familiar with php date this might not be sufficient?

🐛 Bug report
Status

Needs work

Version

10.1 ✨

Component
Documentation  →

Last updated about 11 hours ago

No maintainer
Created by

🇸🇪Sweden pontus_nilsson Stockholm

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

contrib.social Blog FAQ Discussions
Production build 0.69.0 2024