docs(datetime): add highlightedDates playgrounds (#2769)

ionic-team · Feb 22, 2023 · 8036f63 · 8036f63
1 parent e369a87
commit 8036f63
Show file tree

Hide file tree

Showing 30 changed files with 924 additions and 0 deletions.
diff --git a/docs/api/datetime.md b/docs/api/datetime.md
@@ -31,6 +31,9 @@ import ShowingConfirmationButtons from '@site/static/usage/v7/datetime/buttons/s
 import CustomizingButtons from '@site/static/usage/v7/datetime/buttons/customizing-buttons/index.md';
 import CustomizingButtonTexts from '@site/static/usage/v7/datetime/buttons/customizing-button-texts/index.md';
 
+import HighlightedDatesArray from '@site/static/usage/v7/datetime/highlightedDates/array/index.md';
+import HighlightedDatesCallback from '@site/static/usage/v7/datetime/highlightedDates/callback/index.md';
+
 import MultipleDateSelection from '@site/static/usage/v7/datetime/multiple/index.md';
 
 import Theming from '@site/static/usage/v7/datetime/theming/index.md';
@@ -283,6 +286,30 @@ Developers can provide their own buttons for advanced custom behavior.
 
 <CustomizingButtons />
 
+## Highlighting Specific Dates
+
+Using the `highlightedDates` property, developers can style particular dates with custom text or background colors. This property can be defined as either an array of dates and their colors, or a callback that receives an ISO string and returns the colors to use.
+
+When specifying colors, any valid CSS color format can be used. This includes hex codes, rgba, [color variables](../theming/colors), etc.
+
+To maintain a consistent user experience, the style of selected date(s) will always override custom highlights.
+
+:::note
+This property is only supported when `preferWheel="false"`, and using a `presentation` of either `"date"`, `"date-time"`, or `"time-date"`.
+:::
+
+### Using Array
+
+An array is better when the highlights apply to fixed dates, such as due dates.
+
+<HighlightedDatesArray />
+
+### Using Callback
+
+A callback is better when the highlighted dates are recurring, such as birthdays or recurring meetings.
+
+<HighlightedDatesCallback />
+
 ## Theming
 
 Ionic's powerful theming system can be used to easily change your entire app to match a certain theme. In this example, we used the [Color Creator](../theming/colors#new-color-creator) and the [Stepped Color Generator](../theming/themes#stepped-color-generator) to create a rose color palette that we can use for `ion-datetime`.

diff --git a/static/usage/v6/datetime/highlightedDates/array/angular/example_component_html.md b/static/usage/v6/datetime/highlightedDates/array/angular/example_component_html.md
@@ -0,0 +1,7 @@
+```html
+<ion-datetime
+  presentation="date"
+  value="2023-01-01"
+  [highlightedDates]="highlightedDates"
+></ion-datetime>
+```
diff --git a/static/usage/v6/datetime/highlightedDates/array/angular/example_component_ts.md b/static/usage/v6/datetime/highlightedDates/array/angular/example_component_ts.md
@@ -0,0 +1,32 @@
+```ts
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-example',
+  templateUrl: 'example.component.html',
+})
+export class ExampleComponent {
+  highlightedDates = [
+    {
+      date: '2023-01-05',
+      textColor: '#800080',
+      backgroundColor: '#ffc0cb',
+    },
+    {
+      date: '2023-01-10',
+      textColor: '#09721b',
+      backgroundColor: '#c8e5d0',
+    },
+    {
+      date: '2023-01-20',
+      textColor: 'var(--ion-color-secondary-contrast)',
+      backgroundColor: 'var(--ion-color-secondary)',
+    },
+    {
+      date: '2023-01-23',
+      textColor: 'rgb(68, 10, 184)',
+      backgroundColor: 'rgb(211, 200, 229)'
+    }
+  ];
+}
+```
diff --git a/static/usage/v6/datetime/highlightedDates/array/demo.html b/static/usage/v6/datetime/highlightedDates/array/demo.html
@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Datetime</title>
+  <link rel="stylesheet" href="../../../../common.css" />
+  <script src="../../../../common.js"></script>
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/[email protected]/dist/ionic/ionic.esm.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/[email protected]/css/ionic.bundle.css" />
+  <style>
+    ion-datetime {
+      width: 350px;
+    }
+  </style>
+</head>
+
+<body>
+  <ion-app>
+    <ion-content>
+      <div class="container">
+        <ion-datetime presentation="date" value="2023-01-01"></ion-datetime>
+      </div>
+    </ion-content>
+  </ion-app>
+
+  <script>
+    const datetime = document.querySelector('ion-datetime');
+    datetime.highlightedDates = [
+      {
+        date: '2023-01-05',
+        textColor: '#800080',
+        backgroundColor: '#ffc0cb',
+      },
+      {
+        date: '2023-01-10',
+        textColor: '#09721b',
+        backgroundColor: '#c8e5d0',
+      },
+      {
+        date: '2023-01-20',
+        textColor: 'var(--ion-color-secondary-contrast)',
+        backgroundColor: 'var(--ion-color-secondary)',
+      },
+      {
+        date: '2023-01-23',
+        textColor: 'rgb(68, 10, 184)',
+        backgroundColor: 'rgb(211, 200, 229)'
+      }
+    ];
+  </script>
+</body>
+
+</html>
diff --git a/static/usage/v6/datetime/highlightedDates/array/index.md b/static/usage/v6/datetime/highlightedDates/array/index.md
@@ -0,0 +1,25 @@
+import Playground from '@site/src/components/global/Playground';
+
+import javascript from './javascript.md';
+import react from './react.md';
+import vue from './vue.md';
+
+import angular_example_component_html from './angular/example_component_html.md';
+import angular_example_component_ts from './angular/example_component_ts.md';
+
+<Playground
+  size="medium"
+  version={6}
+  code={{
+    javascript,
+    react,
+    vue,
+    angular: {
+      files: {
+        'src/app/example.component.html': angular_example_component_html,
+        'src/app/example.component.ts': angular_example_component_ts,
+      },
+    },
+  }}
+  src="usage/v6/datetime/highlightedDates/array/demo.html"
+/>
diff --git a/static/usage/v6/datetime/highlightedDates/array/javascript.md b/static/usage/v6/datetime/highlightedDates/array/javascript.md
@@ -0,0 +1,29 @@
+```html
+<ion-datetime presentation="date" value="2023-01-01"></ion-datetime>
+
+<script>
+  var datetime = document.querySelector('ion-datetime');
+  datetime.highlightedDates = [
+    {
+      date: '2023-01-05',
+      textColor: '#800080',
+      backgroundColor: '#ffc0cb',
+    },
+    {
+      date: '2023-01-10',
+      textColor: '#09721b',
+      backgroundColor: '#c8e5d0',
+    },
+    {
+      date: '2023-01-20',
+      textColor: 'var(--ion-color-secondary-contrast)',
+      backgroundColor: 'var(--ion-color-secondary)',
+    },
+    {
+      date: '2023-01-23',
+      textColor: 'rgb(68, 10, 184)',
+      backgroundColor: 'rgb(211, 200, 229)'
+    }
+  ];
+</script>
+```
diff --git a/static/usage/v6/datetime/highlightedDates/array/react.md b/static/usage/v6/datetime/highlightedDates/array/react.md
@@ -0,0 +1,35 @@
+```tsx
+import React from 'react';
+import { IonDatetime } from '@ionic/react';
+function Example() {
+  return (
+    <IonDatetime
+      presentation="date"
+      value="2023-01-01"
+      highlightedDates={[
+        {
+          date: '2023-01-05',
+          textColor: '#800080',
+          backgroundColor: '#ffc0cb',
+        },
+        {
+          date: '2023-01-10',
+          textColor: '#09721b',
+          backgroundColor: '#c8e5d0',
+        },
+        {
+          date: '2023-01-20',
+          textColor: 'var(--ion-color-secondary-contrast)',
+          backgroundColor: 'var(--ion-color-secondary)',
+        },
+        {
+          date: '2023-01-23',
+          textColor: 'rgb(68, 10, 184)',
+          backgroundColor: 'rgb(211, 200, 229)'
+        }
+      ]}
+    ></IonDatetime>
+  );
+}
+export default Example;
+```
diff --git a/static/usage/v6/datetime/highlightedDates/array/vue.md b/static/usage/v6/datetime/highlightedDates/array/vue.md
@@ -0,0 +1,44 @@
+```html
+<template>
+  <ion-datetime
+    presentation="date"
+    value="2023-01-01"
+    :highlighted-dates="highlightedDates"
+  ></ion-datetime>
+</template>
+
+<script lang="ts">
+  import { IonDatetime } from '@ionic/vue';
+  import { defineComponent } from 'vue';
+
+  export default defineComponent({
+    components: { IonDatetime },
+    setup() {
+      const highlightedDates = [
+        {
+          date: '2023-01-05',
+          textColor: '#800080',
+          backgroundColor: '#ffc0cb',
+        },
+        {
+          date: '2023-01-10',
+          textColor: '#09721b',
+          backgroundColor: '#c8e5d0',
+        },
+        {
+          date: '2023-01-20',
+          textColor: 'var(--ion-color-secondary-contrast)',
+          backgroundColor: 'var(--ion-color-secondary)',
+        },
+        {
+          date: '2023-01-23',
+          textColor: 'rgb(68, 10, 184)',
+          backgroundColor: 'rgb(211, 200, 229)'
+        }
+      ];
+      
+      return { highlightedDates }
+    }
+  });
+</script>
+```
diff --git a/...c/usage/v6/datetime/highlightedDates/callback/angular/example_component_html.md b/...c/usage/v6/datetime/highlightedDates/callback/angular/example_component_html.md
@@ -0,0 +1,3 @@
+```html
+<ion-datetime presentation="date" [highlightedDates]="highlightedDates"></ion-datetime>
+```
diff --git a/static/usage/v6/datetime/highlightedDates/callback/angular/example_component_ts.md b/static/usage/v6/datetime/highlightedDates/callback/angular/example_component_ts.md
@@ -0,0 +1,30 @@
+```ts
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-example',
+  templateUrl: 'example.component.html',
+})
+export class ExampleComponent {
+  highlightedDates = (isoString) => {
+    const date = new Date(isoString);
+    const utcDay = date.getUTCDate();
+
+    if(utcDay % 5 === 0) {
+      return {
+        textColor: '#800080',
+        backgroundColor: '#ffc0cb',
+      };
+    }
+
+    if(utcDay % 3 === 0) {
+      return {
+        textColor: 'var(--ion-color-secondary-contrast)',
+        backgroundColor: 'var(--ion-color-secondary)',
+      };
+    }
+
+    return undefined;
+  };
+}
+```
diff --git a/static/usage/v6/datetime/highlightedDates/callback/demo.html b/static/usage/v6/datetime/highlightedDates/callback/demo.html
@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Datetime</title>
+  <link rel="stylesheet" href="../../../../common.css" />
+  <script src="../../../../common.js"></script>
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/[email protected]/dist/ionic/ionic.esm.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/[email protected]/css/ionic.bundle.css" />
+  <style>
+    ion-datetime {
+      width: 350px;
+    }
+  </style>
+</head>
+
+<body>
+  <ion-app>
+    <ion-content>
+      <div class="container">
+        <ion-datetime presentation="date"></ion-datetime>
+      </div>
+    </ion-content>
+  </ion-app>
+
+  <script>
+    const datetime = document.querySelector('ion-datetime');
+    datetime.highlightedDates = (isoString) => {
+      const date = new Date(isoString);
+      const utcDay = date.getUTCDate();
+
+      if(utcDay % 5 === 0) {
+        return {
+          textColor: '#800080',
+          backgroundColor: '#ffc0cb',
+        };
+      }
+
+      if(utcDay % 3 === 0) {
+        return {
+          textColor: 'var(--ion-color-secondary-contrast)',
+          backgroundColor: 'var(--ion-color-secondary)',
+        };
+      }
+
+      return undefined;
+    };
+  </script>
+</body>
+
+</html>
diff --git a/static/usage/v6/datetime/highlightedDates/callback/index.md b/static/usage/v6/datetime/highlightedDates/callback/index.md
@@ -0,0 +1,25 @@
+import Playground from '@site/src/components/global/Playground';
+
+import javascript from './javascript.md';
+import react from './react.md';
+import vue from './vue.md';
+
+import angular_example_component_html from './angular/example_component_html.md';
+import angular_example_component_ts from './angular/example_component_ts.md';
+
+<Playground
+  size="medium"
+  version={6}
+  code={{
+    javascript,
+    react,
+    vue,
+    angular: {
+      files: {
+        'src/app/example.component.html': angular_example_component_html,
+        'src/app/example.component.ts': angular_example_component_ts,
+      },
+    },
+  }}
+  src="usage/v6/datetime/highlightedDates/callback/demo.html"
+/>