Skip to content

Commit dce6508

Browse files
mrholekmrholek
committed
docs(Calendar): add component documentation
1 parent 7bd3943 commit dce6508

File tree

3 files changed

+260
-79
lines changed

3 files changed

+260
-79
lines changed

‎docs/assets/js/snippets.js

Lines changed: 18 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
/* eslint-disable complexity */
21
// NOTICE!!! Initially embedded in our docs this JavaScript
32
// file contains elements that can help you create reproducible
43
// use cases in StackBlitz for instance.
@@ -224,70 +223,26 @@
224223
// -------------------------------
225224
// 'Calendars components' example in docs only
226225

227-
const myCalendar = document.getElementById('myCalendar')
228-
if (myCalendar) {
229-
new coreui.Calendar(myCalendar)
230-
231-
myCalendar.addEventListener('startDateChange.coreui.calendar', event => {
232-
// eslint-disable-next-line no-console
233-
console.log(event.date)
234-
})
235-
236-
myCalendar.addEventListener('endDateChange.coreui.calendar', event => {
237-
// eslint-disable-next-line no-console
238-
console.log(event.date)
239-
})
240-
}
241-
242-
const myCalendarWeek = document.getElementById('myCalendarWeek')
243-
if (myCalendarWeek) {
244-
new coreui.Calendar(myCalendarWeek)
245-
246-
myCalendarWeek.addEventListener('startDateChange.coreui.calendar', event => {
247-
// eslint-disable-next-line no-console
248-
console.log(event.date)
249-
})
250-
251-
myCalendarWeek.addEventListener('endDateChange.coreui.calendar', event => {
252-
// eslint-disable-next-line no-console
253-
console.log(event.date)
254-
})
255-
256-
myCalendarWeek.addEventListener('cellHover.coreui.calendar', event => {
257-
// eslint-disable-next-line no-console
258-
console.log(event.date)
259-
})
260-
}
261-
262-
const myCalendarMonth = document.getElementById('myCalendarMonth')
263-
if (myCalendarMonth) {
264-
new coreui.Calendar(myCalendarMonth)
265-
266-
myCalendarMonth.addEventListener('startDateChange.coreui.calendar', event => {
267-
// eslint-disable-next-line no-console
268-
console.log(event.date)
269-
})
270-
271-
myCalendarMonth.addEventListener('endDateChange.coreui.calendar', event => {
272-
// eslint-disable-next-line no-console
273-
console.log(event.date)
274-
})
275-
}
276-
277-
const myCalendarYear = document.getElementById('myCalendarYear')
278-
if (myCalendarYear) {
279-
new coreui.Calendar(myCalendarYear)
280-
281-
myCalendarYear.addEventListener('startDateChange.coreui.calendar', event => {
282-
// eslint-disable-next-line no-console
283-
console.log(event.date)
284-
})
226+
// js-docs-start calendar-disabled-dates
227+
const myCalendarDisabledDates = document.getElementById('myCalendarDisabledDates')
228+
if (myCalendarDisabledDates) {
229+
const optionsCalendarDisabledDates = {
230+
locale: 'en-US',
231+
calendarDate: new Date(2022, 2, 1),
232+
calendars: 2,
233+
disabledDates: [
234+
[new Date(2022, 2, 4), new Date(2022, 2, 7)],
235+
new Date(2022, 2, 16),
236+
new Date(2022, 3, 16),
237+
[new Date(2022, 4, 2), new Date(2022, 4, 8)]
238+
],
239+
maxDate: new Date(2022, 5, 0),
240+
minDate: new Date(2022, 1, 1)
241+
}
285242

286-
myCalendarYear.addEventListener('endDateChange.coreui.calendar', event => {
287-
// eslint-disable-next-line no-console
288-
console.log(event.date)
289-
})
243+
new coreui.Calendar(myCalendarDisabledDates, optionsCalendarDisabledDates)
290244
}
245+
// js-docs-end calendar-disabled-dates
291246

292247
// -------------------------------
293248
// Date Pickers

‎docs/content/components/calendar.md

Lines changed: 238 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,281 @@
11
---
22
layout: docs
3-
title: Bootstrap calendar
4-
description: Create consistent cross-browser and cross-device calendar.
3+
title: Calendar
4+
description: The Bootstrap Calendar Component is a versatile, customizable tool for creating responsive calendars in Bootstrap, supporting day, month, and year selection, and global locales.
55
group: components
66
toc: true
7+
bootstrap: true
8+
pro_component: true
79
---
810

911
## Example
1012

13+
Explore the Bootstrap 5 Calendar component's basic usage through sample code snippets demonstrating its core functionality.
14+
1115
### Days
1216

17+
Select specific days using the Bootstrap Calendar component. The example below shows basic usage.
18+
1319
{{< example >}}
14-
<div class="d-flex">
15-
<div id="myCalendar" class="border rounded" data-coreui-show-week-number="true" data-coreui-show-adjacement-days="true" data-coreui-start-date="2021/08/02" data-coreui-end-date="2021/08/12" data-coreui-calendars="2" data-coreui-range="true"></div>
20+
<div class="d-flex justify-content-center">
21+
<div class="border rounded" data-coreui-locale="en-US" data-coreui-toggle="calendar"></div>
1622
</div>
1723
{{< /example >}}
1824

1925
### Weeks
2026

27+
Set the `data-coreui-selection-type` to `week` to enable selection of entire week. You can also use `data-coreui-show-week-number="true"` to show week numbers.
28+
2129
{{< example >}}
22-
<div class="d-flex">
23-
<div id="myCalendarWeek" class="border rounded" data-coreui-show-week-number="true" data-coreui-show-adjacement-days="true" data-coreui-start-date="2025W07" data-coreui-end-date="2025W12" data-coreui-calendars="2" data-coreui-range="true" data-coreui-selection-type="week"></div>
30+
<div class="d-flex justify-content-center">
31+
<div
32+
class="border rounded"
33+
data-coreui-locale="en-US"
34+
data-coreui-selection-type="week"
35+
data-coreui-show-week-number="true"
36+
data-coreui-start-date="2024W15"
37+
data-coreui-toggle="calendar"
38+
></div>
2439
</div>
2540
{{< /example >}}
2641
2742
### Months
2843

44+
Set the `data-coreui-selection-type` to `month` to enable selection of entire months.
45+
2946
{{< example >}}
30-
<div class="d-flex">
47+
<div class="d-flex justify-content-center">
3148
<div
32-
id="myCalendarMonth"
3349
class="border rounded"
34-
data-coreui-show-week-number="true"
35-
data-coreui-start-date="2022-8"
36-
data-coreui-end-date="2023-8"
50+
data-coreui-locale="en-US"
51+
data-coreui-selection-type="month"
52+
data-coreui-toggle="calendar">
53+
</div>
54+
</div>
55+
{{< /example >}}
56+
57+
### Years
58+
59+
Set the `data-coreui-selection-type` to `year` to enable years range selection.
60+
61+
{{< example >}}
62+
<div class="d-flex justify-content-center">
63+
<div
64+
class="border rounded"
65+
data-coreui-locale="en-US"
66+
data-coreui-selection-type="year"
67+
data-coreui-toggle="calendar">
68+
</div>
69+
</div>
70+
{{< /example >}}
71+
72+
## Multiple calendar panels
73+
74+
Display multiple calendar panels side by side by setting the `data-coreui-calendars` attribute. This can be useful for selecting ranges or comparing dates across different months.
75+
76+
{{< example >}}
77+
<div class="d-flex justify-content-center">
78+
<div
79+
class="border rounded"
80+
data-coreui-calendars="2"
81+
data-coreui-locale="en-US"
82+
data-coreui-toggle="calendar">
83+
</div>
84+
</div>
85+
{{< /example >}}
86+
87+
## Range selection
88+
89+
Enable range selection by adding `data-coreui-range="true"` to allow users to pick a start and end date. This example demonstrates how to configure the Bootstrap 5 Calendar component to handle date ranges.
90+
91+
{{< example >}}
92+
<div class="d-flex justify-content-center">
93+
<div
94+
class="border rounded"
95+
data-coreui-locale="en-US"
3796
data-coreui-calendars="2"
3897
data-coreui-range="true"
39-
data-coreui-selection-type="month">
98+
data-coreui-start-date="2022/08/23"
99+
data-coreui-end-date="2022/09/08"
100+
data-coreui-toggle="calendar">
40101
</div>
41102
</div>
42103
{{< /example >}}
43104

44-
### Years
105+
## Disabled dates
106+
107+
The Bootstrap Calendar component includes functionality to disable specific dates, such as weekends or holidays, using the `disabledDates` option. This option takes an array and applies custom logic to determine which dates should be disabled.
108+
109+
{{< example >}}
110+
<div class="d-flex justify-content-center">
111+
<div id="myCalendarDisabledDates" class="border rounded"></div>
112+
</div>
113+
{{< /example >}}
114+
115+
{{< js-docs name="calendar-disabled-dates" file="docs/assets/js/snippets.js" >}}
116+
117+
## Non-english locale
118+
119+
The CoreUI React Calendar allows users to display dates in non-English locales, making it suitable for international applications.
120+
121+
### Auto
122+
123+
By default, the Calendar component uses the browser's default locale. However, you can easily configure it to use a different locale supported by the JavaScript Internationalization API. This feature helps create inclusive and accessible applications for a diverse audience.
124+
125+
{{< example >}}
126+
<div class="d-flex justify-content-center">
127+
<div class="border rounded" data-coreui-toggle="calendar"></div>
128+
</div>
129+
{{< /example >}}
130+
131+
### Chinese
132+
133+
Here is an example of the React Calendar component with Chinese locale settings.
134+
135+
{{< example >}}
136+
<div class="d-flex justify-content-center">
137+
<div class="border rounded" data-coreui-locale="zh-CN" data-coreui-toggle="calendar"></div>
138+
</div>
139+
{{< /example >}}
140+
141+
### Japanese
142+
143+
Below is an example of the Calendar component with Japanese locale settings.
144+
145+
{{< example >}}
146+
<div class="d-flex justify-content-center">
147+
<div class="border rounded" data-coreui-locale="ja" data-coreui-toggle="calendar"></div>
148+
</div>
149+
{{< /example >}}
150+
151+
### Korean
152+
153+
Here is an example of the Calendar component with Korean locale settings.
154+
155+
{{< example >}}
156+
<div class="d-flex justify-content-center" dir="rtl">
157+
<div class="border rounded" data-coreui-locale="ko" data-coreui-toggle="calendar"></div>
158+
</div>
159+
{{< /example >}}
160+
161+
## Right to left support
162+
163+
RTL support is built-in and can be explicitly controlled through the `$enable-rtl` variables in scss.
164+
165+
### Hebrew
166+
167+
Example of the Calendar component with RTL support, using the Hebrew locale.
168+
169+
{{< example >}}
170+
<div class="d-flex justify-content-center" dir="rtl">
171+
<div class="border rounded" data-coreui-locale="he-IL" data-coreui-toggle="calendar"></div>
172+
</div>
173+
{{< /example >}}
174+
175+
### Persian
176+
177+
Example of the React Calendar component with Persian locale settings.
45178

46179
{{< example >}}
47-
<div class="d-flex">
48-
<div id="myCalendarYear" class="border rounded" data-coreui-show-week-number="true" data-coreui-show-adjacement-days="true" data-coreui-start-date="2022" data-coreui-end-date="2024" data-coreui-calendars="2" data-coreui-range="true" data-coreui-selection-type="year"></div>
180+
<div class="d-flex justify-content-center">
181+
<div class="border rounded" data-coreui-locale="fa-IR" data-coreui-toggle="calendar"></div>
49182
</div>
50183
{{< /example >}}
51184

185+
## Usage
186+
187+
{{< bootstrap-compatibility >}}
188+
189+
### Via data attributes
190+
191+
Add `data-coreui-toggle="calendar"` to a `div` element.
192+
193+
```html
194+
<div data-coreui-toggle="calendar"></div>
195+
```
196+
197+
### Via JavaScript
198+
199+
Call the time picker via JavaScript:
200+
201+
```html
202+
<div class="calendar"></div>
203+
```
204+
205+
```js
206+
const calendarElementList = Array.prototype.slice.call(document.querySelectorAll('.calendar'))
207+
const calendarList = calendarElementList.map(calendarEl => {
208+
return new coreui.Calendar(calendarEl)
209+
})
210+
```
211+
212+
### Options
213+
214+
{{< markdown >}}
215+
{{< partial "js-data-attributes.md" >}}
216+
{{< /markdown >}}
217+
218+
{{< bs-table >}}
219+
| Name | Type | Default | Description |
220+
| --- | --- | --- | --- |
221+
| `ariaNavNextMonthLabel` | string | `'Next month'` | A string that provides an accessible label for the button that navigates to the next month in the calendar. This label is read by screen readers to describe the action associated with the button. |
222+
| `ariaNavNextYearLabel` | string | `'Next year'` | A string that provides an accessible label for the button that navigates to the next year in the calendar. This label is intended for screen readers to help users understand the button's functionality. |
223+
| `ariaNavPrevMonthLabel` | string | `'Previous month'` | A string that provides an accessible label for the button that navigates to the previous month in the calendar. Screen readers will use this label to explain the purpose of the button. |
224+
| `ariaNavPrevYearLabel` | string | `'Previous year'` | A string that provides an accessible label for the button that navigates to the previous year in the calendar. This label helps screen reader users understand the button's function. |
225+
| `calendarDate` | date, number, string, null | `null` | Default date of the component. |
226+
| `calendars` | number | `2` | The number of calendars that render on desktop devices. |
227+
| `disabledDates` | array, null | `null` | Specify the list of dates that cannot be selected. |
228+
| `endDate` | date, number, string, null | `null` | Initial selected to date (range). |
229+
| `firstDayOfWeek` | number | `1` | <p>Sets the day of start week.</p> <ul><li>`0` - Sunday</li><li>`1` - Monday</li><li>`2` - Tuesday</li><li>`3` - Wednesday</li><li>`4` - Thursday</li><li>`5` - Friday</li><li>`6` - Saturday</li></ul> |
230+
| `locale` | string | `'default'` | Sets the default locale for components. If not set, it is inherited from the navigator.language. |
231+
| `maxDate` | date, number, string, null | `null` | Max selectable date. |
232+
| `minDate` | date, number, string, null | `null` | Min selectable date. |
233+
| `range` | boolean | `false` | Allow range selection |
234+
| `selectAdjacementDays` | boolean | `false` | Set whether days in adjacent months shown before or after the current month are selectable. This only applies if the `showAdjacementDays` option is set to true. |
235+
| `selectionType` | `'day'`, `'week'`, `'month'`, `'year'` | `day` | Specify the type of date selection as day, week, month, or year. |
236+
| `showAdjacementDays` | boolean | `true` | Set whether to display dates in adjacent months (non-selectable) at the start and end of the current month. |
237+
| `showWeekNumber` | boolean | `false` | Set whether to display week numbers in the calendar. |
238+
| `startDate` | date, number, string, null | `null` | Initial selected date. |
239+
| `weekdayFormat` | number, 'long', 'narrow', 'short' | `2` | Set length or format of day name. |
240+
| `weekNumbersLabel` | string | `null` | Label displayed over week numbers in the calendar. |
241+
{{< /bs-table >}}
242+
243+
### Methods
244+
245+
{{< bs-table >}}
246+
| Method | Description |
247+
| --- | --- |
248+
| `update` | Updates the configuration of the calendar. |
249+
| `dispose` | Destroys a component. (Removes stored data on the DOM element) |
250+
| `getInstance` | Static method which allows you to get the calendar instance associated to a DOM element, you can use it like this: `coreui.Calendar.getInstance(element)` |
251+
| `getOrCreateInstance` | Static method which returns a calendar instance associated to a DOM element or create a new one in case it wasn't initialized. You can use it like this: `coreui.Calendar.getOrCreateInstance(element)` |
252+
{{< /bs-table >}}
253+
254+
### Events
255+
256+
{{< bs-table >}}
257+
| Method | Description |
258+
| --- | --- |
259+
| `calendarDateChange.coreui.calendar` | Callback fired when the calendar date changed. |
260+
| `calendarMouseleave.coreui.calendar` | Callback fired when the cursor leave the calendar. |
261+
| `cellHover.coreui.calendar` | Callback fired when the user hovers over the calendar cell. |
262+
| `endDateChange.coreui.calendar` | Callback fired when the end date changed. |
263+
| `selectEndChange.coreui.calendar` | Callback fired when the selection type changed. |
264+
| `startDateChange.coreui.calendar` | Callback fired when the start date changed. |
265+
{{< /bs-table >}}
266+
267+
```js
268+
const myCalendar = document.getElementById('myCalendar')
269+
myCalendar.addEventListener('endDateChange.coreui.calendar', date => {
270+
// do something...
271+
})
272+
```
273+
52274
## Customizing
53275

54276
### CSS variables
55277

56-
Calendar use local CSS variables on .accordion for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
278+
Calendar use local CSS variables on `.calendar` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
57279

58280
{{< scss-docs name="calendar-css-vars" file="scss/_calendar.scss" >}}
59281

0 commit comments

Comments
 (0)