Contents

Event Calendar

Basic usage

Create an event calendar with default functionality:

Javascript
mobiscroll.eventcalendar('#eventcalendar', {
    data: [{
        start: new Date(2016, 1, 1), 
        end: new Date(2016, 1, 2), 
        text: 'Conference', 
        color: 'red' 
    }, { 
        d: '12/25', 
        text: 'Christmas' 
    }]
});
HTML
<input id="eventcalendar" />

Adding events dynamically

An example of loading events dynamically when the calendar month is changed.

mobiscroll.eventcalendar('#eventcalendar', {
    onMonthLoading: function (event, inst) {
        var year = event.year,
            month = event.month;

        // Load events for (year, month), (year, month - 1), (year, month + 1)
        $.ajax({
            url: 'http://www.example.com/getevents?year=' + year + '&month=' + month,
            dataType: 'json',
            success : function (data) {

                var events = [];

                for (var i = 0; i < data.length; i++) {
                    events.push({
                        d: new Date(data[i].date), // Make sure that a javascript date object is passed
                        text: data[i].text
                    });
                }

                inst.setEvents(events);
            }
        });
    }
});

Options

Name Type Default value Description
anchor String or HTMLElement undefined Specifies the anchor element for positioning, if display is set to 'bubble'. If undefined, it defaults to the element on which the component was initialized.
animate String or Boolean undefined Animation to use for show/hide (if display is not inline). Possible values:
  • 'fade'
  • 'flip'
  • 'pop'
  • 'swing'
  • 'slidevertical'
  • 'slidehorizontal'
  • 'slidedown'
  • 'slideup'
If false, turns the animation off.
buttons Array ['set', 'cancel'] Buttons to display. Each item in the array will be a button. A button can be specified as a string, or as a button object.

If a string, it must be one of the predifined buttons:
  • 'set' - Sets the value.
  • 'clear' - Clears the value.
  • 'cancel' - Dismisses the popup.
To modify the text of the predfined buttons, you can use the setText, clearText , cancelText settings.

If an object, it may have the following properties:
  • text String - Text of the button.
  • handler String, Function - The function which will run when the button is pressed. If a string, it must be one of the predefined button handlers:
    • 'set' - Sets the value.
    • 'clear' - Clears the value.
    • 'cancel' - Dismisses the popup.
  • icon String (Optional) - Icon of the button.
  • cssClass String (Optional) - Css class of the button.
Predefined and custom buttons example
buttons: [ 
    'set',
    { 
        text: 'Custom',
        icon: 'checkmark',
        cssClass: 'my-btn', 
        handler: function (event, inst) { 
            alert('Custom button clicked!'); 
        } 
    },
    'cancel'
]
Predefined button handler example
buttons: [
    'set',
    { 
        text: 'Hide',
        handler: 'cancel',
        icon: 'close',
        cssClass: 'my-btn'
    }
]
calendarHeight Integer undefined Set the height of the calendar.
calendarScroll String 'horizontal' Possible values:
  • 'horizontal' - Horizontal scroll.
  • 'vertical' - Vertical scroll.
calendarWidth Integer undefined Set the width of the calendar (when layout is fixed).
closeOnOverlayTap Boolean true If true, the popup is closed on overlay tap/click.
context String or HTMLElement 'body' Context in which mobiscroll is appended and positioned (if not inline). Can be a selector string or a DOM element.
data Object undefined Add events to the calendar. There are four ways to specify events:
  • exact dates, both start and end dates - javascript Date objects for multi-day events:
    { start: new Date(2014, 5, 5), end: new Date(2014, 5, 7), text: 'My event' }
  • exact dates - javascript Date objects:
    { d: new Date(2014, 5, 5), text: 'My event' }
  • days of week - number of week day (0 - 6) prefixed with 'w':
    { d: 'w6', text: 'My event' }
  • days of month - number (e.g. every month's 2nd day) or a string in 'x/y' format (e.g. 12/24 means every year's 24th December):
    { d: 2, text: '2nd of the month' }
Events can be added and removed dynamically (e.g. in the onMonthChange event) with the event management methods:
Previous and next months are always preloaded, so if events are loaded at runtime, they must be loaded for the previous and next months as well.
On day tap a popup bubble will show up containing the event list.
Text and color can be also specified for the events.
A sample configuration
data: [
    { 
        start: new Date(2012,4,4), 
        end: new Date(2012,4,5), 
        text: 'Conference', 
        color: 'red' 
    }, 
    { 
        d: '12/25', 
        text: 'Christmas' 
    } 
] 
display String 'center' Controls the positioning of the component. Possible options:
  • 'center' - The component appears as a popup at the center of the viewport.
  • 'inline' - If called on div element, the component is placed inside the div (overwriting existing content), otherwise is placed after the original element.
  • 'bubble' - The component appears as a bubble positioned to the element defined by the 'anchor' setting. By default the anchor is the original element.
  • 'top' - The component appears docked to the top of the viewport.
  • 'bottom' - The component appears docked to the bottom of the viewport.
events Object undefined Specify the events for the calendar. There are four ways to specify event dates:
  • exact dates, both start and end dates - javascript Date objects for multi-day events:
    { start: new Date(2014, 5, 5), end: new Date(2014, 5, 7), text: 'My event' }
  • exact dates - javascript Date objects:
    { d: new Date(2014, 5, 5), text: 'My event' }
  • days of week - number of week day (0 - 6) prefixed with 'w':
    { d: 'w6', text: 'My event' }
  • days of month - number (e.g. every month's 2nd day) or a string in 'x/y' format (e.g. 12/24 means every year's 24th December):
    { d: 2, text: '2nd of the month' }
A sample configuration
events: [ 
    { 
        start: new Date(2012,4,4), 
        end: new Date(2012,4,5), 
        text: 'Conference', 
        color: 'red' 
    }, 
    { 
        d: '12/25', 
        text: 'Christmas' 
    } 
] 
focusOnClose Boolean, String or jQuery Object true Element to focus after the popup is closed. If undefined, the original element will be focused. If false, no focusing will occur.
focusTrap Boolean true If not in inline mode, focus won't be allowed to leave the popup.
headerText Mixed false Specifies a custom string which appears in the popup header.
If the string contains the '{value}' substring, it is replaced with the formatted value of the eventcalendar.
If it's set to false, the header is hidden.
If a function is passed, it receives the formatted value as parameter and the returned value appears in the header.
The default value depends on the theme:

Mobiscroll: false
Android Holo: {value}
Bootstrap: {value}
iOS: false
jQuery Mobile: {value}
Material: false
Windows Phone: false
invalid Array [] An array containing the invalid values.
layout String undefined Sets the layout of the component. Possible values:
  • 'liquid' - The calendar view expand to the maximum available width
    In 'top' or 'bottom' display mode this is the default behavior.
    In 'center'display mode it will also expand the height to the height of the viewport.
  • 'fixed' or undefined - The width and height of the calendar is controlled by the calendarWidth and calendarHeight options.
max Date new Date(currYear + 1, 11, 31) Maximum date and time that can be selected.
Date
mobiscroll.calendar('#mydate', {
    max: new Date(2015, 7, 14)
});
Date and time
mobiscroll.calendar('#mydatetime', { 
    controls: ['calendar', 'time'],
    max: new Date(2015, 7, 14, 16, 57)
});
min Date new Date(currYear - 100, 0, 1) Minimum date and time that can be selected.
Date
mobiscroll.calendar('#mydate', { 
    min: new Date(2015, 7, 14) 
});
Date and time
mobiscroll.calendar('#mydatetime', {
    controls: ['calendar', 'time'],
    min: new Date(2015, 7, 14, 16, 57)
});
months Number
String
1 Number of months to display. Set to 'auto' to decide on runtime how many months can be displayed.
showEventCount Boolean false
  • false - Display marks on days with events.
  • true - Display text indicating the number of events on days with events.
showOnFocus Boolean false Pops up the component on element focus.
showOnTap Boolean true Pops up the component on element tap.
showOuterDays Boolean true Show or hide days from previous and next months.
theme String undefined Sets the visual appearance of the component.

If it is 'auto' or undefined, the theme will automatically be chosen based on the platform. If the theme for the specific platform is not present, it will revert to the Mobiscroll theme.

Supplied themes:
  • 'android-holo' - Android 4.x theme
  • 'android-holo-light' - Android 4.x theme (light version)
  • 'bootstrap' - Bootstrap themes
  • 'ios' - new iOS 7, 8, 9 theme
  • 'material' - Material theme (Android 5.x)
  • 'material-dark' - Material dark theme (Android 5.x)
  • 'jqm' - Integrates with jQuery Mobile look & feel
  • 'mobiscroll' - Mobiscroll theme
  • 'mobiscroll-dark' - Mobiscroll Dark theme
  • 'wp' - Windows Phone Metro UI theme
  • 'wp-light' - Windows Phone Metro UI theme (light version)
It's possible to create custom themes in css by prefixing any css class used in the eventcalendar markup with the theme name and the 'mbsc' prefix, e.g.: .mbsc-my-theme .dwwr { /* My CSS */ }, and set the theme option to 'my-theme'
Make sure that the theme you set is included in the downloaded package.
valid Object null Can be used to override invalid dates and times. E.g. if every Thursday is set to invalid by 'w4', but you want May 15th, 2014 to be valid you can do it using the valid option. The syntax is the same as for the invalid option.
weekCounter String undefined
  • 'year' - Display week number in the year
  • 'month' - Display week number in the month
weekDays String 'short' Control the format of week days in the calendar header. Can be `full`, `short` or `min`.
yearChange Boolean true If true, the calendar can be navigated by year and by month separately from the header controls, otherwise only on a month by month basis.

Setting options runtime (changing options dynamically)

There are two ways to modify options after initalization

  1. Using the option method.

    The option method always triggers reinitialization. Most of the settings can be updated only this way, updating without initialization has no effect, because the markup is already generated. If the scroller was visible, the reinitialization hides it and it's not shown again automatically (except in inline display mode).

    Javascript
    // Modify options
    mobiscrollInstance.option({ 
        theme: 'ios', 
        lang: 'de'
    });
    HTML
    <input id="mobiscroll"/>
  2. Modify directly the settings object.

    Useful when changing dynamic settings, which do not need redraw (e.g. readonly, calendar marked days).

    // Modify a setting
    mobiscrollInstance.settings.readonly = true;
    
    // Modify settings in an event
    mobiscroll.eventcalendar('#mobiscroll', {
        onBeforeShow: function (event, inst) {
            inst.settings.readonly = true;
        }
    });

Events

Name Description
onBeforeClose(event, inst) Triggered before the component closes. Close can be prevented by returning false from the handler function.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
    • button: String - The name of the button which triggered the component to close ('set', or 'cancel').
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onBeforeClose: function (event, inst) {
    }
});
onBeforeShow(event, inst) Triggered before the component is shown. It is useful if you want to modify the settings object before generating the markup. It can be used also to prevent the showing the control by returning false.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onBeforeShow: function (event, inst) {
    }
});
onClose(event, inst) Triggered when the component is closed.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onClose: function (event, inst) {
    }
});
onDayChange(event, inst) Triggered when a day is selected on the calendar. Returning false from the handler function will prevent day selection.

Parameters

  • event: Object - The event object has the following properties:
    • date: The selected date as a Date object.
    • marked: If the day is marked, contains the marked object passed in the settings, otherwise false.
    • selected: Specifies which date was selected ('start' or 'end').
    • target: The table cell HTML DOM element.
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onDayChange: function (event, inst) {
    }
});
onDestroy(event, inst) Triggered when the component is destroyed.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onDestroy: function (event, inst) {
    }
});
onEventSelect(event, inst) Triggered when the user taps/clicks on an event in the event bubble.

Parameters

  • event: Object - The event object has the following properties:
    • event: Object - The selected event.
    • domEvent: Object - The click/tap DOM event.
    • date: Object - The date clicked.
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onEventSelect: function (event, inst) {
    }
});
onInit(event, inst) Triggered when the component is initialized.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onInit: function (event, inst) {
    }
});
onMarkupReady(event, inst) Triggered when the html markup of the component is generated, but it is not yet shown. It is useful, if you want to make modifications to the markup (e.g. add custom elements), before the positioning runs.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onMarkupReady: function (event, inst) {
    }
});
onMonthChange(event, inst) Triggered when the user changes the month (with buttons or swipe).

Parameters

  • event: Object - The event object has the following properties:
    • year: Object - The year object.
    • month: Object - The month object.
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onMonthChange: function (event, inst) {
    }
});
onMonthLoaded(event, inst) Triggered when the user changes the month (with buttons or swipe) and the animation has finished.

Parameters

  • event: Object - The event object has the following properties:
    • year: Number - Year.
    • month: Number - Month.
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onMonthLoaded: function (event, inst) {
    }
});
onMonthLoading(event, inst) Triggered before the month markup is starting to render.

Parameters

  • event: Object - The event object has the following properties:
    • year: Number - Year.
    • month: Number - Month.
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onMonthLoading: function (event, inst) {
    }
});
onPosition(event, inst) Triggered when the component is positioned (on initial show and resize / orientation change).

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
    • windowWidth: Number - The window width.
    • windowHeight: Number - The window height.
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onPosition: function (event, inst) {
    }
});
onShow(event, inst) Triggered when the component is shown.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the eventcalendar.

Example

mobiscroll.eventcalendar('#mobiscroll', {
    onShow: function (event, inst) {
    }
});

Methods

Name Description
addEvent(events) Adds one or more events to the event list.

Parameters

  • events: Object or Array - The javascript event object(s) to add.

Returns: Array

  • An array containing the list of IDs generated for the events.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.addEvent([{ 
    start: new Date(2016, 1, 1), 
    end: new Date(2016, 1, 2), 
    text: 'Conference', 
    color: 'red' 
}, { 
    d: '12/25', 
    text: 'Christmas' 
}]);
destroy() Destroys the component. This will return the element back to its pre-init state.

Returns: Object

  • Returns the element back to its pre-init state.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.destroy();
getInst() Returns the object instance.

Returns: Object

  • The object instance.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.getInst();
hide([ prevAnim ] [, btn ]) Hides the component.

Parameters

  • prevAnim (Optional): Boolean - If true, hide will not be animated.
  • btn (Optional): String - Specifies which button caused the component to hide, and it's passed to the onBeforeClose event.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.hide();
isVisible() Returns a boolean indicating whether the component is visible or not.

Returns: Boolean

  • True if the component is visible, false if it's not.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.isVisible();
navigate(date [, animate ]) Display a specific month on the calendar without setting the date.

Parameters

  • date: Date - The specific month on the calendar.
  • animate (Optional): Boolean - If true, navigate will be animated.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.navigate(new Date(2016, 1, 1));
option(options) Sets one or more options for the component.

Parameters

  • options: Object - A map of option-value pairs to set.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.option({
    display: 'bottom',
    lang: 'de'
});
position([check]) Recalculates the position of the component (if not inline).

Parameters

  • check (Optional): Boolean - If true, the function checks if viewport size changed after last position call, if false or ommitted, position is recalculated anyway.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.position();
redraw() Redraws the calendar view, without reloading the data (the onMonthLoading event will not trigger).

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.redraw();
refresh() Refreshes the calendar view.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.refresh();
removeEvent(eventIDs) Removes one or more events from the event list based on IDs. IDs are generated internally. The generated ids are returned by the addEvent or getEvents methods.

Parameters

  • eventIDs: Array - An array containing the ID of one or more list events.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.removeEvent([1, 3]);
setEvents(events) Set the events for the calendar. The actual list is overwritten. Returns the list of IDs generated for the events.

Parameters

  • events: Array - An array containing the events.

Returns: Array

  • An array containing the event IDs.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.setEvents([{ 
    start: new Date(2016, 1, 1), 
    end: new Date(2016, 1, 2), 
    text: 'Conference',
    color: 'red'  
}, { 
    d: '12/25', 
    text: 'Christmas' 
}]);
show([ prevAnim ] [, prevFocus ]) Shows the component.

Parameters

  • prevAnim (Optional): Boolean - If true, show will not be animated.
  • prevFocus (Optional): Boolean - If true, the popup will not be focused right after show.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.show();
tap(el, handler) Attaches the handler function to the tap event of element el.

Parameters

  • el: Object - The element with tap event.
  • handler: Function - If the action was initiated with touch event, handler is called on touchend, otherwise on click.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.tap('#element', function () { alert("It's a tap!"); });

Localization

Name Type Default value Description
amText String 'am' Text for AM
dateFormat String 'mm/dd/yy' The format for parsed and displayed dates
  • m - month of year (no leading zero)
  • mm - month of year (two digit)
  • M - month name short
  • MM - month name long
  • d - day of month (no leading zero)
  • dd - day of month (two digit)
  • D - day of week (short)
  • DD - day of week (long)
  • y - year (two digit)
  • yy - year (four digit)
  • '...' - literal text
  • '' - single quote
  • anything else - literal text
dayNames Array ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'] The list of long day names, starting from Sunday, for use as requested via the dateFormat setting
dayNamesMin Array ['S', 'M', 'T', 'W', 'T', 'F', 'S'] The list of minimal day names, starting from Sunday, for use as requested via the dateFormat setting
dayNamesShort Array ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] The list of abbreviated day names, starting from Sunday, for use as requested via the dateFormat setting
firstDay Integer 0 Set the first day of the week: Sunday is 0, Monday is 1, etc.
headerText Mixed '{value}' Specifies a custom string which appears in the popup header. If the string contains '{value}' substring, it is replaced with the formatted value of the eventcalendar. If it's set to false, the header is hidden. If a function is passed, it receives the formatted value as parameter and the returned value appears in the header
lang String 'en-US' Language of the component. Based on the language string the component loads the language based default settings from the language modules.
Supported languages:
  • 'en' or 'en-US' or undefined - English
  • 'en-UK' or 'en-GB' - English (UK)
  • 'ca' - Catalan
  • 'cs' - Czech
  • 'zh' - Chinese
  • 'da' - Danish
  • 'de' - German
  • 'es' - Spanish
  • 'fa' - Farsi
  • 'fr' - French
  • 'he' - Hebrew
  • 'hu' - Hungarian
  • 'it' - Italian
  • 'ja' - Japanese
  • 'nl' - Dutch
  • 'no' - Norwegian
  • 'pl' - Polish
  • 'pt-BR' - Brazilian Portuguese
  • 'pt-PT' - European Portuguese
  • 'ro' - Romanian
  • 'ru' - Russian
  • 'ru-UA' - Russian (UA)
  • 'sk' - Slovak
  • 'sv' - Swedish
  • 'tr' - Turkish
monthNames Array ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'] The list of full month names, for use as requested via the dateFormat setting
monthNamesShort Array ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] The list of abbreviated month names, for use as requested via the dateFormat setting
nowText String 'Now' Label for the 'Now' button
pmText String 'pm' Text for PM
rtl Boolean false Right to left display.
timeFormat String 'hh:ii A' The format for parsed and displayed dates
  • h - 12 hour format (no leading zero)
  • hh - 12 hour format (leading zero)
  • H - 24 hour format (no leading zero)
  • HH - 24 hour format (leading zero)
  • i - minutes (no leading zero)
  • ii - minutes (leading zero)
  • s - seconds (no leading zero)
  • ss - seconds (leading zero)
  • a - lowercase am/pm
  • A - uppercase AM/PM
  • '...' - literal text
  • '' - single quote
  • anything else - literal text