Calendar
Calendar is a component for a user to select a specific date, list of dates or a range of dates.
Create calendar
The calendar component is designed to organize the user's choice of a date or a list of dates.
To create calendar
add data-role="calendar"
attribute to element.
You can create compact calendar with class compact
.
<div data-role="calendar"></div>
<div data-role="calendar" class="compact"></div>
Also you can use wide
calendar. To create wide
calendar, use attributes data-wide="true"
- persistent
or data-wide-point="..."
where point
is one of the Metro UI media point (fs, sm, md, lg, xl, xxl).
<div data-role="calendar" data-wide-point="sm"></div>
Week start
Metro UI calendar
support two modes for week start
:
- from
sunday
(default) - from
monday
To set week start
use data-week-start
attribute.
When value is 0
(default), calendar started from sunday, when value is 1
, calendar started from monday.
<div data-role="calendar" data-week-start="0"></div>
<div data-role="calendar" data-week-start="1"></div>
Selection
You can use two variants of date selecting: one date
mode (default) or multi dates
mode.
To set selection
mode use attribute data-multi-select
with values true
or false
.
If you set data-multi-select="true"
, you also select column
of dates by click on week day
.
<div data-role="calendar" data-multi-select="true"></div>
<div data-role="calendar" data-multi-select="false"></div>
Picker mode
You can set calendar to picker mode
with attribute data-picker-mode="true"
.
In this mode user can select only one date and selected date marked as today
.
<div data-role="calendar" data-picker-mode="true"></div>
Buttons
Metro UI calendar contains predefined four buttons to behavior with component:
cancel
,
today
,
clear
and done
.
To define buttons use data-buttons
attribute with string value with enumeration of buttons.
By default a all buttons are present.
If this attribute value is a false
, all buttons will be hide.
<div data-role="calendar" data-buttons="today, clear"></div>
<div data-role="calendar" data-buttons="false"></div>
For all buttons defined callbacks:
Button | Event | Data-* |
---|---|---|
cancel | onCancel(el) | data-on-cancel |
today | onToday(today, el) | data-on-today |
clear | onClear(el) | data-on-clear |
done | onDone(selection, el) | data-on-done |
Buttons today
and clear
has specific predefined functions.
Button today
- set today for calendar.
Button clear
- clear selection for calendar.
Callbacks for this buttons executed after predefined functions.
Input dates format
New in 4.2.20
You can define your input format for dates with attribute data-input-format
.
To define date parts use next identifiers:
day | dd , %d |
month | mm , %m |
year | yyyy , yy , %Y |
hours | hh , %h |
minutes | ii , %i |
seconds | ss , %s |
Example: if you input date is 21/12/1972
, you must define format as %d/%m/%Y
or dd/mm/yyyy
for valid convert string value to date.
If your input date format different from ECMAScript date format, you must define input format for these dates with attribute data-input-format="..."
.
Exclude dates
You can exclude any dates from user selection.
To exclude dates add data-exclude="..."
attribute and specify comma separated dates who can be excluded.
<div
data-role="calendar"
data-input-format="dd-mm-yyyy"
data-show="15-10-2017"
data-exclude="
10-10-2017,
11-10-2017,
12-10-2017,
13-10-2017,
14-10-2017,
15-10-2017
"
></div>
Preset dates
You can preselect dates. To preselect dates use data-preset="..."
attribute and specify dates who can be preselect.
<div
data-role="calendar"
data-show="2017/10/15"
data-preset="
2017/10/10,
2017/10/11,
2017/10/12,
2017/10/13,
2017/10/14,
2017/10/15,
2017/10/16"
></div>
Special dates
You can set a special
dates.
If you set a special dates, others dates marked as disabled.
To set special dates use data-special="..."
attribute and specify dates who can be sets.
<div
data-role="calendar"
data-show="2017/10/15"
data-special="
2017/10/10,
2017/10/11,
2017/10/12,
2017/10/13,
2017/10/14,
2017/10/15,
2017/10/16"
></div>
Min & max dates
You can limit the set of dates for user selection. To set limit use data-min-date="..."
and data-max-date="..."
attributes.
<div
data-role="calendar"
data-show="2017/10/15"
data-min-date="2017/10/08"
data-max-date="2017/10/25"
></div>
Show specific date
You can switch calendar to specific date. To switch calendar use attribute data-show="..."
.
<div
data-role="calendar"
data-show="1972/12/21"
></div>
Select month, year
You can quick change month
or year
.
To change month
, click on current month name and select required month from months panel.
To change year
, click on current year name and select required year from year panel.
Multi select
You can enable multi select feature with attribute data-multi-select
and data-week-day-click
.
<div id="calendar_multiselect" class="mx-auto"
data-role="calendar"
data-week-day-click="true"
data-multi-select="true"
></div>
Internationalisation
You can use attribute data-locale="..."
to setup language for calendar. The default locale is en-US
.
More about Metro UI locales you can read in this article.
<div data-role="calendar" data-locale="de-DE"></div>
<div data-role="calendar" data-locale="uk-UA"></div>
You can change locale in runtime. To change locale, update value for attribute data-locale
.
<div class="d-flex flex-justify-center mb-4">
<button class="button m-1" onclick="$('#cal_locale').attr('data-locale', $(this).text())">en-US</button>
<button class="button m-1" onclick="$('#cal_locale').attr('data-locale', $(this).text())">de-DE</button>
<button class="button m-1" onclick="$('#cal_locale').attr('data-locale', $(this).text())">hu-HU</button>
<button class="button m-1" onclick="$('#cal_locale').attr('data-locale', $(this).text())">uk-UA</button>
<button class="button m-1" onclick="$('#cal_locale').attr('data-locale', $(this).text())">ru-RU</button>
</div>
<div data-role="calendar" data-locale="en-US" class="mx-auto" id="cal_locale"></div>
Options
You can use calendar options to setup it behavior.
Option | Data-* | Default | Desc |
---|---|---|---|
yearsBefore | data-years-before |
100 | Years before today |
yearsAfter | data-years-after |
100 | Years after today |
show | data-show |
null | Show specific date |
pickerMode | data-picker-mode |
false | Set calendar to picker mode |
locale | data-locale |
METRO_LOCALE (default en-US) | Calendar language |
weekStart | data-week-start |
0 | Start month from sunday or monday (0 - sunday, 1 - monday) |
outside | data-outside |
true | Show dates outside from month (prev or next month dates) |
buttons | data-buttons |
cancel, today, clear, done | Buttons can be showing in calendar |
ripple | data-ripple |
false | Add ripple effect to click |
rippleColor | data-ripple-color |
#cccccc | Ripple color |
exclude | data-exclude |
null | Dates can be excluded from selection |
preset | data-preset |
null | Dates can be preselect |
minDate | data-min-date |
null | Min date |
maxDate | data-max-date |
null | Max date |
weekDayClick | data-week-day-click |
false | If true, user can click on week day to select column of days, required multiSelect can be set to true |
multiSelect | data-week-day-click |
false | If true, user can select a few days |
showHeader | data-show-header |
true | If true, header is visible |
showFooter | data-show-footer |
true | If true, footer is visible |
Events
When calendar works, it generated the numbers of events. You can use callback for this event to behavior with calendar or eny elements. Rules for working with events are described on this page.
Event | Data-* | Default | Desc |
---|---|---|---|
onCancel(el) |
data-on-cancel |
Metro.noop | Callback for cancel button |
onToday(today, el) |
data-on-today |
Metro.noop | Callback for today button |
onClear(el) |
data-on-clear |
Metro.noop | Callback for clear button |
onDone(sel, el) |
data-on-done |
Metro.noop | Callback for done button |
onDayClick(sel, day, el) |
data-on-day-click |
Metro.noop | Callback for day click |
onWeekDayClick(sel, day, el) |
data-on-week-day-click |
Metro.noop | Callback for week day click |
onMonthChange(curr, el) |
data-on-month-change |
Metro.noop | Callback for month change event |
onYearChange(curr, el) |
data-on-year-change |
Metro.noop | Callback for year change event |
onCalendarCreate(el) |
data-on-calendar-create |
Metro.noop | Callback fired when calendar is created |
<div data-role="calendar" data-on-day-click="console.log(arguments)"></div>
<div data-role="calendar" data-on-day-click="myFunction"></div>
<script>
function myFunction(sel, day, el){
console.log(sel)
console.log(day)
console.log(el)
}
</script>
Methods
You can use calendar methods to interact with the calendar.
- getPreset()
- getSelected()
- getExcluded()
- getToday()
- getCurrent()
- setToday(today)
- setExclude(exclude)
- setPreset(preset)
- setShow(show)
- setMinDate(date)
- setMaxDate(date)
var calendar = Metro.getPlugin(element, 'calendar');
console.log(calendar.getPreset());
console.log(calendar.getSelected());
console.log(calendar.getExcluded());
console.log(calendar.getToday());
console.log(calendar.getCurrent());
calendar.setExcluded("10/10/2017, 10/11/2017");
calendar.setPreset("10/14/2017, 10/15/2017, 10/16/2017");
calendar.setShow("01/01/2017");
calendar.setMinDate("05/01/2017");
calendar.setMaxDate("31/01/2017");
Observe
You can change attributes
data-exclude
,
data-preset
,
data-show
,
data-min-date
,
data-max-date
at runtime and calendar will be updated.
Customize
You can customize any calendar elements with nex options:
clsToday | data-cls-today |
Additional class for today |
clsSelected | data-cls-selected |
Additional class for selected |
clsExclude | data-cls-exclude |
Additional class for excluded |
clsCancelButton | data-cls-cancel-button |
Additional class for cancel button |
clsTodayButton | data-cls-today-button |
Additional class for today button |
clsClearButton | data-cls-clear-button |
Additional class for clear button |
clsDoneButton | data-cls-done-button |
Additional class for done button |
clsCalendar | data-cls-calendar |
Additional class calendar |
clsCalendarHeader | data-cls-calendar-header |
Additional class for calendar header |
clsCalendarContent | data-cls-calendar-content |
Additional class for calendar content |
clsCalendarFooter | data-cls-calendar-footer |
Additional class for calendar footer |
clsCalendarMonths | data-cls-calendar-months |
Additional class for calendar months |
clsCalendarYears | data-cls-calendar-years |
Additional class for calendar years |
<div class="mx-auto"
data-role="calendar"
data-show="2017/10/15"
data-exclude="2017/10/01, 2017/10/02, 2017/10/03"
data-preset="2017/10/15, 2017/10/16, 2017/10/17"
data-cls-selected="bg-cyan fg-white"
data-cls-excluded="bg-dark fg-white"
data-cls-today="bg-pink fg-white"
data-cls-today-button="success"
data-cls-clear-button="alert"
data-cls-done-button="primary"
data-cls-calendar-header="bg-green"
data-cls-calendar-content="bg-orange fg-white"
data-cls-calendar-footer="bg-teal"
></div>