Skip to content

Commit d9696d5

Browse files
mapsandappsliamdebeasi
mapsandapps
and
liamdebeasi
authored
docs(datetime, datetime-button): document formatOptions property (#3452)
* docs(datetime,datetime-button): document formatOptions property * misc improvements * Apply suggestions from code review Co-authored-by: Liam DeBeasi <[email protected]> * add link to time zone docs * enlarge playground --------- Co-authored-by: Liam DeBeasi <[email protected]>
1 parent 3c594b3 commit d9696d5

File tree

14 files changed

+303
-0
lines changed

14 files changed

+303
-0
lines changed

‎docs/api/datetime-button.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,14 @@ import Basic from '@site/static/usage/v7/datetime-button/basic/index.md';
3535

3636
The localized text on `ion-datetime-button` is determined by the `locale` property on the associated `ion-datetime` instance. See [Datetime Localization](./datetime#localization) for more details.
3737

38+
## Format Options
39+
40+
You can customize the format of the date and time in a Datetime Button by providing `formatOptions` on the associated Datetime instance. See [Datetime Format Options](./datetime#format-options) for more details.
41+
42+
import FormatOptions from '@site/static/usage/v7/datetime-button/format-options/index.md';
43+
44+
<FormatOptions />
45+
3846
## Usage with Modals and Popovers
3947

4048
`ion-datetime-button` must be associated with a mounted `ion-datetime` instance. As a result, [Inline Modals](./modal#inline-modals-recommended) and [Inline Popovers](./popover#inline-popovers) with the `keepContentsMounted` property set to `true` must be used.

‎docs/api/datetime.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ import MaxMin from '@site/static/usage/v7/datetime/date-constraints/max-min/inde
1414
import Values from '@site/static/usage/v7/datetime/date-constraints/values/index.md';
1515
import Advanced from '@site/static/usage/v7/datetime/date-constraints/advanced/index.md';
1616

17+
import FormatOptions from '@site/static/usage/v7/datetime/format-options/index.md';
18+
1719
import CustomLocale from '@site/static/usage/v7/datetime/localization/custom-locale/index.md';
1820
import HourCycle from '@site/static/usage/v7/datetime/localization/hour-cycle/index.md';
1921
import FirstDayOfWeek from '@site/static/usage/v7/datetime/localization/first-day-of-week/index.md';
@@ -268,6 +270,16 @@ By default, `ion-datetime` does not show any header or title associated with the
268270

269271
<CustomizingTitle />
270272

273+
## Format Options
274+
275+
You can customize the format of the date in the header text and the time in the time button of a Datetime component by providing `formatOptions`. The `date` and `time` in the `formatOptions` property should each be an [`Intl.DateTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) object. If `formatOptions` is not provided, default formats will be used for dates and times.
276+
277+
Datetime [does not manipulate or set](#time-zones) the time zone. If `timeZone` or `timeZoneName` are provided, they will be ignored, and the time zone will be set to UTC. This ensures that the displayed value matches the selected value, rather than being converted to the user's current time zone.
278+
279+
Be careful with the options you provide, as they may not match the selected presentation. For example, providing `minute: 'numeric'` for a presentation of `month` may lead to unexpected behavior, displaying a month where only a time might be expected.
280+
281+
<FormatOptions />
282+
271283
## Buttons
272284

273285
By default, `ionChange` is emitted with the new datetime value whenever a new date is selected. To require user confirmation before emitting `ionChange`, you can either set the `showDefaultButtons` property to `true` or use the `buttons` slot to pass in a custom confirmation button. When passing in custom buttons, the confirm button must call the `confirm` method on `ion-datetime` for `ionChange` to be emitted.

‎static/usage/v7/datetime-button/format-options/angular.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
```html
2+
<ion-datetime-button datetime="datetime"></ion-datetime-button>
3+
4+
<ion-modal [keepContentsMounted]="true">
5+
<ng-template>
6+
<ion-datetime
7+
id="datetime"
8+
presentation="date-time"
9+
value="2023-11-02T01:22:00"
10+
[formatOptions]="{
11+
date: {
12+
weekday: 'short',
13+
month: 'long',
14+
day: '2-digit',
15+
},
16+
time: {
17+
hour: '2-digit',
18+
minute: '2-digit',
19+
},
20+
}"
21+
></ion-datetime>
22+
</ng-template>
23+
</ion-modal>
24+
```

‎static/usage/v7/datetime-button/format-options/demo.html‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6+
<title>Datetime Button</title>
7+
<link rel="stylesheet" href="../../../common.css" />
8+
<script src="../../../common.js"></script>
9+
<script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@7/dist/ionic/ionic.esm.js"></script>
10+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@7/css/ionic.bundle.css" />
11+
</head>
12+
13+
<body>
14+
<ion-app>
15+
<ion-content>
16+
<div class="container">
17+
<ion-datetime-button datetime="datetime"></ion-datetime-button>
18+
19+
<ion-modal keep-contents-mounted="{true}">
20+
<ion-datetime id="datetime" presentation="date-time" value="2023-11-02T01:22:00"></ion-datetime>
21+
</ion-modal>
22+
</div>
23+
</ion-content>
24+
</ion-app>
25+
26+
<script>
27+
const datetime = document.querySelector('ion-datetime');
28+
datetime.formatOptions = {
29+
date: {
30+
weekday: 'short',
31+
month: 'long',
32+
day: '2-digit',
33+
},
34+
time: {
35+
hour: '2-digit',
36+
minute: '2-digit',
37+
},
38+
};
39+
</script>
40+
</body>
41+
</html>

‎static/usage/v7/datetime-button/format-options/index.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import Playground from '@site/src/components/global/Playground';
2+
3+
import javascript from './javascript.md';
4+
import react from './react.md';
5+
import vue from './vue.md';
6+
import angular from './angular.md';
7+
8+
<Playground
9+
version="7"
10+
size="large"
11+
code={{
12+
javascript,
13+
react,
14+
vue,
15+
angular,
16+
}}
17+
src="usage/v7/datetime-button/format-options/demo.html"
18+
/>

‎static/usage/v7/datetime-button/format-options/javascript.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
```html
2+
<ion-datetime-button datetime="datetime"></ion-datetime-button>
3+
4+
<ion-modal keep-contents-mounted="true">
5+
<ion-datetime id="datetime" presentation="date-time" value="2023-11-02T01:22:00"></ion-datetime>
6+
</ion-modal>
7+
8+
<script>
9+
const datetime = document.querySelector('ion-datetime');
10+
datetime.formatOptions = {
11+
date: {
12+
weekday: 'short',
13+
month: 'long',
14+
day: '2-digit',
15+
},
16+
time: {
17+
hour: '2-digit',
18+
minute: '2-digit',
19+
},
20+
};
21+
</script>
22+
```

‎static/usage/v7/datetime-button/format-options/react.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
```tsx
2+
import React from 'react';
3+
import { IonDatetime, IonDatetimeButton, IonModal } from '@ionic/react';
4+
5+
function Example() {
6+
return (
7+
<>
8+
<IonDatetimeButton datetime="datetime"></IonDatetimeButton>
9+
10+
<IonModal keepContentsMounted={true}>
11+
<IonDatetime
12+
id="datetime"
13+
presentation="date-time"
14+
value="2023-11-02T01:22:00"
15+
formatOptions={{
16+
date: {
17+
weekday: 'short',
18+
month: 'long',
19+
day: '2-digit',
20+
},
21+
time: {
22+
hour: '2-digit',
23+
minute: '2-digit',
24+
},
25+
}}
26+
></IonDatetime>
27+
</IonModal>
28+
</>
29+
);
30+
}
31+
export default Example;
32+
```

‎static/usage/v7/datetime-button/format-options/vue.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
```html
2+
<template>
3+
<ion-datetime-button datetime="datetime"></ion-datetime-button>
4+
5+
<ion-modal :keep-contents-mounted="true">
6+
<ion-datetime
7+
id="datetime"
8+
presentation="date-time"
9+
value="2023-11-02T01:22:00"
10+
:format-options="formatOptions"
11+
></ion-datetime>
12+
</ion-modal>
13+
</template>
14+
15+
<script lang="ts" setup>
16+
import { IonDatetime, IonDatetimeButton, IonModal } from '@ionic/vue';
17+
import { defineComponent } from 'vue';
18+
19+
const formatOptions = {
20+
date: {
21+
weekday: 'short',
22+
month: 'long',
23+
day: '2-digit',
24+
},
25+
time: {
26+
hour: '2-digit',
27+
minute: '2-digit',
28+
},
29+
};
30+
</script>
31+
```

‎static/usage/v7/datetime/format-options/angular.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
```html
2+
<ion-datetime
3+
value="2023-11-02T01:22:00"
4+
[formatOptions]="{
5+
time: { hour: '2-digit', minute: '2-digit' },
6+
date: { day: '2-digit', month: 'long' },
7+
}"
8+
>
9+
<span slot="title">Select Date</span>
10+
</ion-datetime>
11+
```

‎static/usage/v7/datetime/format-options/demo.html‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6+
<title>Datetime</title>
7+
<link rel="stylesheet" href="../../../common.css" />
8+
<script src="../../../common.js"></script>
9+
<script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@7/dist/ionic/ionic.esm.js"></script>
10+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@7/css/ionic.bundle.css" />
11+
<style>
12+
ion-datetime {
13+
width: 350px;
14+
}
15+
</style>
16+
</head>
17+
18+
<body>
19+
<ion-app>
20+
<ion-content>
21+
<div class="container">
22+
<ion-datetime value="2023-11-02T01:22:00">
23+
<span slot="title">Select Date</span>
24+
</ion-datetime>
25+
</div>
26+
</ion-content>
27+
</ion-app>
28+
29+
<script>
30+
const datetime = document.querySelector('ion-datetime');
31+
datetime.formatOptions = {
32+
time: { hour: '2-digit', minute: '2-digit' },
33+
date: { day: '2-digit', month: 'long' },
34+
};
35+
</script>
36+
</body>
37+
</html>

0 commit comments

Comments
 (0)