The dropdown lists for selecting date and time function in the Cotonti

The cot_selectbox_date function in the Cotonti CMS is designed to generate dropdown lists for selecting date and time. These dropdowns can be used on a web page to input date and time data such as year, month, day, hour, and minute. The function returns a string with HTML markup that represents these dropdown lists.

Function behavior overview:

1. Parameters:
   • The function accepts several parameters that allow you to configure how the form is displayed and how the user's timezone is handled.
2. Logic:
   • First, the function checks whether a custom user function cot_selectbox_date_custom exists, and if so, calls it.
   • Next, it checks for plugins via cot_getextplugins, which may affect the result.
   • Then the function retrieves or calculates values for year, month, day, hour, and minute depending on the provided Unix timestamp ($utime).
   • Dropdown lists are created for selecting year, month, day, hour, and minute.
   • A string with HTML markup that displays these lists is returned.

Now let’s examine each parameter in more detail:

Parameters of the cot_selectbox_date function:

1. $utime (int) — Selected time (Unix timestamp):
   • This is a Unix timestamp (the number of seconds since January 1, 1970).
   • If the passed value is 0, the function uses the value entered by the user (if available), or displays an empty value by default.
2. $mode (string, default 'long') — Display mode:
   • Specifies how elements will be displayed in the dropdown lists.
   • 'short' — compact display (for example, for mobile devices or compact forms).
   • 'long' — full display (default). This is a more detailed format.
3. $name (string, default '') — Variable name prefix:
   • This is the name used for all form elements (for example, date[year], date[month], and so on).
   • If the name contains square brackets (for example, date[year]), the function splits it for use in different parts of the form.
4. $max_year (int, default 2030) — Maximum allowed year:
   • Sets the upper bound for the year dropdown list.
   • For example, if $max_year = 2030, the maximum selectable year will be 2030.
5. $min_year (int, default 2000) — Minimum allowed year:
   • Sets the lower bound for the year dropdown list.
   • For example, if $min_year = 2000, the minimum selectable year will be 2000.
6. $usertimezone (bool, default true) — Use user timezone:
   • Indicates whether the user’s timezone should be taken into account when calculating time.
   • If true, the user’s timezone offset ($usr['timezone']) is added to the timestamp.
   • If false, the user’s timezone is ignored and the time is displayed without adjustment.
7. $custom_rc (string, default '') — Custom resource name:
   • Allows passing a custom resource (for example, if a custom template is used for rendering the date).
   • If the value is empty, the standard resource (input_date or its variant depending on other parameters) is used.

How the function works:

• Time calculation: If the timestamp $utime is not equal to 0, it is split into components (year, month, day, hour, minute). If $utime == 0, the system attempts to extract data from previously entered values (for example, stored in a session or cookies).
• Dropdown generation:
  • For each date component (year, month, day, hour, minute), a corresponding dropdown list is generated using the cot_selectbox function. First, a list of available values is created (for example, months, days of the month, hours, etc.), then the default value to be displayed is selected.
• Output resource: Depending on the $mode parameter and other factors, the appropriate HTML template is used for rendering. Finally, the function calls cot_rc, which generates the final HTML markup with the selected date and time values.

Thus, this function helps create a convenient interface for entering date and time on a website, taking into account all settings (user timezone, custom resources, and so on).

The function code itself (system/forms.php):

/**
* Generates date part dropdown
*
* @param int $utime Selected timestamp
* @param string $mode Display mode: 'short' or complete
* @param string $name Variable name preffix
* @param int $max_year Max. year possible
* @param int $min_year Min. year possible
* @param bool $usertimezone Use user timezone
* @param string $custom_rc Custom resource string name
* @return string
*/
function cot_selectbox_date($utime, $mode = 'long', $name = '', $max_year = 2030, $min_year = 2000, $usertimezone = true, $custom_rc = '')
{
   // Global variables are used, for example, for translations and user data
   global $L, $R, $usr;
   // Check whether a custom date selection function exists
   if (function_exists('cot_selectbox_date_custom')) {
       // If it exists, call it and pass all parameters
       return cot_selectbox_date_custom($utime, $mode, $name, $max_year, $min_year, $usertimezone, $custom_rc);
   }
   // Initialize the result variable
   $result = NULL;
   /* === Hook === */
   // External plugins are included here, if any
   foreach (cot_getextplugins('form.date') as $pl) {
       include $pl; // Include each plugin that may affect the date form
   }
   /* ===== */
   // If the result was modified by plugins, return it immediately
   if ($result !== NULL) return $result;
   // Determine the base name for form elements if it has the format "name[year]"
   $rc_name = preg_match('#^(\w+)\[(.*?)\]$#', $name, $mt) ? $mt[1] : $name;
   // If timezone handling is enabled, adjust the time using the user's timezone
   $utime = ($usertimezone && $utime > 0) ? ($utime + $usr['timezone'] * 3600) : $utime;
   // If $utime equals 0, use stored data (for example, from session or cookies)
   if ($utime == 0) {
       // Initialize variables for year, month, day, and time
       list($s_year, $s_month, $s_day, $s_hour, $s_minute) = [null, null, null, null, null];
       
       // Retrieve buffered data, if available
       $buffered = cot_import_buffered($name, null);
       if (is_array($buffered)) {
           $s_year   = $buffered['year'];
           $s_month  = $buffered['month'];
           $s_day    = $buffered['day'];
           $s_hour   = ($buffered['hour'] ?? 0) > 0 ? $buffered['hour'] : 1; // Default hour is 1 if not set
           $s_minute = $buffered['minute'] ?? 0; // Default minute is 0 if not set
       }
   } else {
       // If $utime is not 0, split it into components (year, month, day, hour, minute)
       list($s_year, $s_month, $s_day, $s_hour, $s_minute) = explode('-', @date('Y-m-d-H-i', $utime));
   }
   // Array of months with their names in the site language
   $months = [];
   $months[1] = $L['January'];
   $months[2] = $L['February'];
   $months[3] = $L['March'];
   $months[4] = $L['April'];
   $months[5] = $L['May'];
   $months[6] = $L['June'];
   $months[7] = $L['July'];
   $months[8] = $L['August'];
   $months[9] = $L['September'];
   $months[10] = $L['October'];
   $months[11] = $L['November'];
   $months[12] = $L['December'];
   // Generate the dropdown list for year selection
   $year = cot_selectbox($s_year, $name.'[year]', range($max_year, $min_year, -1));
   // Generate the dropdown list for month selection
   $month = cot_selectbox($s_month, $name.'[month]', array_keys($months), array_values($months));
   // Generate the dropdown list for day selection
   $day = cot_selectbox($s_day, $name.'[day]', range(1, 31));
   // Generate the dropdown list for hour selection (00 to 23)
   $range = [];
   for ($i = 0; $i < 24; $i++) {
       $range[] = sprintf('%02d', $i); // Format hours as two digits
   }
   $hour = cot_selectbox($s_hour, $name.'[hour]', $range);
   // Generate the dropdown list for minute selection (00 to 59)
   $range = [];
   for ($i = 0; $i < 60; $i++) {
       $range[] = sprintf('%02d', $i); // Format minutes as two digits
   }
   $minute = cot_selectbox($s_minute, $name.'[minute]', $range);
   // Prepare the resource name for rendering
   $rc = empty($R["input_date_{$mode}"]) ? 'input_date' : "input_date_{$mode}";
   $rc = empty($R["input_date_{$rc_name}"]) ? $rc : "input_date_{$rc_name}";
   $rc = empty($custom_rc) ? $rc : $custom_rc;
   // Generate the final HTML markup for all date elements
   $result = cot_rc($rc, [
       'day' => $day,
       'month' => $month,
       'year' => $year,
       'hour' => $hour,
       'minute' => $minute
   ]);
   // Return the result
   return $result;
}

Let’s go through each of these points step by step so that you can clearly understand how this code works:

1. Function parameters

The cot_selectbox_date function accepts several parameters that allow you to configure the behavior and appearance of the date and time dropdown lists.

$utime (int) – a timestamp that represents a specific point in time. This value is used to pre-fill the form fields if it is provided. For example, if the value is 1635724800, it corresponds to a specific date and time.

$mode (string) – the display mode, which can be short or long. This determines how the date is displayed (compact or full version). For example, short may show only month and year, while long shows the full date.

$name (string) – the variable name for each form element (year, month, day, hour, minute). For example, if you pass 'date', the generated HTML elements will be named date[year], date[month], and so on.

$max_year (int) – the maximum year that can be selected in the dropdown list. By default, this is 2030.

$min_year (int) – the minimum year that can be selected in the dropdown list. By default, this is 2000.

$usertimezone (bool) – a flag indicating whether the user’s timezone should be taken into account. If true, the time will be adjusted according to the user’s timezone.

$custom_rc (string) – the name of a custom rendering template. If this parameter is provided, it will be used instead of the default one.

These parameters make the function flexible and adaptable to different needs, such as supporting different timezones, customizing appearance, and defining the year range.

2. Plugin inclusion

foreach (cot_getextplugins('form.date') as $pl) {
   include $pl;
}

cot_getextplugins is a function that returns a list of plugins connected to the system via the 'form.date' hook, used for processing date forms. These plugins can add additional functionality or modify the default behavior.

The foreach loop iterates over each connected plugin and includes it using include. This allows the function’s behavior to be extended, for example by adding new fields or handlers.

Using this mechanism, the function’s behavior can be dynamically modified by connecting external modules without changing the core code.

3. Timestamp processing

if ($utime == 0) {
   // Use stored data
} else {
   // Split the timestamp into components
}

If the value of $utime is 0, it means that no date was provided, and the function attempts to restore data from a saved state, for example from a session or database (via cot_import_buffered).

If $utime is not 0, it represents a timestamp, and it is used to extract year, month, day, hour, and minute using the date function with the format 'Y-m-d-H-i'. This is a standard PHP function that returns a string with the required time components.

This logic allows the function to correctly handle cases where a date has not yet been selected, using saved data or the current timestamp.

4. Month array

$months[1] = $L['January'];
$months[2] = $L['February'];

Here, the $months array is created, where each number from 1 to 12 corresponds to a month name.
The month names are taken from the global $L variable, which stores translations for different interface languages.

For example, $L['January'] contains the localized name of the month in the selected language.
This makes the array easily localizable if the interface language needs to be changed.

The array is later used when generating the dropdown list for month selection, where the array keys (1, 2, 3, etc.) are the values and the month names are the displayed labels.

5. Dropdown generation

$year = cot_selectbox($s_year, $name.'[year]', range($max_year, $min_year, -1));
$month = cot_selectbox($s_month, $name.'[month]', array_keys($months), array_values($months));

For each date component (year, month, day, hour, minute), dropdown lists are created using the cot_selectbox function. This function generates the HTML markup for a <select> element.

For the year, a range from $max_year down to $min_year is generated with a step of -1, meaning the list is sorted in descending order.

For the month, the list contains the 12 months defined in the $months array.

For the day, the list ranges from 1 to 31 (all possible days of a month).

For the hour, the list ranges from 00 to 23 (all possible hours).

For the minute, the list ranges from 00 to 59 (all possible minutes).

Each call to cot_selectbox generates HTML code for the corresponding dropdown list with a preselected value, which is either passed directly to the function or retrieved from stored data.

6. Rendering using templates

$rc = empty($R["input_date_{$mode}"]) ? 'input_date' : "input_date_{$mode}";
$rc = empty($R["input_date_{$rc_name}"]) ? $rc : "input_date_{$rc_name}";
$rc = empty($custom_rc) ? $rc : $custom_rc;
$result = cot_rc($rc, [
   'day' => $day,
   'month' => $month,
   'year' => $year,
   'hour' => $hour,
   'minute' => $minute
]);

Here, the template name used for rendering the form is determined. First, it checks whether a template exists for the selected $mode (for example, input_date_short, input_date_long) in the global $R variable.

Then, if the user provided a custom template name via $custom_rc, it is used. Otherwise, the standard template is selected.

cot_rc is a function that processes the template and replaces placeholders with actual data. In this case, it passes an array containing all dropdown lists (day, month, year, hour, minute) to the selected template.

Rendering allows the form to be displayed in the required format, based on localization and selected parameters.

7. Returning the result

return $result;

Finally, the function returns a string with HTML markup that includes all dropdown lists for selecting date and time.

This result is inserted into the page, allowing the user to select date and time via these form elements.

Conclusion:

The cot_selectbox_date function provides a convenient and flexible way to display a date and time selection form with support for timezones and localization. It uses plugins for extensibility, allows customization of appearance through templates, and works with time data such as timestamps or saved values.