Calendar / Datepicker - 图1

Calendar / Datepicker

Calendar is a touch optimized component that provides an easy way to handle dates.

Calendar could be used as inline component or as overlay. Overlay Calendar will be automatically converted to Popover on tablets (iPad).

Calendar App Methods

Let’s look at related App methods to work with Calendar:

app.calendar.create(parameters)- create Calendar instance

  • parameters - object. Object with calendar parameters

Method returns created Calendar’s instance

app.calendar.destroy(el)- destroy Calendar instance

  • el - HTMLElement or string (with CSS Selector) or object. Calendar element or Calendar instance to destroy.

app.calendar.get(el)- get Calendar instance by HTML element

  • el - HTMLElement or string (with CSS Selector). Calendar element.

Method returns Calendar’s instance

app.calendar.close(el)- close Calendar

  • el - HTMLElement or string (with CSS Selector). Calendar element to close.

Method returns Calendar’s instance

For example:

  1. var calendar = app.calendar.create({
  2. inputEl: '#calendar-input'
  3. });

Calendar Parameters

Let’s look on list of all available Calendar parameters:

ParameterTypeDefaultDescription
calendarTypestringgregorianCalendar type, can be gregorian or jalali
valuearrayArray with initial selected dates. Each array item represents selected date
disabledDate RangeAdditonal disabled dates. Parameter accepts so called Date Range (look below for details)
eventsDate Range

Dates with events. Will be marked with additonal “dot” on calendar day. Parameter accepts so called Date Range (look below for details).

If you want to indicate that day has few different events, it is possible to indicate this with multiple different color dots. In this case, you need to pass date range as array where each object will have date and color properties, e.g.

  1. [
  2. {
  3. date: new Date(2018, 4, 11),
  4. color: ‘#2196f3’,
  5. },
  6. // same date but different color, one more dot will be added to this day
  7. {
  8. date: new Date(2018, 4, 11),
  9. color: ‘#4caf50’,
  10. },
  11. ]
rangesClassesarrayDate ranges you want to add custom CSS class for additional styling. Look below for accepted format
formatValuefunction (values)Function to format input value, should return new/formatted string value. values is array where each item represents selected date
monthNamesarray
  1. [‘January’, February’, March’, April’, May’, June’, July’, August , September , October’, November’, December’]
Array with full month names
monthNamesShortarray
  1. [‘Jan’, Feb’, Mar’, Apr’, May’, Jun’, Jul’, Aug’, Sep’, Oct’, Nov’, Dec’]
Array with short month names
dayNamesarray
  1. [‘Sunday’, Monday’, Tuesday’, Wednesday’, Thursday’, Friday’, Saturday’]
Array with week day names
dayNamesShortarray
  1. [‘Sun’, Mon’, Tue’, Wed’, Thu’, Fri’, Sat’]
Array with week day short names
firstDaynumber1First day of the week. By default 1 - Monday
weekendDaysarray[0, 6]Array with index numeber of weekend days, by default it is Saturday and Sunday
jalaliobject
  1. {
  2. monthNames: [‘فروردین’, ‘اردیبهشت’, ‘خرداد’, ‘تیر’, ‘مرداد’, ‘شهریور’, ‘مهر’, ‘آبان’, ‘آذر’, ‘دی’, ‘بهمن’, ‘اسفند’],
  3. monthNamesShort: [‘فَر’, ‘اُر’, ‘خُر’, ‘تیر’, ‘مُر’, ‘شَه’, ‘مهر’, ‘آب’, ‘آذر’, ‘دی’, ‘بَه’, ‘اِس’],
  4. dayNames: [‘یک‌شنبه’, ‘دوشنبه’, ‘سه‌شنبه’, ‘چهارشنبه’, ‘پنج‌شنبه’, ‘جمعه’, ‘شنبه’],
  5. dayNamesShort: [‘1ش’, ‘۲ش’, ‘۳ش’, ‘۴ش’, ‘۵ش’, ‘ج’, ‘ش’],
  6. firstDay: 6, // Saturday
  7. weekendDays: [5], // Friday
  8. [‘فروردین’, ‘اردیبهشت’, ‘خرداد’, ‘تیر’, ‘مرداد’, ‘شهریور’, ‘مهر’, ‘آبان’, ‘آذر’, ‘دی’, ‘بهمن’, ‘اسفند’]
  9. }
Object with configuration for Jalali type calendar
dateFormatstring‘yyyy-mm-dd’Default date format, available expressions:
  • ‘yyyy’ - 4 digits year
  • ‘yy’ - 2 digits year
  • ‘mm’ - 2 digits month number, from 01 to 12
  • ‘m’ - month number, from 1 to 12
  • ‘MM’ - full month name
  • ‘M’ - short month name
  • ‘dd’ - 2 digits day number, from 01 to 31
  • ‘d’ - day number, from 1 to 31
  • ‘DD’ - full week day name
  • ‘D’ - short week day name
multiplebooleanfalseEnable to allows select multiple dates/values
rangePickerbooleanfalseEnable to enable range picker. Not compatible with multiple
rangePickerMinDaysnumber1Minimum days that need to be selected when rangePicker enabled
rangePickerMaxDaysnumber0Maximum days allowed to be selected when rangePicker enabled. 0 means no maximum
directionstring‘horizontal’Months layout direction, could be ‘horizontal’ or ‘vertical’
minDateDatenullMinimum allowed date
maxDateDatenullMaximum allowed date
touchMovebooleantrueIf enabled then calendar months slides follow finger during touch move
animatebooleantrueEnables transition between months
closeOnSelectbooleanfalseEnable and calendar will be closed when user pick a date
weekHeaderbooleantrueEnable week header with short name week days
monthSelectorbooleantrueEnable month selector in toolbar
yearSelectorbooleantrueEnable year picker in toolbar
Container/opener-specific parameters
containerElstring
HTMLElement
String with CSS selector or HTMLElement where to place generated Calendar HTML. Use only for inline calendar
openInstringautoCan be auto, popover (to open calendar in popover), sheet (to open in sheet modal) or customModal (to open in custom Calendar modal overlay). In case of auto will open in sheet modal on small screens and in popover on large screens.
inputElstring or HTMLElementString with CSS selector or HTMLElement with related input element
scrollToInputbooleantrueScroll viewport (page-content) to input when calendar opened
inputReadOnlybooleantrueSets “readonly” attribute on specified input
cssClassstringAdditional CSS class name to be set on calendar element
closeByOutsideClickbooleantrueIf enabled, picker will be closed by clicking outside of picker or related input element
toolbarbooleantrueEnables calendar toolbar
toolbarCloseTextstringDoneText for Done/Close toolbar button
headerbooleanfalseEnables calendar header
headerPlaceholderstringSelect dateDefault calendar header placeholder text
routableModalsbooleantrueWill add opened calendar to router history which gives ability to close calendar by going back in router history and set current route to the calendar modal
urlstringdate/Calendar modal URL that will be set as a current route
viewobjectView where to set routing when routableModals enabled. Defaults to parent view of inputEl or main view if not found parent view
backdropbooleanEnables Calendar backdrop (dark semi transparent layer behind). By default only it is enabled when Calendar opened in Popover.
closeByBackdropClickbooleantrueWhen enabled, Calendar will be closed on backdrop click
Render Functions
renderWeekHeaderfunctionFunction to render week header. Must return week header HTML string
renderMonthsfunction(date)Function to render months wrapper. Must return months container full HTML string
renderMonthfunction(date, offset)Function to render single month. Must return single month HTML string
renderMonthSelectorfunctionFunction to render month selector. Must return month selector HTML string
renderYearSelectorfunctionFunction to render year selector. Must return year selector HTML string
renderHeaderfunctionFunction to render calendar header. Must return calendar header HTML string
renderToolbarfunctionFunction to render toolbar. Must return toolbar HTML string
renderfunctionFunction to render whole calendar. Must return calendar full HTML string
Events
onobjectObject with events handlers. For example:
  1. var calendar = app.calendar.create({
  2. on: {
  3. opened: function () {
  4. console.log(‘Calendar opened’)
  5. }
  6. }
  7. })

Note that all following parameters can be used in global app parameters under calendar property to set defaults for all calendars. For example:

  1. var app = new Framework7({
  2. calendar: {
  3. url: 'calendar/',
  4. dateFormat: 'dd.mm.yyyy',
  5. }
  6. });

Date Range

Some of Calendar parameters (disabled, events and rangesClasses) accept so called Date Range. It is a simple way to specify and cover all possible dates combination.

It can be array with dates, for example:

  1. var calendar = app.calendar.create({
  2. ...
  3. // Disabled 10th November 2015 and 11th November 2015:
  4. disabled: [new Date(2015, 10, 10), new Date(2015, 10, 11)],
  5. ...
  6. });

It can be custom function where you need to return true or false

  1. var calendar = app.calendar.create({
  2. ...
  3. //Disabled all dates in November 2015
  4. disabled: function (date) {
  5. if (date.getFullYear() === 2015 && date.getMonth() === 10) {
  6. return true;
  7. }
  8. else {
  9. return false;
  10. }
  11. },
  12. ...
  13. });

Or object with from and to properties

  1. var calendar = app.calendar.create({
  2. ...
  3. //Disable all dates between 1st October 2015 and 31 December 2015
  4. disabled: {
  5. from: new Date(2015, 9, 1),
  6. to: new Date(2015, 11, 31)
  7. },
  8. ...
  9. });

Or object with just from or to properties

  1. var calendar = app.calendar.create({
  2. ...
  3. //Disable everyting since December 2015
  4. disabled: {
  5. from: new Date(2015, 11, 1)
  6. },
  7. ...
  8. });

Or object with date property:

  1. var calendar = app.calendar.create({
  2. ...
  3. // Disabled 1th December 2015
  4. disabled: {
  5. date: new Date(2015, 11, 1)
  6. },
  7. ...
  8. });

Or array with mixed dates and objects:

  1. var calendar = app.calendar.create({
  2. ...
  3. events: [
  4. new Date(2015, 9, 1),
  5. new Date(2015, 9, 5),
  6. {
  7. from: new Date(2015, 9, 10),
  8. to: new Date(2015, 9, 15)
  9. },
  10. {
  11. from: new Date(2015, 9, 20),
  12. to: new Date(2015, 9, 31)
  13. },
  14. {
  15. date: new Date(2015, 11, 1),
  16. color: '#ff0000'
  17. },
  18. // same date but one more color dot will be added
  19. {
  20. date: new Date(2015, 11, 1),
  21. color: '#00ff00'
  22. },
  23. ],
  24. ...
  25. });

rangesClasses

rangesClasses parameter accepts array of objects with Date Range and class names for this range:

  1. var calendar = app.calendar.create({
  2. ...
  3. //Add classes for november and october
  4. rangesClasses: [
  5. //Add "day-october' class for all october dates
  6. {
  7. // string CSS class name for this range in "cssClass" property
  8. cssClass: 'day-october', //string CSS class
  9. // Date Range in "range" property
  10. range: function (date) {
  11. return date.getMonth() === 9
  12. }
  13. },
  14. //Add "day-holiday" class for 1-10th January 2015
  15. {
  16. cssClass: 'day-holiday',
  17. range: {
  18. from: new Date(2016, 0, 1),
  19. to: new Date(2016, 0, 10)
  20. }
  21. }
  22. ],
  23. ...
  24. });

Calendar Methods & Properties

After we initialize Calendar we have its initialized instance in variable (like calendar variable in examples above) with helpful methods and properties:

Properties
calendar.appLink to global app instance
calendar.containerElCalendar wrapping container HTML element (when inline calendar is in use)
calendar.$containerElDom7 instance with calendar wrapping container HTML element (when inline calendar is in use)
calendar.elCalendar HTML element
calendar.$elDom7 instance with calendar HTML element
calendar.inputElCalendar input HTML element (passed in inputEl parameter)
calendar.$inputElDom7 instance with calendar input HTML element (passed in inputEl parameter)
calendar.valueArray where each item represents selected date
calendar.openedtrue if Calendar is currently opened
calendar.inlinetrue when inline calendar is in use
calendar.colsArray with specified Calendar columns. Each column also has its own methods and properties (look below)
calendar.urlCalendar URL (that was passed in url parameter)
calendar.viewCalendar View (that was passed in view parameter) or found parent view
calendar.paramsObject with initialization parameters
Methods
calendar.setValue(values)Set new selected dates. values is array where each item represents selected date
calendar.getValue()Returns current calendar value
calendar.addValue()Adds value to the values array. Useful in case if multiple selection is enabled (with multiple: true parameter)
calendar.update()Rerenders calendar. Useful in case you added/changed values dynamically and need to update calendar layout
calendar.nextMonth(duration)Calendar transition to next month for specified duration in ms
calendar.prevMonth(duration)Calendar transition to previous month for specified duration in ms
calendar.nextYear()Calendar transition to next year
calendar.prevYear()Calendar transition to previous year
calendar.setYearMonth(year, month, duration)Calendar transition to specified year, month for specified duration in ms
calendar.open()Open Calendar
calendar.close()Close Calendar
calendar.destroy()Destroy Calendar instance and remove all events
calendar.on(event, handler)Add event handler
calendar.once(event, handler)Add event handler that will be removed after it was fired
calendar.off(event, handler)Remove event handler
calendar.off(event)Remove all handlers for specified event
calendar.emit(event, …args)Fire event on instance

Calendar Events

Calendar will fire the following DOM events on calendar element and events on app and calendar instance:

DOM Events

EventTargetDescription
calendar:openCalendar Element<div class=”calendar”>Event will be triggered when Calendar starts its opening animation
calendar:openedCalendar Element<div class=”calendar”>Event will be triggered after Calendar completes its opening animation
calendar:closeCalendar Element<div class=”calendar”>Event will be triggered when Calendar starts its closing animation
calendar:closedCalendar Element<div class=”calendar”>Event will be triggered after Calendar completes its closing animation

App and Calendar Instance Events

Calendar instance emits events on both self instance and app instance. App instance events has same names prefixed with calendar.

EventTargetArgumentsDescription
dayClickcalendar(calendar, dayEl, year, month, day)Event will be triggered after click on calendar day element
calendarDayClickapp
changecalendar(calendar, value)Event will be triggered when calendar value changes
calendarChangeapp
monthAddcalendar(calendar, monthEl)Event will be triggered when new month HTML layout has been added. Useful if you need to postprocess added html elements
calendarMonthAddapp
monthYearChangeStartcalendar(calendar, year, month)Event will be triggered in the begining of transition to next month
calendarMonthYearChangeStartapp
monthYearChangeEndcalendar(calendar, year, month)Event will be triggered after transition to next month
calendarMonthYearChangeEndapp
initcalendar(calendar)Event will be triggered when calendar initialized
calendarInitapp
opencalendar(calendar)Event will be triggered when Calendar starts its opening animation. As an argument event handler receives calendar instance
calendarOpenapp
openedcalendar(calendar)Event will be triggered after Calendar completes its opening animation. As an argument event handler receives calendar instance
calendarOpenedapp
closecalendar(calendar)Event will be triggered when Calendar starts its closing animation. As an argument event handler receives calendar instance
calendarCloseapp
closedcalendar(calendar)Event will be triggered after Calendar completes its closing animation. As an argument event handler receives calendar instance
calendarClosedapp
beforeDestroycalendar(calendar)Event will be triggered right before Calendar instance will be destroyed. As an argument event handler receives calendar instance
calendarBeforeDestroyapp

Examples

Default Setup

  1. <div class="block-title">Default setup</div>
  2. <div class="list no-hairlines-md">
  3. <ul>
  4. <li>
  5. <div class="item-content item-input">
  6. <div class="item-inner">
  7. <div class="item-input-wrap">
  8. <input type="text" placeholder="Your birth date" readonly="readonly" id="demo-calendar-default"/>
  9. </div>
  10. </div>
  11. </div>
  12. </li>
  13. </ul>
  14. </div>
  1. var calendarDefault = app.calendar.create({
  2. inputEl: '#demo-calendar-default',
  3. });

Custom Date Format

  1. <div class="block-title">Custom date format</div>
  2. <div class="list no-hairlines-md">
  3. <ul>
  4. <li>
  5. <div class="item-content item-input">
  6. <div class="item-inner">
  7. <div class="item-input-wrap">
  8. <input type="text" placeholder="Select date" readonly="readonly" id="demo-calendar-date-format"/>
  9. </div>
  10. </div>
  11. </div>
  12. </li>
  13. </ul>
  14. </div>
  1. var calendarDateFormat = app.calendar.create({
  2. inputEl: '#demo-calendar-date-format',
  3. dateFormat: 'DD, MM dd, yyyy'
  4. });

Multiple Values

  1. <div class="block-title">Multiple Values</div>
  2. <div class="list no-hairlines-md">
  3. <ul>
  4. <li>
  5. <div class="item-content item-input">
  6. <div class="item-inner">
  7. <div class="item-input-wrap">
  8. <input type="text" placeholder="Select multiple dates" readonly="readonly" id="demo-calendar-multiple"/>
  9. </div>
  10. </div>
  11. </div>
  12. </li>
  13. </ul>
  14. </div>
  1. var calendarMultiple = app.calendar.create({
  2. inputEl: '#demo-calendar-multiple',
  3. dateFormat: 'M dd yyyy',
  4. multiple: true
  5. });

Range Picker

  1. <div class="block-title">Range Picker</div>
  2. <div class="list no-hairlines-md">
  3. <ul>
  4. <li>
  5. <div class="item-content item-input">
  6. <div class="item-inner">
  7. <div class="item-input-wrap">
  8. <input type="text" placeholder="Select date range" readonly="readonly" id="demo-calendar-range"/>
  9. </div>
  10. </div>
  11. </div>
  12. </li>
  13. </ul>
  14. </div>
  1. var calendarRange = app.calendar.create({
  2. inputEl: '#demo-calendar-range',
  3. dateFormat: 'M dd yyyy',
  4. rangePicker: true
  5. });

Open In Modal

  1. <div class="block-title">Open in Modal</div>
  2. <div class="list no-hairlines-md">
  3. <ul>
  4. <li>
  5. <div class="item-content item-input">
  6. <div class="item-inner">
  7. <div class="item-input-wrap">
  8. <input type="text" placeholder="Select date" readonly="readonly" id="demo-calendar-modal"/>
  9. </div>
  10. </div>
  11. </div>
  12. </li>
  13. </ul>
  14. </div>
  1. var calendarModal = app.calendar.create({
  2. inputEl: '#demo-calendar-modal',
  3. openIn: 'customModal',
  4. header: true,
  5. footer: true,
  6. dateFormat: 'MM dd yyyy',
  7. });

With Events

  1. <div class="block-title">With Events</div>
  2. <div class="list no-hairlines-md">
  3. <ul>
  4. <li>
  5. <div class="item-content item-input">
  6. <div class="item-inner">
  7. <div class="item-input-wrap">
  8. <input type="text" placeholder="Select date" readonly="readonly" id="demo-calendar-events"/>
  9. </div>
  10. </div>
  11. </div>
  12. </li>
  13. </ul>
  14. </div>
  1. var now = new Date();
  2. var today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
  3. var weekLater = new Date().setDate(today.getDate() + 7);
  4. var calendarEvents = app.calendar.create({
  5. inputEl: '#demo-calendar-events',
  6. dateFormat: 'M dd yyyy',
  7. events: [
  8. {
  9. from: today,
  10. to: weekLater
  11. },
  12. //- more events this day
  13. {
  14. date: today,
  15. color: '#ff0000'
  16. },
  17. {
  18. date: today,
  19. color: '#00ff00'
  20. },
  21. ]
  22. });

Disabled Dates

  1. <div class="block-title">Disabled Dates</div>
  2. <div class="list no-hairlines-md">
  3. <ul>
  4. <li>
  5. <div class="item-content item-input">
  6. <div class="item-inner">
  7. <div class="item-input-wrap">
  8. <input type="text" placeholder="Select date" readonly="readonly" id="demo-calendar-disabled"/>
  9. </div>
  10. </div>
  11. </div>
  12. </li>
  13. </ul>
  14. </div>
  1. var today = new Date();
  2. var weekLater = new Date().setDate(today.getDate() + 7);
  3. var calendarDisabled = app.calendar.create({
  4. inputEl: '#demo-calendar-disabled',
  5. dateFormat: 'M dd yyyy',
  6. disabled: {
  7. from: today,
  8. to: weekLater
  9. }
  10. });

Inline With Custom Toolbar

  1. <div class="block-title">Inline with custom toolbar</div>
  2. <div class="block block-strong no-padding">
  3. <div id="demo-calendar-inline-container"></div>
  4. </div>
  1. var $$ = Dom7;
  2. var monthNames = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August' , 'September' , 'October', 'November', 'December'];
  3. var calendarInline = app.calendar.create({
  4. containerEl: '#demo-calendar-inline-container',
  5. value: [new Date()],
  6. weekHeader: false,
  7. renderToolbar: function () {
  8. return '<div class="toolbar calendar-custom-toolbar no-shadow">' +
  9. '<div class="toolbar-inner">' +
  10. '<div class="left">' +
  11. '<a href="#" class="link icon-only"><i class="icon icon-back ' + (app.theme === 'md' ? 'color-black' : '') + '"></i></a>' +
  12. '</div>' +
  13. '<div class="center"></div>' +
  14. '<div class="right">' +
  15. '<a href="#" class="link icon-only"><i class="icon icon-forward ' + (app.theme === 'md' ? 'color-black' : '') + '"></i></a>' +
  16. '</div>' +
  17. '</div>' +
  18. '</div>';
  19. },
  20. on: {
  21. init: function (c) {
  22. $$('.calendar-custom-toolbar .center').text(monthNames[c.currentMonth] +', ' + c.currentYear);
  23. $$('.calendar-custom-toolbar .left .link').on('click', function () {
  24. calendarInline.prevMonth();
  25. });
  26. $$('.calendar-custom-toolbar .right .link').on('click', function () {
  27. calendarInline.nextMonth();
  28. });
  29. },
  30. monthYearChangeStart: function (c) {
  31. $$('.calendar-custom-toolbar .center').text(monthNames[c.currentMonth] +', ' + c.currentYear);
  32. }
  33. }
  34. });