public static function Datelist::processDatelist in Drupal 10

Same name and namespace in other branches

8 core/lib/Drupal/Core/Datetime/Element/Datelist.php \Drupal\Core\Datetime\Element\Datelist::processDatelist()
9 core/lib/Drupal/Core/Datetime/Element/Datelist.php \Drupal\Core\Datetime\Element\Datelist::processDatelist()

Expands a date element into an array of individual elements.

Required settings:

#default_value: A DrupalDateTime object, adjusted to the proper local timezone. Converting a date stored in the database from UTC to the local zone and converting it back to UTC before storing it is not handled here. This element accepts a date as the default value, and then converts the user input strings back into a new date object on submission. No timezone adjustment is performed.

Optional properties include:

#date_part_order: Array of date parts indicating the parts and order that should be used in the selector, optionally including 'ampm' for 12 hour time. Default is array('year', 'month', 'day', 'hour', 'minute').
#date_text_parts: Array of date parts that should be presented as text fields instead of drop-down selectors. Default is an empty array.
#date_date_callbacks: Array of optional callbacks for the date element.
#date_year_range: A description of the range of years to allow, like '1900:2050', '-3:+3' or '2000:+3', where the first value describes the earliest year and the second the latest year in the range. A year in either position means that specific year. A +/- value describes a dynamic value that is that many years earlier or later than the current year at the time the form is displayed. Defaults to '1900:2050'.
#date_increment: The increment to use for minutes and seconds, i.e. '15' would show only :00, :15, :30 and :45. Defaults to 1 to show every minute.
#date_timezone: The Time Zone Identifier (TZID) to use when displaying or interpreting dates, i.e: 'Asia/Kolkata'. Defaults to the value returned by date_default_timezone_get().

Example usage:

$form = array(
  '#type' => 'datelist',
  '#default_value' => new DrupalDateTime('2000-01-01 00:00:00'),
  '#date_part_order' => array(
    'month',
    'day',
    'year',
    'hour',
    'minute',
    'ampm',
  ),
  '#date_text_parts' => array(
    'year',
  ),
  '#date_year_range' => '2010:2020',
  '#date_increment' => 15,
  '#date_timezone' => 'Asia/Kolkata',
);

Parameters

array $element: The form element whose value is being processed.

\Drupal\Core\Form\FormStateInterface $form_state: The current state of the form.

array $complete_form: The complete form structure.

Return value

array

File

core/lib/Drupal/Core/Datetime/Element/Datelist.php, line 181

Class

Datelist: Provides a datelist element.

Namespace

Drupal\Core\Datetime\Element

Code

public static function processDatelist(&$element, FormStateInterface $form_state, &$complete_form) {

  // Load translated date part labels from the appropriate calendar plugin.
  $date_helper = new DateHelper();

  // The value callback has populated the #value array.
  $date = !empty($element['#value']['object']) ? $element['#value']['object'] : NULL;
  $element['#tree'] = TRUE;

  // Determine the order of the date elements.
  $order = !empty($element['#date_part_order']) ? $element['#date_part_order'] : [
    'year',
    'month',
    'day',
  ];
  $text_parts = !empty($element['#date_text_parts']) ? $element['#date_text_parts'] : [];

  // Output multi-selector for date.
  foreach ($order as $part) {
    switch ($part) {
      case 'day':
        $options = $date_helper
          ->days($element['#required']);
        $format = 'j';
        $title = t('Day');
        break;
      case 'month':
        $options = $date_helper
          ->monthNamesAbbr($element['#required']);
        $format = 'n';
        $title = t('Month');
        break;
      case 'year':
        $range = static::datetimeRangeYears($element['#date_year_range'], $date);
        $options = $date_helper
          ->years($range[0], $range[1], $element['#required']);
        $format = 'Y';
        $title = t('Year');
        break;
      case 'hour':
        $format = in_array('ampm', $element['#date_part_order']) ? 'g' : 'G';
        $options = $date_helper
          ->hours($format, $element['#required']);
        $title = t('Hour');
        break;
      case 'minute':
        $format = 'i';
        $options = $date_helper
          ->minutes($format, $element['#required'], $element['#date_increment']);
        $title = t('Minute');
        break;
      case 'second':
        $format = 's';
        $options = $date_helper
          ->seconds($format, $element['#required'], $element['#date_increment']);
        $title = t('Second');
        break;
      case 'ampm':
        $format = 'a';
        $options = $date_helper
          ->ampm($element['#required']);
        $title = t('AM/PM');
        break;
      default:
        $format = '';
        $options = [];
        $title = '';
    }
    $default = isset($element['#value'][$part]) && trim($element['#value'][$part]) != '' ? $element['#value'][$part] : '';
    $value = $date instanceof DrupalDateTime && !$date
      ->hasErrors() ? $date
      ->format($format) : $default;
    if (!empty($value) && $part != 'ampm') {
      $value = intval($value);
    }
    $element['#attributes']['title'] = $title;
    $element[$part] = [
      '#type' => in_array($part, $text_parts) ? 'textfield' : 'select',
      '#title' => $title,
      '#title_display' => 'invisible',
      '#value' => $value,
      '#attributes' => $element['#attributes'],
      '#options' => $options,
      '#required' => $element['#required'],
      '#error_no_message' => FALSE,
      '#empty_option' => $title,
    ];
  }

  // Allows custom callbacks to alter the element.
  if (!empty($element['#date_date_callbacks'])) {
    foreach ($element['#date_date_callbacks'] as $callback) {
      $message = sprintf('Datelist element #date_date_callbacks callbacks must be methods of a class that implements \\Drupal\\Core\\Security\\TrustedCallbackInterface or be an anonymous function. The callback was %s. See https://www.drupal.org/node/3217966', Variable::callableToString($callback));
      StaticTrustedCallbackHelper::callback($callback, [
        &$element,
        $form_state,
        $date,
      ], $message);
    }
  }
  return $element;
}

You are here