diff --git a/ionic/components/datetime/datetime.ts b/ionic/components/datetime/datetime.ts index 465c10e495..149b360e46 100644 --- a/ionic/components/datetime/datetime.ts +++ b/ionic/components/datetime/datetime.ts @@ -16,29 +16,22 @@ const DATETIME_VALUE_ACCESSOR = new Provider( /** * @name DateTime * @description - * The Date/Time Picker displays a dialog from the bottom of a page. + * The DateTime component can be added to a template using the `` element. + * Tapping on the `` element will display a dialog that slides up from the + * bottom of the page. The dialog displays scrollable columns that can be used to select + * date and time values. + * + * It is similar to the native `` element, however, Ionic's + * DateTime component makes it easy for developers to display the date in their preferred + * format and manage the date from their JavaScript. * * - * It is similar to the native `` element. - * However, Ionic's Date/Time component makes it easy for developers to display - * the date in their preferred format and manage the date from their JavaScript. - * Additionally, the Date/Time component makes it easier for users to scroll through - * and individually select parts of date and time values from an easy to user interface. + * ## Display and Picker Formats * - * ```html - * - * Date - * - * - * - * ``` - * - * - * ### Display and Picker Formats - * - * Datetime values can be displayed in many different formats, so it is best to - * let the app decide exactly how to display it. To do so, `ion-datetime` uses - * a common format seen in many other libraries and programming languages: + * The DateTime component displays the date/time in two places: in the `` + * element, and in the dialog that presents from the bottom of the screen. These both + * can be customized to display in many different formats. The following chart lists + * all of the formats that can be passed to the different inputs. * * | Format | Description | Example | * |---------|--------------------------------|-------------------------| @@ -67,38 +60,44 @@ const DATETIME_VALUE_ACCESSOR = new Provider( * **Important**: See the [Month Names and Day of the Week Names](#month-names-and-day-of-the-week-names) * section below on how to use different names for the month and day. * - * The `displayFormat` input allows developers to specify how a date's value - * should be displayed within the `ion-datetime`. The `pickerFormat` decides - * which datetime picker columns should be shown, the order of the columns, and - * which format to display the value in. If a `pickerFormat` is not provided - * then it'll use the `displayFormat` instead. In most cases only providing the - * `displayFormat` is needed. + * ### Display Format * - * In the example below, the datetime's display would use the month's short - * name, the 1 digit day in the month, and a 4 digit year. + * The `displayFormat` input specifies how a date's value should be displayed + * within the `ion-datetime` element. + * + * In the following example, the display in the `` will use the + * month's short name, the numerical day with a leading zero, a comma and the + * 4 digit year. In addition to the date, it will display the time with the hours + * in the 24-hour format and the minutes. Both the hour and minutes will be displayed + * with a leading zero, and they are separated by a `:` character. Any character + * can be used as a separator. An example display using this format is: `Jun 17, 2005 11:06`. * * ```html * * Date - * + * * * * ``` * - * In this example, the datetime's display would only show hours and minutes, - * and the hours would be in the 24-hour format. Note that the divider between - * the hours and minutes, in this case the `:` character, can be have any - * character which the app chooses to use as the divider. + * ### Picker Format + * + * The `pickerFormat` input determines which columns should be shown in the dialog, + * the order of the columns, and which format to use to display the value. If the + *`pickerFormat` input is not provided then it will use the `displayFormat`. + * + * In the following example, the display in the `` will use the + * numerical month with a leading zero, followed by a forward slash `/` and the + * 4 digit year. An example display using this format is: `06/2020`. The dialog + * will display two columns: the month's long name, and the 4 digit year. * * ```html * * Date - * - * + * * * ``` * - * * ### Datetime Data * * Historically, handling datetime data within JavaScript, or even within HTML @@ -157,7 +156,7 @@ const DATETIME_VALUE_ACCESSOR = new Provider( * string. * * - * ### Min and Max Datetimes + * ## Min and Max Datetimes * * Dates are infinite in either direction, so for a user selection there should be at * least some form of restricting the dates can be selected. Be default, the maximum @@ -180,7 +179,7 @@ const DATETIME_VALUE_ACCESSOR = new Provider( * ``` * * - * ### Month Names and Day of the Week Names + * ## Month Names and Day of the Week Names * * At this time, there is no one-size-fits-all standard to automatically choose the correct * language/spelling for a month name, or day of the week name, depending on the language @@ -193,10 +192,10 @@ const DATETIME_VALUE_ACCESSOR = new Provider( * * All things considered, the by far easiest solution is to just provide an array of names * if the app needs to use names other than the default English version of month and day - * names. The month names and day names can be either configurated at the app level, or + * names. The month names and day names can be either configured at the app level, or * individual `ion-datetime` level. * - * ##### App Config Level + * ### App Config Level * * ```ts * @App({ @@ -209,16 +208,17 @@ const DATETIME_VALUE_ACCESSOR = new Provider( * }) * ``` * - * ##### Component Input Level + * ### Component Input Level * * ```html * * Período - * * * ``` @@ -239,6 +239,17 @@ const DATETIME_VALUE_ACCESSOR = new Provider( * prepackage this dependency since most apps will not require it, and its locale * configuration should be decided by the end-developer. * + * + * @usage + * ```html + * + * Date + * + * + * + * ``` + * + * * @demo /docs/v2/demos/datetime/ */ @Component({