diff --git a/core/lib/Drupal/Core/Datetime/Element/DateElementBase.php b/core/lib/Drupal/Core/Datetime/Element/DateElementBase.php index e5303340624d5376952c54b4a1227b964acbba9a..acf9e42e7a085f2a2ad80145d2522cb95a3ee623 100644 --- a/core/lib/Drupal/Core/Datetime/Element/DateElementBase.php +++ b/core/lib/Drupal/Core/Datetime/Element/DateElementBase.php @@ -8,6 +8,48 @@ /** * Provides a base class for date elements. + * + * Date elements are a subset of render elements, representing elements for + * HTML forms, which can be referenced in form arrays. See the + * + * @link theme_render Render API topic @endlink for an overview of render + * arrays and render elements, and the @link form_api Form API topic @endlink + * for an overview of forms and form arrays. + * + * This is a list of the properties that are available for all date elements. + * Properties specific to a particular element are documented on that element's + * class. + * + * List of properties that are used during the rendering and form processing of + * date elements, + * - #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. + * - #date_date_callbacks: (optional) 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. Used in HTML5 min/max date settings. Defaults to + * '1900:2050'. + * - #date_increment: (optional) The interval (step) to use when incrementing or + * decrementing time, in seconds. For example, if this value is set to 30, + * time increases (or decreases) in steps of 30 seconds (00:00:00, 00:00:30, + * 00:01:00, and so on.) If this value is a multiple of 60, the + * "seconds"-component will not be shown in the input. Used for HTML5 step + * values. Defaults to 1 to show every second. + * - #date_timezone: (optional) 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(). + * + * @see \Drupal\Core\Render\Element\RenderElementBase() + * @see \Drupal\Core\Datetime\Element\Datelist() + * @see \Drupal\Core\Datetime\Element\Datetime() */ abstract class DateElementBase extends FormElementBase { diff --git a/core/lib/Drupal/Core/Datetime/Element/Datelist.php b/core/lib/Drupal/Core/Datetime/Element/Datelist.php index c80ac0e33d86d0f95235fc7eca105228f0722120..e1cd8e7142d5add4d62a7d892be0270f497576dc 100644 --- a/core/lib/Drupal/Core/Datetime/Element/Datelist.php +++ b/core/lib/Drupal/Core/Datetime/Element/Datelist.php @@ -13,7 +13,50 @@ use Drupal\Core\Security\StaticTrustedCallbackHelper; /** - * Provides a datelist element. + * Provides a element for selecting the parts of a date from a list. + * + * Properties: + * - #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. + * - #date_part_order: (optional) 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 ['year', 'month', 'day', 'hour', 'minute']. + * - #date_text_parts: (optional) Array of date parts that should be presented + * as text fields instead of drop-down selectors. Default is an empty array. + * - #date_date_callbacks: (optional) Array of optional callbacks for the date + * element. + * - #date_year_range: (optional) 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: (optional) 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: (optional) 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: + * + * @code + * $form = [ + * '#type' => 'datelist', + * '#default_value' => new DrupalDateTime('2000-01-01 00:00:00'), + * '#date_part_order' => ['month', 'day', 'year', 'hour', 'minute', 'ampm'], + * '#date_text_parts' => ['year'], + * '#date_year_range' => '2010:2020', + * '#date_increment' => 15, + * '#date_timezone' => 'Asia/Kolkata' + * ]; + * @endcode + * + * @see \Drupal\Core\Datetime\Element\Datetime() */ #[FormElement('datelist')] class Datelist extends DateElementBase { @@ -130,47 +173,7 @@ public static function valueCallback(&$element, $input, FormStateInterface $form } /** - * 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 ['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: - * @code - * $form = [ - * '#type' => 'datelist', - * '#default_value' => new DrupalDateTime('2000-01-01 00:00:00'), - * '#date_part_order' => ['month', 'day', 'year', 'hour', 'minute', 'ampm'], - * '#date_text_parts' => ['year'], - * '#date_year_range' => '2010:2020', - * '#date_increment' => 15, - * '#date_timezone' => 'Asia/Kolkata' - * ]; - * @endcode + * Expands this element into an array of individual elements. * * @param array $element * The form element whose value is being processed. diff --git a/core/lib/Drupal/Core/Datetime/Element/Datetime.php b/core/lib/Drupal/Core/Datetime/Element/Datetime.php index 98d8e045d316f5364ee60aaf6f6c51ebf1686199..bbdc31cc37f99888a3b82447e522388554713587 100644 --- a/core/lib/Drupal/Core/Datetime/Element/Datetime.php +++ b/core/lib/Drupal/Core/Datetime/Element/Datetime.php @@ -12,7 +12,76 @@ use Drupal\Core\Security\StaticTrustedCallbackHelper; /** - * Provides a datetime element. + * Provides a date and time element. + * + * Properties: + * - #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. + * - #date_date_format: A date format string that describes the + * format that should be displayed to the end user for the date. When using + * HTML5 elements the format MUST use the appropriate HTML5 format for that + * element, no other format will work. See the + * DateFormatterInterface::format() function for a list of the possible + * formats and HTML5 standards for the HTML5 requirements. Defaults to the + * right HTML5 format for the chosen element if an HTML5 element is used, + * otherwise defaults to DateFormat::load('html_date')->getPattern(). + * - #date_date_element: (optional) The date element. Options are: + * - datetime: Use the HTML5 datetime element type. + * - datetime-local: Use the HTML5 datetime-local element type. + * - date: Use the HTML5 date element type. + * - text: No HTML5 element, use a normal text field. + * - none: Do not display a date element. + * - #date_date_callbacks: (optional) Array of optional callbacks for the date + * element. + * - #date_time_element: (optional)The time element. Options are: + * - time: Use an HTML5 time element type. + * - text: No HTML5 element, use a normal text field. + * - none: Do not display a time element. + * - #date_time_format: (optional)A date format string that describes the format + * that should be displayed to the end user for the time. When using HTML5 + * elements the format MUST use the appropriate HTML5 format for that element, + * no other format will work. See the DateFormatterInterface::format() + * function for a list of the possible formats and HTML5 standards for the + * HTML5 requirements. Defaults to the right HTML5 format for the chosen + * element if an HTML5 element is used, otherwise defaults to + * DateFormat::load('html_time')->getPattern(). + * - #date_time_callbacks: (optional) An array of callbacks for the time + * element. Can be used to add a jQuery timepicker or an 'All day' checkbox. + * - #date_year_range: (optional) 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. Used in HTML5 min/max date settings. Defaults to + * '1900:2050'. + * - #date_increment: (optional)The interval (step) to use when incrementing or + * decrementing time, in seconds. For example, if this value is set to 30, + * time increases (or decreases) in steps of 30 seconds (00:00:00, 00:00:30, + * 00:01:00, and so on.) If this value is a multiple of 60, the + * "seconds"-component will not be shown in the input. Used for HTML5 step + * values. Defaults to 1 to show every second. + * - #date_timezone: (optional)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: + * + * @code + * $form = [ + * '#type' => 'datetime', + * '#default_value' => new DrupalDateTime('2000-01-01 00:00:00'), + * '#date_date_element' => 'date', + * '#date_time_element' => 'none', + * '#date_year_range' => '2010:+3', + * '#date_timezone' => 'Asia/Kolkata', + * ]; + * @endcode + * + * @see \Drupal\Core\Datetime\Element\Datelist() */ #[FormElement('datetime')] class Datetime extends DateElementBase { @@ -132,91 +201,6 @@ public static function valueCallback(&$element, $input, FormStateInterface $form /** * Expands a datetime element type into date and/or time elements. * - * All form elements are designed to have sane defaults so any or all can be - * omitted. Both the date and time components are configurable so they can be - * output as HTML5 datetime elements or not, as desired. - * - * Examples of possible configurations include: - * HTML5 date and time: - * #date_date_element = 'date'; - * #date_time_element = 'time'; - * HTML5 datetime: - * #date_date_element = 'datetime'; - * #date_time_element = 'none'; - * HTML5 time only: - * #date_date_element = 'none'; - * #date_time_element = 'time' - * Non-HTML5: - * #date_date_element = 'text'; - * #date_time_element = 'text'; - * - * 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_date_format: A date format string that describes the format that - * should be displayed to the end user for the date. When using HTML5 - * elements the format MUST use the appropriate HTML5 format for that - * element, no other format will work. See the - * DateFormatterInterface::format() function for a list of the possible - * formats and HTML5 standards for the HTML5 requirements. Defaults to the - * right HTML5 format for the chosen element if an HTML5 element is used, - * otherwise defaults to DateFormat::load('html_date')->getPattern(). - * - #date_date_element: The date element. Options are: - * - datetime: Use the HTML5 datetime element type. - * - datetime-local: Use the HTML5 datetime-local element type. - * - date: Use the HTML5 date element type. - * - text: No HTML5 element, use a normal text field. - * - none: Do not display a date element. - * - #date_date_callbacks: Array of optional callbacks for the date element. - * - #date_time_element: The time element. Options are: - * - time: Use an HTML5 time element type. - * - text: No HTML5 element, use a normal text field. - * - none: Do not display a time element. - * - #date_time_format: A date format string that describes the format that - * should be displayed to the end user for the time. When using HTML5 - * elements the format MUST use the appropriate HTML5 format for that - * element, no other format will work. See the - * DateFormatterInterface::format() function for a list of the possible - * formats and HTML5 standards for the HTML5 requirements. Defaults to the - * right HTML5 format for the chosen element if an HTML5 element is used, - * otherwise defaults to DateFormat::load('html_time')->getPattern(). - * - #date_time_callbacks: An array of optional callbacks for the time - * element. Can be used to add a jQuery timepicker or an 'All day' - * checkbox. - * - #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. Used in HTML5 min/max date - * settings. Defaults to '1900:2050'. - * - #date_increment: The interval (step) to use when incrementing or - * decrementing time, in seconds. For example, if this value is set to 30, - * time increases (or decreases) in steps of 30 seconds (00:00:00, - * 00:00:30, 00:01:00, and so on.) If this value is a multiple of 60, the - * "seconds"-component will not be shown in the input. Used for HTML5 step - * values. Defaults to 1 to show every second. - * - #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: - * @code - * $form = [ - * '#type' => 'datetime', - * '#default_value' => new DrupalDateTime('2000-01-01 00:00:00'), - * '#date_date_element' => 'date', - * '#date_time_element' => 'none', - * '#date_year_range' => '2010:+3', - * '#date_timezone' => 'Asia/Kolkata', - * ]; - * @endcode - * * @param array $element * The form element whose value is being processed. * @param \Drupal\Core\Form\FormStateInterface $form_state diff --git a/core/lib/Drupal/Core/Render/Element/File.php b/core/lib/Drupal/Core/Render/Element/File.php index df50492a9ec4d6f4a207b00b9f90d35feff23eea..0c442665bd20f0866ecf5a1745238fae75e612f8 100644 --- a/core/lib/Drupal/Core/Render/Element/File.php +++ b/core/lib/Drupal/Core/Render/Element/File.php @@ -19,6 +19,14 @@ * The value of this form element will always be an array of * \Symfony\Component\HttpFoundation\File\UploadedFile objects, regardless of * whether #multiple is TRUE or FALSE + * + * Usage example: + * @code + * $form['file'] = [ + * '#type' => 'file', + * '#title' => $this->t('File to Upload'), + * ]; + * @endcode */ #[FormElement('file')] class File extends FormElementBase { diff --git a/core/lib/Drupal/Core/Render/Element/Form.php b/core/lib/Drupal/Core/Render/Element/Form.php index 29c0b2ec8a42ddecd1cc321f5e8309ee966bef53..476ec22ef1885094af58f4e73e773bc368163d00 100644 --- a/core/lib/Drupal/Core/Render/Element/Form.php +++ b/core/lib/Drupal/Core/Render/Element/Form.php @@ -6,6 +6,16 @@ /** * Provides a render element for a form. + * + * Properties: + * - #method: The form method: 'post' or 'get'. + * + * Usage example: + * @code + * $form = [ + * '#method' => 'post', + * ]; + * @endcode */ #[RenderElement('form')] class Form extends RenderElementBase { diff --git a/core/lib/Drupal/Core/Render/Element/ImageButton.php b/core/lib/Drupal/Core/Render/Element/ImageButton.php index f34ab63eb62f1c0253ae45ff98580415fa714668..1aeac3c2d79a353a07dbf24b996f64ecd73ad2d5 100644 --- a/core/lib/Drupal/Core/Render/Element/ImageButton.php +++ b/core/lib/Drupal/Core/Render/Element/ImageButton.php @@ -8,6 +8,17 @@ /** * Provides a form element for a submit button with an image. + * + * Properties: + * - #src: Relative path to the image used in the button. + * + * Usage Example: + * @code + * $form['actions']['add'] = [ + * '#type' => 'image_button', + * '#src' => 'my_theme/images/my_image.png', + * ]; + * @endcode */ #[FormElement('image_button')] class ImageButton extends Submit { diff --git a/core/lib/Drupal/Core/Render/Element/Item.php b/core/lib/Drupal/Core/Render/Element/Item.php index 6d00dabcd69c4a0c0caa4d6315e84697bf35c7e0..35876ae73f94a06dbcc0f174f5e566274187149b 100644 --- a/core/lib/Drupal/Core/Render/Element/Item.php +++ b/core/lib/Drupal/Core/Render/Element/Item.php @@ -10,6 +10,21 @@ * Note: since this is a read-only field, setting the #required property will do * nothing except theme the form element to look as if it were actually required * (i.e. by placing a red star next to the #title). + * + * Properties: + * - #markup: The data to be display. + * - #title: Title of the form element. + * - #description: Description of the element. + * + * Usage Example: + * @code + * $form['item_number'] = [ + * '#type' => 'item', + * '#title' => $this->t('Priority'), + * '#markup' => $this->t('Important'), + * '#description' => $this->t('The priority of this task'), + * ]; + * @endcode */ #[FormElement('item')] class Item extends FormElementBase { diff --git a/core/lib/Drupal/Core/Render/Element/LanguageSelect.php b/core/lib/Drupal/Core/Render/Element/LanguageSelect.php index fc18dccbb1252dd5e2b4abb67fb87fdf6d600fd7..8ef21257ce2db091853581e11bd386cdd997cfca 100644 --- a/core/lib/Drupal/Core/Render/Element/LanguageSelect.php +++ b/core/lib/Drupal/Core/Render/Element/LanguageSelect.php @@ -12,6 +12,16 @@ * the default language. It is then extended by Language module via * language_element_info_alter() to provide a proper language selector. * + * Usage Example: + * @code + * $form['langcode'] = [ + * '#type' => 'language_select', + * '#title' => $this->t('Menu language'), + * '#languages' => LanguageInterface::STATE_ALL, + * '#default_value' => $menu->language()->getId(), + * ]; + * @endcode + * * @see language_element_info_alter() */ #[FormElement('language_select')] diff --git a/core/lib/Drupal/Core/Render/Element/PathElement.php b/core/lib/Drupal/Core/Render/Element/PathElement.php index fbe5621552eb2aa7406a950194d5260868fe3dd0..ce0a8e6c61a8305bcad7253a5d83fc2b38e019cd 100644 --- a/core/lib/Drupal/Core/Render/Element/PathElement.php +++ b/core/lib/Drupal/Core/Render/Element/PathElement.php @@ -11,6 +11,25 @@ * Provides a form element to enter a path which can be optionally validated and * stored as either a \Drupal\Core\Url value object or an array containing a * route name and route parameters pair. + * + * Properties: + * - #convert_path: (optional) Indicates if the value is to be converted, and + * if so, how. There are 3 possible values; CONVERT_NONE indicates no + * conversion, CONVERT_ROUTE converts the value to a route name and parameter + * pair and CONVERT_URL converts the \Drupal\Core\Url value object. Defaults + * to CONVERT_ROUTE. + * - #validate_path: (optional) A boolean which indicated if the element should + * be validated. Defaults to TRUE. + * + * Usage example: + * + * @code + * $form['phone'] = [ + * '#type' => 'path', + * '#convert_path' => PathElement::CONVERT_NONE, + * '#validate_path' => FALSE, + * ]; + * @endcode */ #[FormElement('path')] class PathElement extends Textfield { diff --git a/core/modules/language/src/Element/LanguageConfiguration.php b/core/modules/language/src/Element/LanguageConfiguration.php index c0633e30957e1b916ffaf8fa91b661ad591c73d3..f51323d0f3f63746613b786b39d74b8e24450828 100644 --- a/core/modules/language/src/Element/LanguageConfiguration.php +++ b/core/modules/language/src/Element/LanguageConfiguration.php @@ -10,6 +10,9 @@ /** * Defines an element for language configuration for a single field. + * + * An internal element used to specify a specialized selection of the default + * language behavior of an entity. */ #[FormElement('language_configuration')] class LanguageConfiguration extends FormElementBase {