General
Getting Started
Quick Install
Using with Cordova
Using with Vue.js
Using with Stencil.js
Mobiscroll CLI
ES6 Modules
Instance
Customizing the Look and Feel
Upgrade From Trial
Utility functions
Typings
Update version
Upgrade Guide v4
Upgrade Guide v3
Date & Time pickers
Event Calendar
Form components
Accordion
Alerts & Notifications
Buttons
Checkbox
Dropdown
Forms
Progress
Radio Buttons
Rating
Segmented
Slider
Stepper
Switch
Textfields
Timer
Gesture enabled responsive list
Numeric pickers
Pickers & dropdowns
Page layout & navigation
Tools
Accessibility
Event Calendar
Starting from version 4.2.0 it is also possible to pass ISO 8601 date strings or moment objects as well,
instead of just javascript date objects, for every setting where dates are used.
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);
}
});
}
});
Typescript Types
When using with typescript, the following types are available for the Eventcalendar:
| Type | Description |
|---|---|
| Eventcalendar | Type of the Eventcalendar instance |
| MbscEventcalendarOptions | Type of the settings object that is used to initialize the component |
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:
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.
When the passed array does not contain the predefined 'set' button, the auto-selection will be turned on.
Selecting a value on the UI this way, will be set to the input immediately.
If there are more than one wheels shown, the control will close on overlay tap. Otherwise tapping a value on the wheel will also close the control.
If a string, it must be one of the predefined buttons:
If an object, it may have the following properties:
Predefined and custom buttons example
Predefined button handler example
|
| calendarHeight | Integer | undefined |
Set the height of the calendar. The height of the calendar view impacts the number of labels that fit into a table cell. A show more label will be displayed for events that don't fit. |
| calendarScroll | String | 'horizontal' |
Possible values:
|
| calendarSystem | String | 'gregorian' |
Defines the basic structure of the calendar.
|
| 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. |
| colors | Array | undefined |
Change the color of certain dates on the calendar. There are four ways to specify days:
inst.settings.colors object
(e.g. in the onPageChange event).
Previous and next months are always preloaded, so if colored days are loaded at runtime,
they must be loaded for the previous and next months as well.
A sample configuration
|
| context | String, HTMLElement | 'body' |
The DOM element in which the popups (event popover, year and month picker) are rendered. Can be a selector string or a DOM element. |
| data | Array | undefined |
Events for the calendar, as an array of event objects. The event object supports the following properties:
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
The event objects may have additional custom properties as well.
The custom properties are not used by the eventcalendar, but they are kept and will be available anywhere the event objects are used.
E.g. the onEventSelect
event will receive the event object as argument, containing the custom properties as well.
There are four ways to specify events:
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
|
| eventBubble | Boolean | true |
If true, on day selection it will show the list of events for that day in a popup bubble.
|
| 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. |
| formatDuration | function(start: Date, end: Date, event: Object): string | undefined |
A function which formats the duration of the events displayed inside the event popover. If not specified, a built in formatter function is used. |
| 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 | undefined |
An array containing the invalid values. |
| labels | Array | undefined |
Specify labels for calendar days. A label object can have the following properties:
A sample configuration
|
| layout | String |
'liquid'
|
Sets the layout of the component. Possible values:
|
| marked | Array | undefined |
Mark certain dates on the calendar. There are four ways to specify marked days:
inst.settings.marked object
(e.g. in the onPageChange event).
Previous and next months are always preloaded, so if marked days are loaded at runtime,
they must be loaded for the previous and next months as well.
A sample configuration
To display text and/or icons instead of the marks use the labels option.
|
| max | Date, String, Object |
undefined
|
Maximum date and time that can be selected.
Date
Date and time
|
| min | Date, String, Object |
undefined
|
Minimum date and time that can be selected.
Date
Date and time
|
| responsive | Object | undefined |
Specify different settings for different viewport widths, in a form of an object,
where the keys are the name of the breakpoints, and the values are objects containing
the settings for the given breakpoint.
There are five predefined breakpoints:
breakpoint
property specifying the min-width in pixels.
Example:
|
| showEventCount | Boolean | false |
|
| showOnFocus | Boolean |
false - on desktop
true - on mobile
|
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.
Hiding outer days only works in case of month view, and not supported for week view.
|
| 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 default to the Mobiscroll theme.
Supplied themes:
Starting from v4.9.0 setting directly the dark version of the theme is deprecated.
Use the themeVariant setting instead to control the light / dark appearance of the theme.
Make sure that the theme you set is included in the downloaded package.
|
| themeVariant | String | undefined |
Controls which variant of the theme will be used (light or dark). Possible values:
If not set, only the theme setting will determine which theme to use. To use the setting with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with '-dark',
e.g.: 'my-theme' and 'my-theme-dark'.
The setting will not have any effect if the theme setting explicitly
sets the dark version of a theme, e.g.
theme: 'ios-dark'.
|
| valid | Object | null |
Can be used to override invalid dates and times. E.g. if every Thursday is set to invalid, 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.
It's important if you want to use the valid setting together with invalid make sure to set: invalid day with valid day, invalid time with valid time or both
invalid date and time with valid date and time. So in case you use an invalid day and a valid time, this will not override the invalid setting.
A sample configuration
|
| view | Object | { calendar: { type: 'month', popover: true } } |
Configures the event calendar view elements.
Properties
Example |
| weekCounter | String | undefined |
|
| weekDays | String | 'short' |
Control the format of week days in the calendar header. Can be `full`, `short` or `min`. |
| yearChange | Boolean |
false
|
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
-
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"/> -
Modify directly the
settingsobject.
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
Example |
|
| 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
Example |
|
| onClose(event, inst) |
Triggered when the component is closed.
Parameters
Example |
|
| onDayChange(event, inst) |
Triggered when a day is selected on the calendar, but before the selection is actually done.
Returning false from the handler function will prevent day selection.
Parameters
Example |
|
| onDestroy(event, inst) |
Triggered when the component is destroyed.
Parameters
Example |
|
| onEventSelect(event, inst) |
Triggered when the user selects and event.
Parameters
Example |
|
| onInit(event, inst) |
Triggered when the component is initialized.
Parameters
Example |
|
| onLabelTap(event, inst) |
Triggered when the user taps/clicks on a label on the calendar.
Parameters
Example |
|
| 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
Example |
|
| onPageChange(event, inst) |
Triggered when the calendar page is changed (month or week, with buttons or swipe).
Parameters
Example |
|
| onPageLoaded(event, inst) |
Triggered when the calendar page is changed (month or week, with buttons or swipe) and the animation has finished.
Parameters
Example |
|
| onPageLoading(event, inst) |
Triggered before the markup of a calendar page (month or week) is starting to render.
Parameters
Example |
|
| onPosition(event, inst) |
Triggered when the component is positioned (on initial show and resize / orientation change).
Useful if dimensions needs to be modified before the positioning happens, e.g. set a custom width or height. Custom positioning can also be implemented here, in this case, returning false from the handler
function will prevent the built in positioning.
Parameters
Example |
|
| onSetDate(event, inst) |
Gets called every time a date or time is selected (from wheels or from calendar, or programatically). It also runs on initial show.
Parameters
Example |
|
| onShow(event, inst) |
Triggered when the component is shown.
Parameters
Example |
|
Methods
| Name | Description | |
|---|---|---|
| addEvent(events) |
Adds one or more events to the event list.
Parameters
Returns: Array
ExampleMethods can be called on an instance. For more details see calling methods |
|
| destroy() |
Destroys the component. This will return the element back to its pre-init state.
Returns: Object
ExampleMethods can be called on an instance. For more details see calling methods |
|
| getEvents([date]) |
Returns the list of events.
Parameters
Returns: Array
ExampleMethods can be called on an instance. For more details see calling methods |
|
| getInst() |
Returns the object instance.
Returns: Object
ExampleMethods can be called on an instance. For more details see calling methods |
|
| hide([ prevAnim ] [, btn ]) |
Hides the component.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| isVisible() |
Returns a boolean indicating whether the component is visible or not.
Returns: Boolean
ExampleMethods can be called on an instance. For more details see calling methods |
|
| navigate(date [, animate ]) |
Navigates to the specified date on the calendar and optionally opens the event popover
(only if popover is enabled and events exists for the specified date).
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| option(options) |
Sets one or more options for the component.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| position([check]) |
Recalculates the position of the component (if not inline).
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| redraw() |
Redraws the calendar view, without reloading the data (the onPageLoading event will not trigger).
ExampleMethods can be called on an instance. For more details see calling methods |
|
| refresh() |
Refreshes the calendar view.
ExampleMethods can be called on an instance. For more details see calling methods |
|
| 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
ExampleMethods can be called on an instance. For more details see calling methods |
|
| setEvents(events) |
Set the events for the calendar. The actual list is overwritten. Returns the list of IDs generated for the events.
Parameters
Returns: Array
ExampleMethods can be called on an instance. For more details see calling methods |
|
| setOptions(options) | ||
| show([ prevAnim ] [, prevFocus ]) |
Shows the component.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| tap(el, handler) |
Attaches the handler function to the tap event of element el.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
| updateEvent(event) |
Updates an event from the event list.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods |
|
Localization
| Name | Type | Default value | Description |
|---|---|---|---|
| allDayText | String | 'All-day' |
Text for all day events. |
| amText | String | 'am' |
Text for AM. |
| dateFormat | String |
'mm/dd/yy'
|
The format for parsed and displayed dates.
|
| 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. |
| eventsText | String | 'events' |
Text for the events word (plural). |
| eventText | String | 'event' |
Text for the event word. |
| 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 |
| labelsShort | Array | ['Yrs', 'Mths', 'Days', 'Hrs', 'Mins', 'Secs'] |
List of labels used when displaying the duration of events. |
| 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:
|
| 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. |
| moreEventsPluralText | String | undefined |
Text for the "more" label on the calendar, when there's not enough space to display all the labels for the day,
and there are more than one extra labels.
The {count} inside the string will be replaced with the number of extra labels.
When not specified, the moreEventsText setting is used for both plural and singular form.
|
| moreEventsText | String | '{count}' more |
Text for the "more" label on the calendar, when there's not enough space to display all the labels for the day.
The {count} inside the string will be replaced with the number of extra labels.
Use the moreEventsPluralText as well, if the plural form is different.
|
| noEventsText | String | 'No events' |
Text for empty event list. |
| 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
|
| todayText | String | 'Today' |
Label for the "Today" button. |
Customizing the appearance
While the provided pre-built themes are enough in many use cases, most of the times on top of adapting to a specific platform, you'd also like to match a brand or color scheme. Mobiscroll provides various ways to achieve this:
- Create custom themes using the theme builder - the custom themes can be also built using out theme builder, on a graphical user interface, without any coding, or the need for Sass support in your project.
- Create custom themes using Sass - use this, if you need multiple themes with different color variatons, in case you have pages with different colors, or you'd like to users to customize the colors of your app.
- Override the Sass color variables - the straightforward way to change the colors in one place throughout the application.
Override the Sass Color Variables
A convenient way to customize the colors of the Mobiscroll components is to override the Sass color variables.
Let's say your branding uses a nice red accent color, and you'd like that color to appear on the Mobiscroll components as well,
while still using platform specific themes (e.g. ios on iOS devices, material on Android devices, and mobiscroll on desktop).
You can override the accent color for every theme:
$mbsc-ios-accent: #e61d2a;
$mbsc-material-accent: #e61d2a;
$mbsc-mobiscroll-accent: #e61d2a;
@import "~@mobiscroll/Javascript/dist/css/mobiscroll.javascript.scss"
It's important that you override the variables BEFORE the scss file import, otherwise it won't make any difference.
Here's a complete guide on how to set up Mobiscroll with SASS support
You can also customize the colors on many levels:
- Theme specific variables (ex.
$mbsc-material-background,$mbsc-ios-dark-text) are applied to all components in a theme. Complete list of variables here. - Component specific global variables (ex.
$mbsc-card-background-light,$mbsc-listview-text-dark) are applied to all themes for a specific component. - Component and theme specific variables (ex.
$mbsc-ios-dark-form-background,$mbsc-material-input-text) are applied to a specific theme and a specific component.
Hereinafter you will see all the variables that are specific to the Eventcalendar component or affect its look:
Global variables
These variables are applied to all base themes: iOS, material, windows and mobiscroll.
They all come in pairs. One for the light and one for the dark variant in each theme.
| Variable name | Description |
|---|---|
| $mbsc-frame-background-light | Sets the background color of the Eventcalendar |
| $mbsc-frame-background-dark | |
| $mbsc-frame-text-light | Sets the text color of the Eventcalendar |
| $mbsc-frame-text-dark | |
| $mbsc-frame-accent-light | Sets the accent color of the Eventcalendar |
| $mbsc-frame-accent-dark | |
| $mbsc-frame-overlay-light | Sets the color of the overlay, when the Eventcalendar is shown as a modal |
| $mbsc-frame-overlay-dark | |
| $mbsc-calendar-mark-light | Sets the default color of the mark on marked days |
| $mbsc-calendar-mark-dark |
If you really want to get sophisticated or if a color doesn't look good on a specific theme and you want to overwrite it, you can fine tune all of the above variables individually for each theme. Below are the complete list of variables broken down to themes:
iOS theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-ios-frame-background | #ffffff | The Eventcalendar background color |
| $mbsc-ios-frame-text | #000000 | The Eventcalendar text color |
| $mbsc-ios-frame-accent | #007bff | The Eventcalendar accent color |
| $mbsc-ios-frame-overlay | rgba(0, 0, 0, 0.2) | Sets the color of the overlay, when the Eventcalendar is shown as a modal |
| $mbsc-ios-calendar-mark | #cccccc | Sets the default color of the mark on marked days |
iOS Dark theme
| $mbsc-ios-dark-frame-background | #0f0f0f | The Eventcalendar background color |
| $mbsc-ios-dark-frame-text | #ffffff | The Eventcalendar text color |
| $mbsc-ios-dark-frame-accent | #ff8400 | The Eventcalendar accent color |
| $mbsc-ios-dark-frame-overlay | rgba(255, 255, 255, .1) | Sets the color of the overlay, when the Eventcalendar is shown as a modal |
| $mbsc-ios-dark-calendar-mark | #333333 | Sets the default color of the mark on marked days |
Windows theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-windows-frame-background | #1a1a1a | The Eventcalendar background color |
| $mbsc-windows-frame-text | #262626 | The Eventcalendar text color |
| $mbsc-windows-frame-accent | #0078d7 | The Eventcalendar accent color |
| $mbsc-windows-frame-overlay | rgba(0, 0, 0, .7) | Sets the color of the overlay, when the Eventcalendar is shown as a modal |
| $mbsc-windows-calendar-mark | #262626 | Sets the default color of the mark on marked days |
Windows Dark theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-windows-dark-frame-background | #191919 | The Eventcalendar background color |
| $mbsc-windows-dark-frame-text | #ffffff | The Eventcalendar text color |
| $mbsc-windows-dark-frame-accent | #0078d7 | The Eventcalendar accent color |
| $mbsc-windows-dark-frame-overlay | rgba(0, 0, 0, .7) | Sets the color of the overlay, when the Eventcalendar is shown as a modal |
| $mbsc-windows-dark-calendar-mark | #ffffff | Sets the default color of the mark on marked days |
Material theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-material-frame-background | #eeeeee | The Eventcalendar background color |
| $mbsc-material-frame-text | #5b5b5b | The Eventcalendar text color |
| $mbsc-material-frame-accent | #009688 | The Eventcalendar accent color |
| $mbsc-material-frame-overlay | rgba(0, 0, 0, .6) | Sets the color of the overlay, when the Eventcalendar is shown as a modal |
| $mbsc-material-calendar-mark | #009688 | Sets the default color of the mark on marked days |
Material Dark theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-material-dark-frame-background | #303030 | The Eventcalendar background color |
| $mbsc-material-dark-frame-text | #c2c2c2 | The Eventcalendar text color |
| $mbsc-material-dark-frame-accent | #81ccc4 | The Eventcalendar accent color |
| $mbsc-material-dark-frame-overlay | rgba(0, 0, 0, .6) | Sets the color of the overlay, when the Eventcalendar is shown as a modal |
| $mbsc-material-dark-calendar-mark | #81ccc4 | Sets the default color of the mark on marked days |
Mobiscroll theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-mobiscroll-frame-background | #f7f7f7 | The Eventcalendar background color |
| $mbsc-mobiscroll-frame-text | #454545 | The Eventcalendar text color |
| $mbsc-mobiscroll-frame-accent | #4eccc4 | The Eventcalendar accent color |
| $mbsc-mobiscroll-frame-overlay | rgba(0, 0, 0, .7) | Sets the color of the overlay, when the Eventcalendar is shown as a modal |
| $mbsc-mobiscroll-calendar-mark | #454545 | Sets the default color of the mark on marked days |
Mobiscroll Dark theme
| Variable name | Default value | Description |
|---|---|---|
| $mbsc-mobiscroll-dark-frame-background | #263238 | The Eventcalendar background color |
| $mbsc-mobiscroll-dark-frame-text | #f7f7f7 | The Eventcalendar text color |
| $mbsc-mobiscroll-dark-frame-accent | #4fccc4 | The Eventcalendar accent color |
| $mbsc-mobiscroll-dark-frame-overlay | rgba(0, 0, 0, .7) | Sets the color of the overlay, when the Eventcalendar is shown as a modal |
| $mbsc-mobiscroll-dark-calendar-mark | #f7f7f7 | Sets the default color of the mark on marked days |
