Contents
v5
General Date & Time pickers Event Calendar Form components Pickers & dropdowns Page layout Tools Accessibility
Version 5.26.2 for JQuery
5.33.0
final
4.10.10
final
3.2.6
final
2.17.3
final
Javascript jQuery Angular React Vue
This version of the documentation is outdated. Check the latest version here!
General Date & Time pickers Event Calendar Form components Pickers & dropdowns Page layout
Grid Layout Popup
Tools Accessibility
This version of the documentation is outdated. Check the latest version here!

Event Calendar

Basic usage

The following example will create an event calendar with the default options.

Example
$('#eventcalendar').mobiscroll().eventcalendar();

For many more examples - simple and complex use-cases - check out the event calendar demos for jquery.

Data binding

The event calendar accepts an array of event objects through the data option of the component. The event array can be either a local static array, or populated on demand with remote requests.

Local data

To bind local data to the event calendar, you can simply assign a JavaScript array of objects to the data option of the component.

Example
$('#eventcalendar').mobiscroll().eventcalendar({
  data: [{
    start: new Date(2020, 2, 18, 8, 0),
    end: new Date(2020, 2, 18, 17, 0),
    title: 'My First Event'
  }, {
    start: new Date(2020, 2, 18, 9, 0),
    end: new Date(2020, 2, 20, 13, 0),
    title: 'My Second Event'
  }]
});

Remote data

You can load the data through an external request and use the setEvents method to pass the data to the component.

Example
$('#eventcalendar').mobiscroll().eventcalendar();

var inst = $('#eventcalendar').mobiscroll('getInst');

$.getJSON('https://example.com/events/', function (events) {
  inst.setEvents(events);
});

Load on demand

Use the onPageLoading event to load the data relevant to the currently active view. The event fires every time the date range of the view changes, for example when someone navigates the event calendar. Getting the events in real time as the user interacts with the UI improves load performance and always serves the most recent data.

You can pass the view variables - like month and year - in the URL and handle the filtering inside the API implmentation.

Example
$('#eventcalendar').mobiscroll().eventcalendar({
  data: [],
  onPageLoading: function (event, inst) {
    var fromDay = event.firstDay.toISOString();
    var toDay = event.lastDay.toISOString();

    $.getJSON('https://example.com/events?from=' + fromDay + '&to=' + toDay), function (events) {
      inst.setEvents(events);
    });
  }
});

Recurrence

For the data, colors, labels, marked, and invalid options it's possible to specify recurrence rules. The rule can be an object or a string in RRULE format.

Supported properties:

In string format the specified properties are separated by the ';' character.

As object
recurring: {
  repeat: 'daily',
  count: 5,
  interval: 2
}
As string
recurring: 'FREQ=DAILY;COUNT=5;INTERVAL=2'

Examples

Example
$('#eventcalendar').mobiscroll().eventcalendar({
    data: [{
        start: new Date(2020, 2, 18, 9, 0),
        end: new Date(2020, 2, 18, 17, 0),
        title: 'Repeat every 2 days 5 times',
        recurring: {
            repeat: 'daily',
            count: 5,
            interval: 2
        }
    }, {
        start: new Date(2020, 2, 17, 20, 0),
        end: new Date(2020, 2, 17, 22, 0),
        title: 'Football training every Monday and Wednesday',
        recurring: 'FREQ=WEEKLY;UNTIL=2020-06-17;BYDAY=MO,WE'
    }, {
        title: 'Pay the bills - on every first Friday of the months',
        recurring: {
            repeat: 'monthly',
            pos: 1,
            weekDays: 'FR',
        }   
    }]
});

Recurring exceptions

In case you would like to skip some dates from your rule, that's when the recurring exception come in handy. You can either set specific dates and/or a recurring rule as an exception, using the recurringException and the recurringExceptionRule properties.

Example
$('#eventcalendar').mobiscroll().eventcalendar({
    data: [{
        start: '2021-06-01',
        allDay: true,
        title: 'Repeat every day until the end of 2021, except every month\'s 15th',
        recurring: {
            repeat: 'daily',
            until: '2021-12-31'
        },
        // exact dates as exceptions
        recurringException: ['2021-07-10', '2021-07-11'],
        // recurring rule as an exception
        recurringExceptionRule: {
            repeat: 'monthly',
            day: 15
        }
    }, {
        start: '08:30',
        end: '10:00',
        title: 'Meeting every Monday and Friday, except every second month\'s 3rd',
        recurring: 'FREQ=WEEKLY;UNTIL=2021-06-01;BYDAY=MO,FR',
        recurringExceptionRule: 'FREQ=MONTHLY;BYMONTHDAY=3;INTERVAL=2'
    }]
});
In case you drag & drop an event on the calendar which is an occurrence of a recurring event, a new event will be created for the moved or resized event and the occurrence date will be added as a recurring exception to the original recurring event.

CRUD actions

You can use the addEvent, removeEvent and updateEvent methods for CRUD operations.

Here's an example for adding, removing, and updating an event.

Example
var guid = 3;
var events = [{
  id: 1,
  start: new Date(2020, 2, 18, 8, 0),
  end: new Date(2020, 2, 18, 17, 0),
  title: 'My First Event'
}, {
  id: 2,
  start: new Date(2020, 2, 18, 9, 0),
  end: new Date(2020, 2, 20, 13, 0),
  title: 'My Second Event'
}];

$('#eventcalendar').mobiscroll().eventcalendar({
  data: events;
});

var inst = $('#eventcalendar').mobiscroll('getInst');

// Add an event
inst.addEvent({
  id: guid++,
  start: new Date(2020, 2, 18, 9, 0),
  end: new Date(2020, 2, 20, 13, 0),
  title: 'My New Event
});

// Remove an event
inst.removeEvent(2);

// Update an event
var eventToUpdate = events[0];
eventToUpdate.title = 'Updated title';

inst.updateEvent(eventToUpdate);

In case you would like to edit a recurring event, you can use the updateRecurringEvent helper function.

Name Description
updateRecurringEvent

Parameters

  • originalRecurringEvent: Object - The original recurring event to update.
  • oldEventOccurrence: Object, null - The old event occurrence, if there's any.
  • newEvent: Object, null - The new event, if there's any.
  • updatedEvent: Object, null - The updated event, if there's any.
  • updateMode: String Specifies which part of the event to update. Possible values:
    • 'current' - This event occurrence only.
    • 'following' - This and following events.
    • 'all' - All event occurrences.
The function returns the updatedEvent and the newEvent.

See the Recurring event editor as an example.

Views

The event calendar supports three different views for three different jobs: the calendar view, schedule view and agenda view. These three can be combined and configured in a couple of different ways.

Calendar view

Use the event calendar as a traditional month view or combine it with an agenda as a week view. The events can be rendered as labels or in a pop-over that is shown on day click.

Desktop calendar view

Desktop calendar with labels and popover

Mobile calendar view

Mobile month view with agenda

Schedule view

The scheduler displays a time grid with its related events. It can be configured as a daily or weekly schedule. Work hours and work days along with disabled time-spans, breaks can be added. Use it to for advanced scheduling tasks with built-in drag & drop.

The displayed week days can be modified with the startDay and endDay properties of the schedule view option.

The displayed hours can be modified with the startTime and endTime properties of the schedule view option. With these properties both hours and minutes can be specified.

Example to display a work-week
view: {
  schedule: {
    type: 'week',
    startDay: 1, // Monday
    endDay: 5, // Friday
    startTime: '07:30',
    endTime: '18:30',
  }
}
Desktop schedule view

Desktop weekly schedule

Mobile schedule view

Mobile daily schedule

There might be cases when you would like to change the height of the schedule cell. You can use the following CSS classes for this purpose: 

.mbsc-schedule-time-wrapper,
.mbsc-schedule-item {
  height: 20px;
}

Timeline view

The timeline view displays a timeline with its related events. It can be configured as a daily or weekly timeline. Work hours and work days along with disabled time-spans, breaks can be added. Use it to for advanced scheduling tasks with built-in drag & drop.

The displayed week days can be modified with the startDay and endDay properties of the timeline view option.

The displayed hours can be modified with the startTime and endTime properties of the timeline view option. With these properties both hours and minutes can be specified.

Example to display a work-week
view: {
  timeline: {
    type: 'week',
    startDay: 1, // Monday
    endDay: 5, // Friday
    eventList: false,
    startTime: '07:30',
    endTime: '18:30'
  }
}
Desktop timeline view

Desktop monthly timeline

Mobile timeline view

Mobile daily timeline

By default timeline rows will have variable height and will expand to accommodate the displayed events. This can be controlled by the rowHeight property of the timeline view option. If it is set to 'equal', the rows will have equal heights, and overlapping events will be distributed evenly to fit in the row.

The eventList property transforms the event display into a daily listing mode. This view represents a daily summary rather than an hour-by-hour layout, similar to the event calendar where labels are printed under the appropriate day for the appropriate resource one after the other. The events have an exact height and the resource rows will expand automatically if more events are displayed than the minimum height.

Timeline event listing

Timeline event listing

Agenda view

The agenda calendar displays a list of events for a given period of time (year, month, week or day). It can be used as a stand-alon component or in combination with the calendar.

Desktop agenda view

Desktop agenda

Mobile agenda view

Mobile agenda

The three views can be used alone or combined with each-other. e.g. a week calendar combined with a daily agenda, listing the events for the selected day.

For the available configuration options see the view setting.

Daily agenda example

Weekly calendar view with daily agenda

Example
$('#eventcalendar').mobiscroll().eventcalendar({
  data: [/*...*/],
  view: {
    calendar: { type: 'week' },
    agenda: { type: 'day' }
  }
});

Setting the initial view

By default the initial view of the calendar displays the current date. Depending on the view type, this might be the current day, week, month or year. For views, where time is also displayed, the view will be scrolled to the current time as well.

To change the initial view to another date, the selectedDate option can be used.

Example
$('#eventcalendar').mobiscroll().eventcalendar({
  data: [/*...*/],
  selectedDate: new Date(2020, 2, 18)
});

For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day.

When multiple days, weeks, months or years are displayed, the position of the specified date on the view (first, second, third, etc. day/week/month/year) is determined by the refDate option.

You can navigate to another view programatically any time, using the navigate method.

This will navigate the calendar to the view containing the specified date. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day.

When multiple days, weeks, months or years are displayed, the position of the specified date on the view (first, second, third, etc. day/week/month/year) is determined by the refDate option.

Example
$('#eventcalendar').mobiscroll().eventcalendar({
  data: [/*...*/],
  selectedDate: new Date(2020, 2, 18)
});

var inst = $('#eventcalendar').mobiscroll('getInst);

inst.navigate(new Date(2020, 3, 19));

Events drag/resize/create

The calendar and schedule view events can be moved and resized with mouse/touch interactions. The dragToMove and dragToResize options enable the events drag and drop and resize functionality. With the dragTimeStep option the minimum amount of drag/resize step can be specified in minutes.

With the dragToCreate option enabled events can be created by dragging on the empty areas of the calendar and schedule view. On a desktop environment a new event can also be created with the clickToCreate option.

To customize the newly created event use the extendDefaultEvent option.

Event calendar move, resize and create

Event calendar move, resize and create

External drag & drop

Drag & drop events onto the calendar

There is a possibility to drag & drop any external element into your calendar.
In order to achieve this, first you need to grant permission to your calendar to accept this behavior. You can do that easily by setting the externalDrop option to true.
As a second step, you'll have to create your external draggable element and pass a skeleton event definition through the dragData option which will be added to the event calendar on drop. If omitted, a default event will be created.

You can initialize the draggable containers with two different methods. You either use manual or auto-initialization. In case you're working with dynamic values, it is recommended to use the manual initialization. Here's an example:

Manual initialization
<div id="mydiv">Drag me to the calendar</div>
var now = new Date();
$('#mydiv').mobiscroll().draggable({
    dragData: {
        title: 'My new event',
        // this event will be 3 hours long
        start: new Date(now.getFullYear(), now.getMonth(), 10, 12),
        end: new Date(now.getFullYear(), now.getMonth(), 10, 15),
        color: 'green'
    };
});

For the auto-init you only need to add the mbsc-draggable attribute to your container element and optionally pass a skeleton event definition through the data-drag-data attribute as a JSON string. If omitted, a default event will be created.

Auto-initialization
<div id="mydiv" mbsc-draggable data-drag-data='{"title": "My new event", "start": "2021-03-10T12:00", "end": "2021-03-10T15:00", "color": "green"}'>Drag me to the calendar</div>
Please note that when dragging the external element, we create a clone of it for a better illustration of the movement.
Event calendar external drag and drop

Event calendar external drag and drop

Drag & drop events outside of the calendar

The externalDrag option enables events to be dragged out from the calendar/schedule/timeline views and dropped onto another instance or any dropcontainer. When an event leaves the calendar element the onEventDragLeave life-cycle event will be fired and a clone of the event will be displayed for a better illustration of the movement. If the dragToMove option is not enabled the dragged event will instantly leave the calendar container and the onEventDragLeave event will fire and the event clone will be displayed. When an event enters the calendar view the onEventDragEnter life-cycle event will be fired.

Dropcontainer

The dropcontainer defines a container where events can be dragged out form the Eventcalendar/Timeline/Schedule views. The onItemDragLeave and onItemDragEnter life-cycle events can be used to track when an event exits or enters the dropcontainer. When an item is dropped inside the container the onItemDrop event is triggered. This can be useful for unscheduling work or appointments that were already scheduled.

Dropcontainer initialization and turning the dropped element into draggable
$('#external-drop-cont').mobiscroll().dropcontainer({
    onItemDrop: function (args) {
        if (args.data) {
            var event = args.data;
            var eventLength = Math.abs(new Date(event.end) - new Date(event.start)) / (60 * 60 * 1000);
            var elm = '<div id="md-event-' + event.id + '" class="external-drop-task" style="background: ' + event.color + ';">' +
                '<div>' + event.title + '</div>' +
                '<div>' + eventLength + ' hour' + (eventLength > 1 ? 's' : '') + '</div>' +
                '</div>';

            $('#md-task-cont').append(elm);
            $('#md-event-' + event.id).mobiscroll().draggable({
                dragData: event
            })
        }
    }
});

For usage examples check out the Schedule External drag and drop demo.

Dropcontainer life-cycle events:

Name Description
onItemDragEnter(event, inst) Triggered when an event is dragged into the dropcontainer. To enable external drag & drop use the externalDrag or the externalDrop options.

Parameters

  • event: Object - The event object has the following properties:
    • clone: HtmlElement - The clone of the dragging element. When dragging an external element we create a clone for a better illustration of the movement.
    • data: Object - The dragged calendar event data.
    • domEvent: Event - The DOM event of the dragged event.
  • inst: Object - The instance object of the eventcalendar.
onItemDragLeave(event, inst) Triggered when an event is dragged out from the dropcontainer. To enable external drag & drop use the externalDrag or the externalDrop options.

Parameters

  • event: Object - The event object has the following properties:
    • clone: HtmlElement - The clone of the dragging element. When dragging an external element we create a clone for a better illustration of the movement.
    • data: Object - The dragged calendar event data.
    • domEvent: Event - The DOM event of the dragged event.
  • inst: Object - The instance object of the eventcalendar.
onItemDrop(event, inst) Triggered when an event is dropped inside the dropcontainer. To enable external drag & drop use the externalDrag or the externalDrop options.

Parameters

  • event: Object - The event object has the following properties:
    • clone: HtmlElement - The clone of the dragging element. When dragging an external element we create a clone for a better illustration of the movement.
    • data: Object - The dragged calendar event data.
    • domEvent: Event - The DOM event of the dragged event.
  • inst: Object - The instance object of the eventcalendar.

Events connections

The timeline view can display connections between events. Events will be linked with lines and additionally arrows can be displayed to illustrate the direction of the connection. Events can have multiple connections simultaneously. Connections can be specified with the connections option.

Timeline event connections

Timeline event connections

For usage examples check out the timeline connections demo.

Resources

Resources grouped by date

Resources grouped by date

Resources grouped by resource

Resources grouped by resource

Resources grouped by resource

Resources grouped by day view

The scheduler view can display multiple resources inside a single instance. By default the displayed resources will be grouped by the given resources and the grouping can be changed with the groupBy option, which also supports date grouping.

Example to a resource and groupBy settings
  resources: [{
    id: 1,
    name: 'Ryan',
    color: '#f7c4b4'
  }, {
    id: 2,
    name: 'Kate',
    color: '#c6f1c9'
  }, {
    id: 3,
    name: 'John',
    color: '#e8d0ef'
  }],
  groupBy: 'date'

The color property controls the default event color of the resource. If an event doesn't have a specified color it will inherit from the resource. The agenda and calendar view events and labels will also inherit the resource color.

Events, colors, invalids can be tied to a single or multiple resources. This can be done with the resource property of the objects, where the id of the resource should be passed. It can be a single value and the element would be linked to a single resource or in case of an array the element will show up at the specified resources. If no resource property is specified to the color/event/invalid object then the element will show up in every resource group.

Example to color/invalid/event objects with resource property
  invalid: [{ 
    start: '13:00',
    end: '12:00',
    resource: 1, // this invalid will be displayed only in resource group where id is 1
    recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' },
    title: 'Lunch break'
  }],
  data: [{
    start: new Date(2021, 5, 23),
    end: new Date(2021, 5, 30),
    title: 'Conference',
    allDay: true,
    resource: [2, 3] // this event will be displayed in resource groups where id is 2 and 3
  }],
  colors: [{
    // this color will display at every resource group
    start: new Date(2021, 5, 12, 16),
    end: new Date(2021, 5, 12, 17),
    color: 'green'
  }]

Resource grouping & hierarchy

The timeline view supports resource hierarchy. Hierarchy groups can be defined with the children property of the resource object and child objects have the same properties as the main level resources. By default every resource group will be displayed and this can be modified with the collapsed attribute of the parent objects.
It supports multiple levels of hierarchy, child resources can have their own children. Both parent and child rows can contain events and those can be moved between any rows.
Child or parent rows can be disabled by creating an invalid rule which repeats daily and it is tied to the specific resources. Example: { recurring: { repeat: 'daily' }, resource: [/* resource id(s) */] }

In case of the schedule view child resources will display only on one level, each parent will be followed by their children.

Example to resource hierarchy and disabling resources
resources: [{
  color: '#f7c4b4',
  id: 1,
  name: 'Carl',
}, {
  color: '#c6f1c9',
  id: 2,
  collapsed: false,
  name: 'Sharon',
  children: [
    {
      color: 'red',
      id: 21,
      name: 'Child 1 of Sharon',
    },
    {
      color: 'blue',
      id: 22,
      name: 'Child 2 of Sharon',
      collapsed: true,
      children: [
        {
          color: 'ef0011',
          id: 210,
          name: 'Grandchild 1 of Sharon',
        },
        {
          color: 'ef0011',
          id: 220,
          name: 'Grandchild 2 of Sharon',
        },
      ]
    }
  ]
}]
Timeline view resource grouping & hierarchy

Timeline view resource grouping & hierarchy

Resource templating

To customize the display of the resources, the renderResource and, in case of the timeline, renderResourceHeader options can be used.

Besides the resource template, an additional sidebar can be rendered on the opposite end of the row through the renderSidebar option, and a header for it, using the renderSidebarHeader option.

A footer element can be rendered as well for each day through the renderDayFooter option. If this element is present, the renderResourceFooter and renderSidebarFooter can be defined as well.

See the Resource grid as an example.

Timeline resource, sidebar, footer templating

Timeline resource, sidebar, footer templating

In case of the timeline view the width of the resource column is fixed, but it can be overwritten from CSS if needed: 

.mbsc-timeline-resource-col {
  width: 200px;
}

/* For sticky event labels */
@supports (overflow:clip) {
    .mbsc-timeline.mbsc-ltr .mbsc-schedule-event-inner {
        left: 200px;
    }
    
    .mbsc-timeline.mbsc-rtl .mbsc-schedule-event-inner {
        right: 200px;
    }
}
Scheduler resource templating

Scheduler resource templating

Resource row height

There might be cases when you would like to change the height of the resource rows. There are three CSS classes which can be used for this purpose. For setting the resource row heights in general, you can use the .mbsc-timeline-row class. 

.mbsc-timeline-row {
  height: 80px;
}

If you only want to set the height of the parent resources, you can use the .mbsc-timeline-parent class. Note that there's minimum height of the rows which can only be decreased if the event creation is disabled on the relevant resource. You can prevent event creation by using the eventCreation property of the the resources option. 

.mbsc-timeline-parent {
  height: 30px;
}

You can also customize the remaining empty space below the events, by using the .mbsc-timeline-row-gutter class. 

.mbsc-timeline-row-gutter {
  height: 6px;
}

Slots

Besides the resources which are grouping data for the whole date range, slots introduce a horizontal level daily grouping in case of the timeline view. Slots can be used alongside resources.

When slots are used the timeline view will display in daily listing mode and only the dragToMove event iteraction will be available. The dragToCreate and dragToResize interactions will be truned off.

The renderSlot option can be used to customize the slot template of the timeline view.

Example to slots
  slots: [{
    id: 1,
    name: 'Morning shift',
  }, {
    id: 2,
    name: 'Afternoon shift',
  }]
Timeline slots

Timeline slots

Blocked out dates

You can show blocked out time ranges with the invalid option. By default the events and the blocked out dates will be displayed on the view even if there is collision.

The invalid option supports the following formats: JavaScript Date objects, 8601 strings , or moment object. These formats can be passed directly to the array in this case the whole day will be disabled or as an object where the blocked out ranges can be customized with the following properties: allDay/start/end/title/recurring.
Custom properties can also be passed to the invalid object which will also be passed to the life-cycle events and this can help with the identification/validation of the invalids.

If an event interacts with an invalid range the event will be reverted to it's original position and the onEventUpdateFailed event will be fired. (If the dragToMove or the dragToResize options were used.)

If a newly created event collide with a blocked out date the event won't be created and the onEventCreateFailed event will be fired. (If the dragToCreate option was used)

Example to an invalid array and it's properties
invalid: [
    /* Passing exact dates will block out the entire day */
     new Date(2021, 1, 7), // Date object
    '2021-10-15T12:00', // string
     moment("2020-12-25"), // moment object

    /* Block out date range passed as an object */
    { 
      // multi day range with date string
      start: '2021-10-15T12:00',
      end: '2021-10-18T13:00', 
      title: 'Company 10th anniversary',
      type: 'day-off' // custom property
    },
    { 
     // multi day range with date object
      allDay: true,
      start: new Date(2021, 2, 7, 10, 10),
      end: new Date(2021, 2, 9, 20, 20),
      title: 'Conference for the whole team',
      type: 'conference' // custom property
    },
    { 
      // multi day time range with recurring and time string
      start: '13:00',
      end: '12:00',
      recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' },
      title: 'Lunch break',
      type: 'lunch' // custom property
    }
];
Event calendar blocked out dates

Event calendar blocked out dates

Customizing the events

You can customize the events by writing custom rendering functions. Depending on what your goal is, you have two options:

Customize the full event

Whenever there is an event (in the agenda, scheduler, timeline, labels or popover) your custom rendering function will be used for instead the default render. Mobiscroll will position your component to the right place, but anything else you want to show is up to you... like a title, description, color the background or show any content.

Event calendar event customization

Event calendar event customization

Customize the event content

In most cases you only want to customize the content section of the event. In this case your render function will be used for rendering the content of the event. Mobiscroll will position the event to the right place and will render essential information like the color of the event, the time and if it's an all day event or not. The title, description and any other fields you want to show (like participants, an avatar...) will be coming from your custom function.

Customize the event content

Agenda content customization

Examples

Custom Event
$('#eventcalendar').mobiscroll().eventcalendar({
    data: [/*...*/],
    renderEvent: function (data) {
        return '' +
          '<div class="my-start">' + data.start + '</div>' +
          '<div class="my-end">' + data.end + '</div>' +
          '<div class="my-title">' + data.title + '</div>' +
          '<div class="my-custom-field">' + data.original.description + '</div>' +
          '<div class="my-custom-field">' + data.original.location + '</div>';
    }
});
Custom Event Content
$('#eventcalendar').mobiscroll().eventcalendar({
    data: [/*...*/],
    renderEventContent: function (data) {
        return '' +
          '<div class="my-title">' + data.title + '</div>' +
          '<div class="my-custom-field">' + data.original.description + '</div>' +
          '<div class="my-custom-field">' + data.original.location + '</div>';
    }
});

Taking over the listing

When the agenda view is displayed, you can take full control of the rendering, using the renderAgenda option. The renderer function will receive the event data as parameter, grouped by days.

If you'd like to keep the scroll to day functionality, when clicking a day on the calendar, make sure to add mbsc-timestamp attribute on the element containing the events for a day, with the timestamp of the day as value.

Example
$('#eventcalendar').mobiscroll().eventcalendar({
  data: [/*...*/],
  renderAgenda: function (data) {
    var html = '<div class="custom-event-list">';
    data.forEach(function (day) {
      html += '<ul class="custom-event-group" mbsc-timestamp="' + day.timestamp + '">' +
        '<li class="custom-event-day">' + day.date + '</li>';
      day.events.forEach(function (event) {
        html += '<li class="custom-event">' + event.title + '</li>';
      });
      html += '</ul>';
    });
    html += '</div>';
    return html;
  },
  view: {
    calendar: { type: 'week' },
    agenda: { type: 'day' }
  }
});
Agenda full event customization

Agenda full event customization

Customizing the header

The header of the calendar can be fully customized to one's needs. This can be achieved by passing a function that returns the custom header markup to the renderHeader option.

Fully custom header
$('#eventcalendar').mobiscroll().eventcalendar({
    data: [/*...*/],
    renderHeader: function () {
        return '<div class="my-custom-title">My <strong>Awesome</strong> Title</div>';
    }
});

While fully customizing the header is very usefull, sometimes it's desireable to customize only parts of it. In this case you can take advantage of the default header's building blocks. These components let you put toghether the header you want, while you don't have to worry about the functionality behind them.
For example you can leave out parts from the default header, change the order the default buttons appearance or add custom markup between them.

The built in header components can be initialized with their respective attributes as follows:

The above built in components can be used inside of the custom header. The following example will render the prev and next buttons and then a custom title that is set from a custom variable (myTitle variable).

Custom header with default buttons
var myTitle = 'My Awesome title';
$('#eventcalendar).mobiscroll().eventcalendar({
    renderHeader: function () {
        return `<button mbsc-calendar-prev></button>
                <button mbsc-calendar-next></button>
                <div className="my-custom-title">${myTitle}</div>`;
    }
});
Event calendar header customization

Event calendar header customization

Timezones

By default the Eventcalendar uses the local timezone of the browser to show event data. If you want to show the data or interpret it in a different timezone, you will need an external library to handle the timezone conversions. There are two libraries that Mobiscroll supports: moment-timezone and luxon.

When using a timezone plugin with the Eventcalendar, the exclusiveEndDates options defaults to true. Learn more about exclusive end dates here!

Library Install

To setup the library, first you have to install it on your page. In this guide we'll assume you are using npm to install packages, but you can consult the installation guide on the libraries official pages (moment-timezone install page, luxon install page) for more options on how to install them.

The Moment-Timezone library

To install the moment-timezone library with npm you will need to run the following commands:

$ npm install moment-timezone

After the library is installed, you will have to import it with the momentTimezone object from mobiscroll:

import moment from 'moment-timezone';
import { momentTimezone } from '@mobiscroll/jquery';

Then set the mobiscroll's reference to the imported library:

momentTimezone.moment = moment;

After that, you can pass the momentTimezone object to the Eventcalendar's timezonePlugin option.

The Luxon library

To install the luxon library with npm you will need to run the following commands:

$ npm install luxon

In case you are using typescript you can also consider installing the types, because they come separately:

$ npm install --save-dev @types/luxon

After the library is installed, you will have to import it with the luxonTimezone object from mobiscroll:

import * as luxon from 'luxon';
import { luxonTimezone } from '@mobiscroll/jquery';

Then set the mobiscroll's reference to the imported library:

luxonTimezone.luxon = luxon;

After that, you can pass the luxonTimezone object to the Eventcalendar's timezonePlugin option.

Using timezones

When working with timezones, you usually have your data stored in one timezone, and display it in a different timezone. A common scenario is storing the data in UTC, and displaying it in the user's local timezone. You can set this using the dataTimezone and displayTimezone options.

You can also store the timezone inside the event data, using the timezone property. If an event has the timezone specified, this will take precedence over the timezone set by dataTimezone. This is particularly useful for recurring events. Storing recurring events in UTC is not useful in most of the cases, since the occurrences will be generated in UTC time, which does not have daylight saving times. When converted to a displayTimezone which uses DST, the event times will be shifted with an hour when DST changes. Storing the timezone on the event makes it unambiguous, and will be correctly converted to displayTimezone.

Example
import moment from 'moment-timezone';
import { momentTimezone } from '@mobiscroll/jquery';

// setup the reference to moment
momentTimezone.moment = moment;
        
$('#my-selector').mobiscroll().eventcalendar({ 
    timezonePlugin: momentTimezone,
    dataTimezone: 'utc',
    displayTimezone: 'Europe/Berlin',
});

Global Variables

In case you are using global varibles instead of ES6 imports in your page, the timezone objects are accessible from the mobiscroll global variable:

Moment-Timezone
mobiscroll.momentTimezone.moment = moment;
$('#my-selector').mobiscroll().eventcalendar({ timezonePlugin: mobiscroll.momentTimezone});
Luxon
mobiscroll.luxonTimezone.luxon = luxon;
$('#my-selector').mobiscroll().eventcalendar({ timezonePlugin: mobiscroll.luxonTimezone});
Event calendar changing the timezones

Event calendar changing the timezones

Exclusive end dates

In version 5.7.0 we introduced support for exclusive end dates. This means that the last moment of a given range is not actually part of the range.

Many of existing calendaring solutions (e.g. Google Calendar) and standards (e.g. iCalendar) are working with exclusive end dates, so this makes interoperabiliy with our Eventcalendar UI simpler.

With the introduction of timezone support, this also became a necessity, e.g. if you have an event with start: '2021-07-09T20:00Z' and end: '2021-07-09T21:00Z', defined in UTC, when displayed in Europe/Bucharest timezone, the end becomes '2021-07-10T00:00+03:00'. With inclusive end dates the event will show up on 10th of July as well, which is unexpected.

The exclusive end dates mode can be enabled using the exclusiveEndDates option. When timezones are used (displayTimezone and/or dataTimezone is set), exclusive end dates are automatically enabled.

Enabling exclusive end dates can cause breaking changes, especially with all-day events with no time specified. With inclusive end dates an event with start: '2021-07-09' and end: '2021-07-10' will show as a two day event on the calendar view, expanded over 9th and 10th of July. With exclusive end dates the event will be a single day event, showing up only on 9th of July.

The Print Module is an optional module, that includes styles and functions for printing. It can be installed and used with other Mobiscroll Components as described below.

Installing the Print Module

When your Mobiscroll package is created with the Download Builder and you have access to the Print Module, you can choose to include it in the built package. In this case you will need make sure you checked the print module before downloading the package from the download page. After installing your downloaded package, the Print Module will be available for import. In case it was downloaded with the download builder, the Print Module needs to be imported from the generated package.

When you're using the full Mobiscroll package from NPM, then you have the possibility to install the Print Module as an additional package (also from NPM). In this case, after successfully using the Mobiscroll CLI to configure the project, you will have to install the @mobiscroll/print package from npm. Use the following command: 

$ npm install @mobiscroll/print

Importing the Print Module

The Print Module consists of print specific styles, that need to be loaded into the document. Also, there's a javascript part, that needs to be imported and passed to the component via the modules option.

Stylesheets

In the case of the package built by the download builder, there's no additional stylesheet. It is already bundled into the same file all the other component files are.

For the NPM package, styles can be found at the dist/css/ folder inside the package.

Import path for the styles from the npm print package
// importing the css
import '@mobiscroll/print/dist/css/mobiscroll.min.css';

// importing the SASS - if you are using SASS
import '@mobiscroll/print/dist/css/mobiscroll.scss';

JavaScript

The print module can be imported from the installed package and passed to the component using the modules option. Here's an example:

Pass the print module to the Eventcalendar
import { print } from '@mobiscroll/print';

$('#my-element').mobiscroll().eventcalendar({
    modules: [print],
});

Printing

Printing only the eventcalendar contents can be done, using the print method of the eventcalendar instance. Calling this method will create a new window containing only the eventcalendar and will invoke the print function of the browser. After the printing is done, the window should close automatically.

The new window created by the print method will include all the styles and links to stylesheets from the original page. These styles will be copied over automatically, but in case you are using relative urls, the base url of the new window might not match yours. In this case, the print method can be passed a config object, with your custom baseUrl, to make the relative paths work. By default, the baseUrl will be the original page's origin.

Please note that popup blockers might block the created window, so you need to disable the blocker for this method to work.
Printing the Eventcalendar
const inst = $('#my-element').mobiscroll().eventcalendar({
    modules: [print],
    data: myEvents,
}).mobiscroll('getInst');
            
$('#my-button').on('click', function() {
    inst.print();            
}

When you want to include more than just the eventcalendar in your print, you can invoke the print screen of your browser. You don't have to worry about the printing styles for the eventcalendar, they will be applied in this case as well.

Third Party Calendar Integration

The Calendar Integration is an optional plugin, that includes synchronization with your Google and Outlook calendar services. It can be installed and used with the Mobiscroll Event Calendar as described below.

Installing the Calendar Integration Plugin

When your Mobiscroll package is created with the Download Builder and you have access to the Calendar Integration, you can choose to include it in the built package. In this case you will need to make sure you checked the Calendar Integration before downloading the package from the download page. After installing your downloaded package, the Calendar Integration will be available for import.

When you're using the full Mobiscroll package from NPM, then you have the possibility to install the Calendar Integration as an additional package (also from NPM). In this case, after successfully using the Mobiscroll CLI to configure the project, you will have to install the @mobiscroll/calendar-integration package from npm. Use the following command: 

$ npm install @mobiscroll/calendar-integration

Public Google Calendar

Calling the init function will do the necessary initializations for the third party. After the init, you can list the events from the public calendar.

Example
var googleCalendarSync = mobiscroll.googleCalendarSync;

googleCalendarSync.init({
    apiKey: 'YOUR_API_KEY',
    onInit: function () {
        googleCalendarSync.getEvents(
            'PUBLIC_CALENDAR_ID',
            new Date(2022, 1, 1),
            new Date(2022, 3, 0)
        ).then(function(events){
            mobiscrollInstance.setEvents(events);
        });
    }
});

Private Google Calendars

Calling the init function will do the necessary initializations for the third party. For this step you need to use an API key and a client ID. After the init, you can sign in, list your calendars and events and create, update or delete the events on the calendars you have permission to.

Example
var googleCalendarSync = mobiscroll.googleCalendarSync;

googleCalendarSync.init({
    apiKey: 'YOUR_API_KEY',
    clientId: 'YOUR_CLIENT_ID',
    onInit: myInit,
    onSignedIn: mySignedIn,
    onSignedOut: mySignedOut,
});

function myInit() {
    googleCalendarSync.signIn();
}

function mySignedIn() {
    googleCalendarSync.getEvents(
        ['MY_FIRST_CALENDAR_ID', 'MY_SECOND_CALENDAR_ID'],
        new Date(2022, 1, 1),
        new Date(2022, 3, 0)
    ).then(function(events){
        mobiscrollInstance.setEvents(events);
    });
}

Click here to find more information about the Google Calendar Integration.

Outlook Calendar Integration

Calling the init function will do the necessary initializations for the third party. For this step you need to use a client ID. After the init, you can sign in, list your calendars and events and create, update or delete the events on the calendars you have permission to. More info about the Third Party Calendar Integration

Example
var outlookCalendarSync = mobiscroll.outlookCalendarSync;

outlookCalendarSync.init({
    clientId: 'YOUR_CLIENT_ID',
    onInit: myInit,
    onSignedIn: mySignedIn,
    onSignedOut: mySignedOut,
});

function myInit() {
    outlookCalendarSync.signIn();
}

function mySignedIn() {
    outlookCalendarSync.getEvents(
        ['MY_FIRST_CALENDAR_ID', 'MY_SECOND_CALENDAR_ID'],
        new Date(2022, 1, 1),
        new Date(2022, 3, 0)
    ).then(function(events){
        mobiscrollInstance.setEvents(events);
    });
}

Click here to find more information about the Outlook Calendar Integration.

For many more examples - simple and complex use-cases - check out the event calendar demos for jquery.

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
actionableEvents Boolean true Defines if the events on the agenda and inside the calendar popover are actionable or not. If actionable, the event items will have hover and active states, and pointer cursor. Set to false when custom event rendering is used and the event list items contain other actionable elements, e.g. buttons.
calendarSystem Object undefined Specify the calendar system to be used. Supported calendar systems:
  • Gregorian - This is the default calendar system, no setting needs to be passed.
  • Jalali - Default system of the Persian calendar. The Farsi language needs to be included to the package. 
    $('#mycalendar').mobiscroll().eventcalendar({
  calendarSystem: mobiscroll.jalaliCalendar
});
  • Hijri - Arabic language needs to be included to the package. 
    $('#mycalendar').mobiscroll().eventcalendar({
  calendarSystem: mobiscroll.hijriCalendar
});
clickToCreate Boolean, String undefined Enable new event creation on click. If true or 'double' a new event will be created only with a double click and with the 'single' value the event will be created instantly with a single click. This option will only work on desktop environment where mouse events are fired.
It will also allow deleting of the focused events using the Delete or Backspace key. In touch environment a long tap should be used to create a new event and it is controlled with the dragToCreate option.

Using the extendDefaultEvent option extra properties can be set for the created event.

The event deletion functionality can be overwritten using the eventDelete option.
colors Array undefined Change the color of certain dates on the calendar. Must be an array of objects with the following properties:
  • allDay Boolean - Specifies whether the date you want to color is all day or not.
  • date Date, String, Object - Date of the calendar day which should be colored.
  • start Date, String, Object - Start date/time of the calendar days/cells which should be colored.
  • end Date, String, Object - End date/time of the calendar days/cells which should be colored.
  • background: String - Background color of the cell, can be any valid CSS color ('red', '#ff0000', 'rgb(255,0,0)', etc.).
  • highlight: String - Highlight color of the day, can be any valid CSS color ('red', '#ff0000', 'rgb(255,0,0)', etc.).
  • recurring String, Object - Recurrence rule for coloring recurring days.
  • recurringException: String, Object, Array - Represents the exceptions of a recurring color. Useful when specific dates need to be skipped from the rule.
  • recurringExceptionRule: String, Object - Represents the exception rule of a recurring color. Useful when recurring dates need to be skipped from the rule.
  • cellCssClass: String - CSS class for the day cell. This property is only applicable in the case of the calendar view.
  • resource: String, Number, Array of String | Number - specify resource ids for the color. The color will display only in the specified resource group. If there is no resource id defined the color will be displayed at every resource group.
  • slot: String, Number - specify slot ids for the color. The color will display only in the specified slot group. If there is no slot id defined the color will be displayed at every slot group.
  • textColor: String - Specifies the color of the colored range title.
  • title: String - Text which will be displayed on the schedule/timeline view for the colored range.
  • cssClass String - Specifies the custom CSS class name of the color. Useful when customization is needed for the background of cells and time ranges. This property is only applicable in the case of the scheduler and timeline view.
The colored range will be considered all-day if:
  • allDay is explicitly set.
  • start/end is not specified, only the date.
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
The colors can be combined with the labels or marked options.
Example
colors: [
    { date: new Date(2020,2,23), background: 'pink' },
    { date: new Date(2020,2,24), background: 'green' },
    { background: '#ff0000', recurring: { repeat: 'weekly', weekDays: 'SU' } },
    { background: 'yellow', recurring: { repeat: 'weekly', weekDays: 'SA' } }
]
connections Array undefined

Define connections between events. On the ui events will be linked with lines and additionally arrows can be displayed to illustrate the direction of the connection. Events can have multiple connections simultaneously.

An array of connection object can be passed to this option.The connection object has the following properties:

  • arrow: String, Boolean - define and specify where to disaply arrows. The following string values are supported 'from' | 'to' | 'bidirectional''. If true arrow will display only at the end side of the connection.
  • color: String - define the color of the connection.
  • cssClass: String - add a specific css class to the connection for further customization.
  • from: String - the id of the event where the connection will begin.
  • to: String - the id of the event where the connection will end.
Example of a connection array

connections: [{
  arrow: 'to',
  color: 'red',
  cssClass: 'my-test-class',
  from: 2,
  to: 3,
},
{
  arrow: 'to',
  color: 'rgb(255,69,0)',
  from: 1,
  to: 6,
}]
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:
  • idString, Number - A unique id for the event. If not specifed, the event will get a generated id.
  • startDate, String, Object - Specifies the start of the event.
  • endDate, String, Object - Specifies the end of the event.
  • titleString - The title of the event.
  • colorString - The color of the event.
  • allDayBoolean - Specifies if the event is all day or not.
  • editable: Boolean - specify if an event is editable or not. Setting it to false disables drag & drop, resize and delete, and the event will have mbsc-readonly-event css class. With this class, the fixed events will be easily customizable, for example: add opacity or disable the cursor on the fixed events.
  • dragBetweenResources: boolean - specifies whether the event is movable across resources. It applies for scheduler and timeline views. Has precedence over the eventDragBetweenResources property of the resource and the dragBetweenResources option.
  • dragInTime: boolean - specifies whether the event is movable in time. Has precedence over the eventDragInTime property of the resource and the dragInTime option.
  • resize: boolean - specifies whether the event is resizable. Has precedence over the eventResize property of the resource and the dragToResize option.
  • resource: String, Number, Array - specify resource ids for the events. The event will display only in the specified resource group. If there is no resource id defined the event will be displayed at every resource group.
  • slot: String, Number - specify slot ids for the events. The event will display only in the specified slot group. If there is no slot id defined the event will be displayed at every slot group.
  • recurring: String, Object - Recurrence rule for the event.
  • recurringException: String, Object, Array - Represents the exceptions of a recurring event. Useful when specific dates need to be skipped from the rule.
  • recurringExceptionRule: String, Object - Represents the exception rule of a recurring event. Useful when recurring dates need to be skipped from the rule.
  • timezone: String - The timezone of the event. When specified, it takes precedence over dataTimezone. A timezone plugin must be also passed to the component.
  • tooltip: String - Specifies the tooltip text of the event.
  • cssClass String - Can be used to pass custom CSS classes on an event to event basis. Useful when customization is needed on the event level. For example: setting the width for specific events.
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 onEventClick event will receive the event object as argument, containing the custom properties as well.
Use the getEvents method to get the events between two dates.
Example
data: [{
          start: new Date(2021, 5, 23),
          end: new Date(2021, 5, 30),
          title: 'Conference',
          allDay: true,
          color: 'red'
        }, {
          title: 'Work project',
          recurring: {
            repeat: 'daily',
            until: '2021-04-01'
          },
          recurringException: ['2021-03-15', '2021-03-25'],
          recurringExceptionRule: {
            repeat: 'weekly',
            weekDays: 'SA,SU'
          }
        }]
dataTimezone String defaults to displayTimezone The timezone in which the data is interpreted. If the data contain timezone information (when the ISO string has a timezone offset ex. "2021-03-28T01:00:00Z" or "2021-03-28T03:00:00+03:00") then the data's timezone is used instead of the dataTimezone option.
When using timezones, the exclusiveEndDates option is also turned on by default.
When using anything other than the default, a timezone plugin must be also passed to the component.
Possible values are:
  • 'local' - Uses the systems local timezone
  • 'utc' - Displays data in UTC (Universal Coordinated Time)
  • Timezone name - The timezone name from the IANA time zone database ex. "America/New_York"
displayTimezone String 'local' The timezone in which the data is displayed.
When using anything other than the default ('local'), a timezone plugin must be also passed to the component.
Possible values are:
  • 'local' - Default. Uses the systems local timezone
  • 'utc' - Displays data in UTC (Universal Coordinated Time)
  • Timezone name - The timezone name from the IANA time zone database ex. "America/New_York"
dragBetweenResources Boolean undefined

If false, the events will not be movable across resources, only in time. To control movement in time, use the [dragToMove](#opt-dragToMove) option.

Consider that dragToMove has to be enabled.
dragInTime Boolean undefined

If false, the events will not be movable in time. In case of the scheduler and timeline views events events can still be moved between resources. To control movement between resources, use the dragBetweenResources option.

Consider that dragToMove has to be enabled.
dragTimeStep Number 15 Specify the steps in minutes for the schedule events during drag.
dragToCreate Boolean undefined If true, dragging on an empty cell will create a new event. It will also allow deleting of the focused events using the Delete or Backspace key. The title of the new event can be specified with the newEventText option.

Using the extendDefaultEvent option extra properties can be set for the created event.

The event deletion functionality can be overwritten using the eventDelete option.
dragToMove Boolean undefined If true, the events will be move-able.
dragToResize Boolean undefined If true, the events will be resize-able.
eventDelete Boolean undefined

Enables or disables event deletion. When true, the focused event will be deleted on pressing the Delete or Backspace keys on the keyboard.

By default the event deletion depends on the clickToCreate and dragToCreate options. If either of those are true, and no eventDelete option is set, then event deletion is also enabled, otherwise not.

eventOrder Function undefined Determines the ordering of the events within the same day. Can be a function that accepts two event objects as arguments and should return -1 or 1.

If not specified, the default order is:
  • all day events
  • rest of events, sorted by start time; events with identical start times, will be ordered alphabetically based on their title
exclusiveEndDates Boolean undefined If true, the Eventcalendar will work in exclusive end dates mode, meaning that the last moment of the range (event, invalid, colors, etc.) is not part of the range. E.g. end: '2021-07-03T00:00' means that the event ends on 2nd of July and will not be shown on 3rd of July.
extendDefaultEvent Function undefined

Use this option to set properties to the new event created with click or drag. This event creation is handled by the clickToCreate and dragToCreate options. It takes a function that should return the properties for the new event. The object passed to this function has the following properties:

  • start: Date - The date when the newly created event will start.
  • resource: String, Number, Array - The id of the resource where the event creation started.

Example
function newEventData() {
    return {
        color: 'green',
        title: 'My event',
    };
}
externalDrag Boolean undefined If true, external drag & drop is allowed and events can be dragged outside from the component view.
externalDrop Boolean undefined If true, external drag & drop is allowed.
groupBy String 'resource' Groups the given schedule resources based on the specified 'date' or 'resource'.
height Number, String undefined Sets the height of the component. 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.
invalid Array undefined An array containing the invalid values.

Can contain dates (Javascript Date objects, ISO 8601 strings, or moment objects), or objects with the following properties:

  • allDay: Boolean - If true the specified date will cover the whole day.
  • start: Date, String, Object - Start of the invalid range.
  • end: Date, String, Object - End of the invalid range.
  • recurring: String, Object - Recurrence rule for recurring invalid ranges.
  • recurringException: String, Object, Array - Represents the exceptions of a recurring invalid. Useful when specific dates need to be skipped from the rule.
  • recurringExceptionRule: String, Object - Represents the exception rule of a recurring invalid. Useful when recurring dates need to be skipped from the rule.
  • title: String - Text which will be displayed on the schedule view for the invalid range.
  • resource: String, Number, Array - specify resource ids for the invalid range. The invalid range will be displayed only for the specified resources. If there is no resource defined, the invalid range will be displayed for every resource.
  • slot: String, Number - specify slot ids for the invalid range. The invalid range will be displayed only for the specified slot. If there is no slot defined, the invalid range will be displayed for every slot.
  • cssClass String - Specifies the custom CSS class name of the invalid. Useful when customization is needed for specific invalids. This property is only applicable in the case of the scheduler and timeline view.
Use the getInvalids method to get the invalids between two dates.
Example
invalid: [
    // Passing exact dates and times
    new Date(2021, 1, 7), // Date object
    '2021-10-15T12:00', // ISO 8601 string
    moment("2020-12-25"), // moment object

    // Passing invalid ranges
    { 
      // ISO 8601 strings
      start: '2021-10-15T12:00',
      end: '2021-10-18T13:00', 
      title: 'Company 10th anniversary',
    },
    {
      // Date objects
      allDay: true,
      start: new Date(2021, 2, 7),
      end: new Date(2021, 2, 9),
      title: 'Conference for the whole team',
    },
    {
      // Time range with recurrence
      start: '13:00',
      end: '12:00',
      recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' },
      title: 'Lunch break',
    },
    {
      // Disable weekends
      recurring: {
          repeat: 'weekly',
          weekDays: 'SA,SU'
      }
    }
];
invalidateEvent String 'strict'

Configures how to validate events against invalid ranges on create/move/resize:

When set to 'strict', event cannot intersect with an invalid range at all.

When set to 'start-end', event start and end cannot be inside an invalid range.
labels Array undefined Specify labels for calendar days. A label object can have the following properties:
  • date Date, String, Object - Date of the calendar label.
  • start Date, String, Object - Start date of the calendar label.
  • end Date, String, Object - End date of the calendar label.
  • color String - The color of the label, can be any valid CSS color ('red', '#ff0000', 'rgb(255,0,0)', etc.).
  • text String - The text of the label.
  • recurring: String, Object - Recurrence rule for recurring labels.
  • recurringException: String, Object, Array - Represents the exceptions of a recurring label. Useful when specific dates need to be skipped from the rule.
  • recurringExceptionRule: String, Object - Represents the exception rule of a recurring label. Useful when recurring dates need to be skipped from the rule.
  • cellCssClass: String - CSS class for the day cell. This property is only applicable in the case of the calendar view.
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
The labels can be combined with the colors option.
Example
labels: [{
  start: new Date(2020, 2, 23),
  end: new Date(2020, 2, 24),
  text: 'Conference',
  color: 'red'
}, {
  text: 'Christmas',
  recurring: { repeat: 'yearly', month: 12, day: 24 }
}]
marked Array undefined Mark certain dates on the calendar. Must be an array containing dates (Javascript Date objects, ISO 8601 strings, or moment objects), or objects with the following properties:
  • date Date, String, Object - Date of the day to be marked.
  • start Date, String, Object - Start date of the days to be marked.
  • end Date, String, Object - End date of the days to be marked.
  • color String - The color of the mark, can be any valid CSS color ('red', '#ff0000', 'rgb(255,0,0)', etc.).
  • recurring: String, Object - Recurrence rule for recurring marked days.
  • recurringException: String, Object, Array - Represents the exceptions of a recurring marked rule. Useful when specific dates need to be skipped from the rule.
  • recurringExceptionRule: String, Object - Represents the exception rule of a recurring marked rule. Useful when recurring dates need to be skipped from the rule.
  • cellCssClass: String - CSS class for the day cell. This property is only applicable in the case of the calendar view.
  • markCssClass: String - CSS class for the mark.
The dates can be specified as Javascript Date objects, ISO 8601 strings, or moment objects.
The marked option can be combined with the colors option.
Example
marked: [
  new Date(2020, 2, 15),
  new Date(2020, 2, 22),
  {
    start: new Date(2020, 2, 23),
    end: new Date(2020, 2, 24),
    color: 'red'
  },
  {
    color: 'green',
    recurring: { repeat: 'yearly', month: 12, day: 24 }
  }
]
max Date, String, Object undefined Maximum date and time. The calendar cannot be navigated beyond the specified maximum date. If navigation is needed, but event creation should not be allowed after a specific date, use the invalid option with daily recurrence starting from the specific date. 
$('#mycalendar').mobiscroll().eventcalendar({
    max: new Date(2021, 11, 12)
});
min Date, String, Object undefined Minimum date and time. The calendar cannot be navigated beyond the specified minimum date. If navigation is needed, but event creation should not be allowed before a specific date, use the invalid option with daily recurrence until the specific date. 
$('#mycalendar').mobiscroll().eventcalendar({
    min: new Date(2021, 11, 12)
});
refDate Date, String, Object undefined Specifies the reference date for the view calculation, when multiple days, weeks, months or years are displayed.
If not specified, for the scheduler and timeline views will be today's date, for the calendar and agenda views will be 1970/01/01.

It denotes the reference point when calculating the pages going in the future and in the past. For example if the view type is day, the view size is 3, and the current date is 01/16/2024, the pages are calculated from this date, so the initial page will contain [01/16/2024, 01/16/2024, 01/17/2024], the next page [01/18/2024, 01/19/2024, 01/20/2024] and so on.

In case of day view, the reference point will be exactly the specified date. For week, month and year views the reference point will be the start of the week, month or year of the specified day.

Changing the reference date will not navigate the calendar to the specified date, it only recalculates the pages from the new reference date. To navigate the view to a specified date and time, use the navigate method.
renderAgenda Function undefined A render function to customize the agenda template. Should return the markup of an event list, to be used in the agenda listing. It receives the the following parameters:
  • events: Array - The events of the current view, grouped by day. A day object has the following properties:
    • date: String - The formatted date of the day.
    • events: Array - The list of events for the day. An event object has the following properties:
      • allDay: String - The localized all-day text in case of all day events.
      • end: String - The formatted end time, if the event is not all day.
      • id: String - The id of the event.
      • isMultiDay: Boolean - True if the event spans across multiple days.
      • lastDay: Boolean - True if it's rendered on the last day of a multiple event.
      • original: Object - The original event object.
      • start: String - The formatted start time, if the event is not all day.
      • title: String - The title of the event.
    • timestamp: Number - The timestamp of the day
  • options: Object - The current settings of the component.
renderAgendaEmpty Function undefined

Use this option to customize the empty state message that appears on the agenda. It should return the desired markup.

renderDay Function undefined

You can use the renderDay option to customize the day cells of the calendar view and the header date container in case of schedule and timeline view. It takes a function that should return the desired markup. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

If you are looking to customize only the content and don't want to bother with the styling of the event, in case of calendar and schedule view you can use the renderDayContent option.

The render function will receive an object as parameter. This data can be used to show day specific things on the Eventcalendar. The object passed to the function has the following properties:

  • date: Date object - The specific date as a Date object.
  • selected: Boolean - True if the date is selected. (In case of calendar view)
  • events: Array - The list of events of the day.
  • resource: String, Number - The id of the resource in case of scheduler(week and month views) when the events are grouped by resources.
  • isActive: Boolean - On the timeline view, this parameter will be true when rendering the current day/week/month/year.
Example
renderDay: function (day) {
    var date = day.date;
    var formatDate = mobiscroll.formatDate;

    return `<div>`+ formatDate('DDDD', date) +`</div>` +
    `<p>`+ formatDate('MMMM DD', date) +`</p>`;
}
renderDayContent Function undefined

You can use the renderDayContent option to customize the day content of the Eventcalendar. It takes a function that should return the desired markup. The Eventcalendar will take care of styling and you can focus on what you show beside the day number a.k.a the content.

If you are looking to fully customize the day (ex. add custom hover effects) you will need to use the renderDay option. In that case you will only get the positioning done by the Eventcalendar and everything else is up to you.

The render function will receive an object as parameter. This data can be used to show day specific things on the Eventcalendar. The object passed to the template has the following properties:

  • date: Date object - The specific date as a Date object.
  • selected: Boolean - True if the date is selected.
  • events: Array - The list of events of the day.
  • resource: String, Number - The id of the resource in case of week view scheduler when the events are grouped by resources.
Example
renderDay: function (day) {
    var date = day.date;
    var formatDate = mobiscroll.formatDate;

    return `<div>`+ formatDate('DDDD', date) +`</div>` +
    `<p>`+ formatDate('MMMM DD', date) +`</p>`;
}
renderDayFooter Function undefined

Use this option to render a custom footer for the timeline. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. This element only renders for the timeline view.

The template will receive an object as data. This data can be used to show day specific things on the day footer. The object passed to the template has the following properties:

  • date: Date object - The specific date as a Date object.
  • events: Array - The list of events of the day.
Example
function myCustomDayFooterTemplate() {
    return <div>Day footer</div>;
}
renderEvent Function undefined

You can use the renderEvent option to customize the events that appear on the agenda and the popover. It should return the markup of the event. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

If you are looking to customize only the content (ex. add custom elements) and don't want to bother with the styling of the event, you can use the renderEventContent option.

For customizing the events on other part of the Eventcalendar check out the customizing the events section

The render function will receive an event object as parameter. This data can be used to show event specific things on the agenda and popover. The object passed to the function has computed properties, as well as a reference to the original event it comes from:

  • allDay: String - The localized all-day text in case of all day events.
  • end: String - The formatted end time, if the event is not all day.
  • id: String - The id of the event.
  • isMultiDay: Boolean - True if the event spans across multiple days.
  • lastDay: Boolean - True if it's rendered on the last day of a multiple event.
  • original: Object - The original event object.
  • start: String - The formatted start time, if the event is not all day.
  • title: String - The title of the event.
renderEventContent Function undefined

You can use the renderEventContent option to customize the event content that appears on the agenda and the popover. It should return the markup that is added to the event. The Eventcalendar will take care of styling and you can focus on what you show inside of the event a.k.a the content.

If you are looking to fully customize the event (ex. add custom hover effects) you will need to use the renderEvent option. In that case you will only get the positioning done by the Eventcalendar and everything else is up to you.

For customizing the events on other part of the Eventcalendar check out the customizing the events section.

The render function will receive an event object as parameter. This data can be used to show event specific things on the agenda and popover. The object passed to the function has computed properties, as well as a reference to the original event it comes from:

  • allDay: String - The localized all-day text in case of all day events.
  • end: String - The formatted end time, if the event is not all day.
  • id: String - The id of the event.
  • isMultiDay: Boolean - True if the event spans across multiple days.
  • lastDay: Boolean - True if it's rendered on the last day of a multiple event.
  • original: Object - The original event object.
  • start: String - The formatted start time, if the event is not all day.
  • title: String - The title of the event.
renderHeader Function undefined

Use this option to customize the header of the Eventcalendar. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well as the built in header components of the calendar.

Check out the customizing the header section for a more detailed description on built in components.

Example with built in components
function myCustomHeader() {
    return `<button mbsc-calendar-prev></button>
            <button mbsc-calendar-next></button>
            <div mbsc-calendar-nav></div>`;
}
renderHour Function undefined

You can use the renderHour option to customize the header hour container in case of the timeline view. It takes a function that should return the desired markup. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

The render function will receive an object as parameter. This data can be used to show day specific things on the Eventcalendar. The object passed to the function has the following properties:

  • date: Date object - The specific date as a Date object.
  • events: Array - The list of events of the hour.
  • isActive: Boolean - On the timeline view, this parameter will be true when rendering the current hour.
Example
renderHour: function (day) {
    var date = day.date;
    var formatDate = mobiscroll.formatDate;

    return `<div>`+ formatDate('hh:mm', date) +`</div>`;
}
renderHourFooter Function undefined

You can use the renderHourFooter option to customize the footer hour container in case of the timeline view. It takes a function that should return the desired markup. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

The render function will receive an object as parameter. This data can be used to show day specific things on the Eventcalendar. The object passed to the function has the following properties:

  • date: Date object - The specific date as a Date object.
  • events: Array - The list of events of the hour.
Example
renderHourFooter: function (day) {
    var date = day.date;
    var formatDate = mobiscroll.formatDate;

    return `<div>`+ formatDate('hh:mm', date) +`</div>`;
}
renderLabel Function undefined

You can use the renderLabel option to fully customize the labels that appear on the calendar. It should return the markup of the event. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

If you are looking to customize only the content (ex. add custom elements) and don't want to bother with the styling of the label, you can use the renderLabelContent option.

For customizing the events on other part of the Eventcalendar check out the customizing the events section

The render function will receive an event object as parameter. This data can be used to show event specific things on the calendar. The object passed to the function has computed properties, as well as a reference to the original event it comes from:

  • end: String - Computed property. It holds the formatted end time, if the event is not all day.
  • id: String - It holds the id of the event. If there's no id on the event object, this property is generated.
  • isMultiDay: Boolean - Computed property. It's true if the event spans across multiple days.
  • original: Object - Reference to the original event object. Any custom property on the event can be access through this property.
  • start: String - Computed property. It holds the formatted start time, if the event is not all day.
renderLabelContent Function undefined

You can use the renderLabelContent option to customize the label contents, that appears on the calendar. It should return the markup that is added to the label. The Eventcalendar will take care of styling and you can focus on what you show inside of the label a.k.a the content.

If you are looking to fully customize the label (ex. add custom hover effects) you will need to use the renderLabel option. In that case you will only get the positioning done by the Eventcalendar and everything else is up to you.

For customizing the events on other part of the Eventcalendar check out the customizing the events section

The render function will receive an event object as parameter. This data can be used to show event specific things on the calendar. The object passed to the function has computed properties, as well as a reference to the original event it comes from:

  • end: String - Computed property. It holds the formatted end time, if the event is not all day.
  • id: String - It holds the id of the event. If there's no id on the event object, this property is generated.
  • isMultiDay: Boolean - Computed property. It's true if the event spans across multiple days.
  • original: Object - Reference to the original event object. Any custom property on the event can be access through this property.
  • start: String - Computed property. It holds the formatted start time, if the event is not all day.
renderMonth Function undefined

You can use the renderMonth option to customize the header month container in case of the timeline view. It takes a function that should return the desired markup. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

The render function will receive an object as parameter. This data can be used to show day specific things on the Eventcalendar. The object passed to the function has the following properties:

  • date: Date object - The specific date as a Date object.
  • events: Array - The list of events of the month.
  • isActive: Boolean - On the timeline view, this parameter will be true when rendering the current month.
Example
renderMonth: function (day) {
    var date = day.date;
    var formatDate = mobiscroll.formatDate;

    return `<div>`+ formatDate('MMMM DD', date) +`</div>`;
}
renderMonthFooter Function undefined

You can use the renderMonthFooter option to customize the footer month container in case of the timeline view. It takes a function that should return the desired markup. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

The render function will receive an object as parameter. This data can be used to show day specific things on the Eventcalendar. The object passed to the function has the following properties:

  • date: Date object - The specific date as a Date object.
  • events: Array - The list of events of the month.
Example
renderMonthFooter: function (day) {
    var date = day.date;
    var formatDate = mobiscroll.formatDate;

    return `<div>`+ formatDate('MMMM DD', date) +`</div>`;
}
renderResource Function undefined

Use this option to customize the resource template of the Scheduler. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well.

Example
function myCustomResourceTemplate(resource) {
    return `<div>`+ resource.name +`</div>` +
            `<p>`+ resource.description +`</p>` +
            `<img src="`+ resource.img +`"/>`;
}
renderResourceFooter Function undefined

Use this option to customize the empty cell content below the resource column. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. This element only renders for the timeline view, if the renderDayFooter option is present.

Example
function myCustomResourceFooterTemplate() {
    return <div>Resource footer</div>;
}
renderResourceHeader Function undefined

Use this option to customize the empty cell content above the resource column. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well.

Example
function myCustomResourceHeaderTemplate() {
    return <div>Resources</div>;
}
renderScheduleEvent Function undefined

You can use the renderScheduleEvent option to customize the events that appear on the scheduler and timeline. It should return the markup of the event. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

If you are looking to customize only the content (ex. add custom elements) and don't want to bother with the styling of the event, you can use the renderScheduleEventContent option.

For customizing the events on other part of the Eventcalendar check out the customizing the events section

The render function will receive an event object as parameter. This data can be used to show event specific things on the scheduler. The object passed to the function has computed properties, as well as a reference to the original event it comes from:

  • allDay: String - The localized all-day text in case of all day events.
  • end: String - The formatted end time, if the event is not all day.
  • id: String - The id of the event.
  • isMultiDay: Boolean - True if the event spans across multiple days.
  • lastDay: Boolean - True if it's rendered on the last day of a multiple event.
  • original: Object - The original event object.
  • start: String - The formatted start time, if the event is not all day.
  • title: String - The title of the event.
  • currentResource: String, Number - Represents the resource of the row or column where the event is being rendered.
renderScheduleEventContent Function undefined

You can use the renderScheduleEventContent option to customize the event content that appears on the scheduler and timeline. It should return the markup that is added to the event. The Eventcalendar will take care of styling and you can focus on what you show inside of the event a.k.a the content.

If you are looking to fully customize the event (ex. add custom hover effects) you will need to use the renderScheduleEvent option. In that case you will only get the positioning done by the Eventcalendar and everything else is up to you.

For customizing the events on other part of the Eventcalendar check out the customizing the events section

The render function will receive an event object as parameter. This data can be used to show event specific things on the scheduler. The object passed to the function has computed properties, as well as a reference to the original event it comes from:

  • allDay: String - The localized all-day text in case of all day events.
  • end: String - The formatted end time, if the event is not all day.
  • id: String - The id of the event.
  • isMultiDay: Boolean - True if the event spans across multiple days.
  • lastDay: Boolean - True if it's rendered on the last day of a multiple event.
  • original: Object - The original event object.
  • start: String - The formatted start time, if the event is not all day.
  • title: String - The title of the event.
  • currentResource: String, Number - Represents the resource of the row or column where the event is being rendered.
renderSidebar Function undefined

Use this option to render a custom sidebar on the right side of the timeline. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. This element only renders for the timeline view.

The template will receive the resource object as data. This data can be used to show resource specific things on the sidebar.

Example
function myCustomSidebarTemplate(resource: MbscResource) {
    return `<div>`+ resource.name +`</div>` +
            `<p>`+ resource.description +`</p>` +
            `<img src="`+ resource.img +`"/>`;
}
renderSidebarFooter Function undefined

Use this option to customize the empty cell content below the sidebar column. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. This element only renders for the timeline view, if the renderSidebar option is present.

Example
function myCustomSidebarFooterTemplate() {
    return <div>Sidebar footer</div>;
}
renderSidebarHeader Function undefined

Use this option to customize the empty cell content above the sidebar column. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. This element only renders for the timeline view, if the renderSidebar option is present.

Example
function myCustomSidebarHeaderTemplate() {
    return <div>Sidebar header</div>;
}
renderSlot Function undefined

Use this option to customize the slot template of the Timeline view. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well.
It will recieve an object as parameter and has the following properties:

  • date: Date object - The specific date where the slot is rendered.
  • slot: Object - Data of the rendered slot.
Example
function myCustomSlotTemplate(slotData) {
    return `<div>`+ slotData.slot.name +`</div>` +
            `<p>`+ slotData.slot.description +`</p>` +
            `<img src="`+ slotData.slot.img +`"/>`;
}
renderWeek Function undefined

You can use the renderWeek option to customize the header week container in case of the timeline view. It takes a function that should return the desired markup. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

The render function will receive an object as parameter. This data can be used to show day specific things on the Eventcalendar. The object passed to the function has the following properties:

  • date: Date object - The specific date as a Date object.
  • events: Array - The list of events of the week.
  • isActive: Boolean - On the timeline view, this parameter will be true when rendering the current week.
Example
renderWeek: function (day) {
    var date = day.date;
    var formatDate = mobiscroll.formatDate;

    return `<div>`+ formatDate('MMMM DD', date) +`</div>`;
}
renderWeekFooter Function undefined

You can use the renderWeekFooter option to customize the header week container in case of the timeline view. It takes a function that should return the desired markup. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

The render function will receive an object as parameter. This data can be used to show day specific things on the Eventcalendar. The object passed to the function has the following properties:

  • date: Date object - The specific date as a Date object.
  • events: Array - The list of events of the week.
    • ∂
Example
renderWeekFooter: function (day) {
    var date = day.date;
    var formatDate = mobiscroll.formatDate;

    return `<div>`+ formatDate('MMMM DD', date) +`</div>`;
}
renderYear Function undefined

You can use the renderYear option to customize the header year container in case of the timeline view. It takes a function that should return the desired markup. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

The render function will receive an object as parameter. This data can be used to show day specific things on the Eventcalendar. The object passed to the function has the following properties:

  • date: Date object - The specific date as a Date object.
  • events: Array - The list of events of the year.
  • isActive: Boolean - On the timeline view, this parameter will be true when rendering the current year.
Example
renderYear: function (day) {
    var date = day.date;
    var formatDate = mobiscroll.formatDate;

    return `<div>`+ formatDate('YYYY', date) +`</div>`;
}
renderYearFooter Function undefined

You can use the renderYearFooter option to customize the footer year container in case of the timeline view. It takes a function that should return the desired markup. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you.

The render function will receive an object as parameter. This data can be used to show day specific things on the Eventcalendar. The object passed to the function has the following properties:

  • date: Date object - The specific date as a Date object.
  • events: Array - The list of events of the year.
∂
Example
renderYearFooter: function (day) {
    var date = day.date;
    var formatDate = mobiscroll.formatDate;

    return `<div>`+ formatDate('YYYY', date) +`</div>`;
}
resources Array undefined

The scheduler can handle multiple resources inside a single instance. Resource grouping can be modified with the help of the groupBy option.

If set null or undefined, all events will be displayed, regardless of their resource property. If set to an empty array, only those events will be displayed which are not tied to any resource.

The timeline view can render multiple levels of hierachy groups. Levels can be added wiht the help of the children property.

The resource object has the following properties:

  • children: Array of object - Array of resoruce objects which will render as a child of the specified resource.
  • collapsed: Boolean - Defines the displayed state of the child resoruce group.
  • id: Number, String - This is an id that can be referenced in the events/invalids/colors data.
  • name: String - The name of the resource that will be displayed at the top of the resource column.
  • color: String - The color controls the default event color of the resource. Event colors can be specific above this. If the color is omitted the events of the resource will inherit the default calendar color.
  • eventCreation: Boolean - Disables event creation on specific resources by setting it to false. It's true by default.
  • eventDragBetweenResources: boolean - Specifies whether the events in the specified resource are movable across resources. It applies for scheduler and timeline views. Has precedence over the dragBetweenResources option.
  • eventDragInTime: boolean - Specifies whether the events in the specified resource are movable in time. Has precedence over the dragInTime option.
  • eventResize: boolean - Specifies whether the events in the specified resource are resizable. Has precedence over the dragToResize option.
Example of a resource array
resources: [{
      id: 1,
      name: 'Flatiron Room',
      color: '#f7c4b4'
    }, {
      id: 2,
      name: 'The Capital City',
      color: '#c6f1c9'
    }, {
      id: 3,
      name: 'Heroes Square',
      color: '#e8d0ef'
    }]
responsive Object undefined Specify different settings for different container 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.
The available width is queried from the container element of the component and not the browsers viewport like in css media queries
There are five predefined breakpoints:
  • xsmall - min-width: 0px
  • small - min-width: 576px
  • medium - min-width: 768px
  • large - min-width: 992px
  • xlarge - min-width: 1200px
Custom breakpoints can be defined by passing an object containing the breakpoint property specifying the min-width in pixels. Example: 
responsive: {
    xsmall: {
        view: {
            calendar: {
                type: 'week'
            },
            agenda: {
                type: 'day'
            }
        }
    },
    custom: { // Custom breakpoint
        breakpoint: 600,
        view: {
            calendar: {
                labels: true
            }
        }
    }
}
selectedDate Date, String, Object undefined Specifies the selected date on the calendar. This can be changed programmatically and when changed the calendar will automatically navigate to the specified date.

For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day.

This does not change the reference date that defines the reference point of the navigation pages. To change the reference point for the navigation (e.g. start the paging from the newly selected date) use the refDate option.
selectedEvents Array undefined Specifies the selected events on the calendar.
selectMultipleEvents Boolean false When true, enables multiple selection on the calendar. The selected events can be set with the setSelectedEvents method and can be returned by the getSelectedEvents method.
showControls Boolean true Shows or hides the calendar header controls: the previous and next buttons, and the current view button together with the year and month picker.
showEventTooltip Boolean true If false, it will hide the native tooltip that shows up when hovering over the event.
slots Array undefined

The slots besides the resources introduce a horizontal(daily) level of data grouping to the Timeline view.

If set null or undefined, all events will be displayed, regardless of their slot property. If set to an empty array, only those events will be displayed which are not tied to any slot.

The slot object has the following properties:

  • id: Number, String - This is an id that can be referenced in the events/invalids/colors data.
  • name: String - The name of the slot that will be displayed at the top of the slot column.
Example of a resource array
slots: [{
  id: 1,
  name: 'Morning shift,
}, {
  id: 2,
  name: 'Afternoon shift',
}]
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 custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme.

Supplied themes:
  • 'ios' - iOS theme
  • 'material' - Material theme
  • 'windows' - Windows theme
It's possible to modify theme colors or create custom themes.
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:
  • 'light' - Use the light variant of the theme.
  • 'dark' - Use the dark variant of the theme.
  • 'auto' or undefined - Detect the preferred system theme on devices where this is supported.

To use the option 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'.

timezonePlugin Object undefined

Specifies the timezone plugin, which can handle the timezone conversions.

By default the Eventcalendar uses the local timezone of the browser to show event data. If you want to show the data or interpret it in a different timezone, you will need an external library to handle the timezone conversions. There are two supported libraries: moment-timezone and luxon.
Read our guide on how to set up timezones in your app.

You can specify either the dataTimezone or the displayTimezone or both.

Depending on which externa library you use you can pass either the

  • momentTimezone
  • luxonTimezone
objects to the timezonePlugin option. These objects can be accessed under the mobiscroll namespace: 
var plugin = mobiscroll.momentTimezone;
var plugin2 = mobiscroll.luxonTimezone;
Example
$('#my-selector').mobiscroll().eventcalendar({
    timezonePlugin: mobiscroll.momentTimezone,
    dataTimezone: 'utc',
    displayTimezone: 'America/New_York',
});
view Object { calendar: { type: 'month', popover: true } } Configures the event calendar view elements.

Properties

  • calendar: Object - Configures the calendar view. If omitted, no calendar will be displayed.
    Properties:
    • type: String (default 'month') - Sets the calendar type. Possible values: 'year', 'month', 'week'.
    • size: Number - Specifies the number of displayed weeks/months.
    • count: Boolean (default false) - If true, it will display the number of events on days with events.
    • outerDays: Boolean (default false) - Show or hide days from previous and next months. Hiding only works for type: 'month'.
    • labels: Boolean, String, Number (default false) - Enable displaying events as labels on calendar days. Supported values:
      • boolean - If is set to true events will be displayed in the available space. If there are more events for a day, than the available space, a label with "x more" text will be displayed, which opens the popover showing all the events for the given day. In this mode to display multiple events on a day, set the calendar height to an appropriate value, using the height setting.
      • 'all' - In this mode all the event labels will be displayed in the calendar cell and the row height will auto-expand based on the diplayed events. The row conatiner will became scrollable if the rows overflow the available height.
      • number - Specify how many events will be displayed before the "more" button in a calendar cell. The row height will auto expand until the labels count reaches the given number and after that the "x more" button will be displayed. In the case when only one event should go in the "more" popup, that event will be displayed in the place of the "x more" button.
    • popover: Boolean (default undefined) - Enable popover for event listing on days containing events. If not explicitly defined, the popover will not show up if event listing is used. If event labels are used, popover will only show up for days where all labels do not fit on the calendar, and a "more" label is present.
    • popoverClass: String (default undefined) - A CSS class that's added to the popover element. Can be used to customize the styling of the popover on a calendar basis.
    • scroll: String (default 'horizontal') - Specifies the direction of the calendar scroll. Can be 'horizontal' or 'vertical'.
    • weekNumbers: Boolean (default false) - Show or hide week numbers.
  • agenda: Object - Configures the event list. If omitted, no event list will be displayed.
    Properties:
    • type: String (default undefined) - Sets the list type. Possible values: 'year', 'month', 'week', 'day'.
      If calendar is also displayed, only month, week and day values are supported.
      In case of month and week, the type and size should match the calendar type and size.
      In case of day type events on the selected calendar day will be displayed, so size will always be 1.
    • size: Number (default 1) - Specifies the number of years, months, weeks or days included in the list (depending on the specified type).
    • scrollable: Boolean (default false) - Setting this to true makes the event listing independently scrollable. There are two prerequisites for making this work:

      1 - The calendar needs to be to placed inside a container which has a height. This can be either a fixed height, a height in percentage, or a flex height. When the calendar is placed directly in a container with a fixed height, it will work out of the box.
      If the height of the container is specified in percentage, e.g. you'd like to fill the full page height, you need to make sure that all parent elements also have height: 100% specified, up until the body and html elements, or until the closest parent which has a fixed height.
      If the container is inside a parent with flex layout, it will also work out of the box.

      2 - The event list has a minimum calculated height of 200px - the result of the container height minus the height of the calendar header minus the height of the displayed calendar rows. If the calculated height is less then 200px, the event list will not be scrollable.
  • schedule: Object - Configures the schedule view. If omitted, no schedule will be displayed.
    Properties:
    • type: String (default 'week') - Sets the schedule type. Possible values: 'day', 'week' ,'month' .
    • size: Number - Specifies the number of displayed days/weeks.
    • allDay: Boolean (default true) - Show or hide the all day events.
    • currentTimeIndicator: Boolean (default true when the resolution is less than a day) - Show or hide the current time indicator
    • days: Boolean (default true) - Show or hide week days above the schedule grid.
    • startDay: Number (default 0) - Set the first visible weekday of the view. Sunday is 0, Monday is 1, etc. Days outside of the startDay and endDay range will not be visible. Should not be mistaken for the firstDay option, which sets the first day of the week, and, if not set, is defined by the localization.
    • endDay: Number (default 6) - Set the last visible weekday of the view. Sunday is 0, Monday is 1, etc.
    • startTime: String (default 00:00) - Set the start time of schedule column. Hours and minutes can be specified in the string, example: '09:30'.
    • endTime: String (default 24:00) - Set the end time of schedule column. Hours and minutes can be specified in the same string, example: '18:30'.
    • timeCellStep: Number (default 60) - Set the step of the grid cells in minutes. Supported values: 1, 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440.
    • timeLabelStep: Number (default 60) - Set the step of the time labels in minutes. Supported values: 1, 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440.
    • timezones: Array - Use this to display times in multiple timezones on the time scale and time indicator. The timezones array can contain timezone strings or objects with timezone and label properties. Timezone strings must use the name from the IANA time zone database. If no label is provided, the time column label will be UTC +/- the timezone offset. 
      timezones: [
    'Europe/Berlin',
    'Europe/Bucharest'
]

      timezones: [{
    timezone: 'America/Chicago',
    label: 'CHI'
}, {
    timezone: 'America/New_York',
    label: 'NY'
}]
  • timeline: Object - Configures the timeline view. If omitted, no timeline will be displayed.
    Properties:
    • type: String (default 'week') - Sets the timeline type. Possible values: 'day', 'week' , 'month', 'year'.
    • resolutionHorizontal: String (default 'hour') - Sets the resolution of the timeline column. Possible values: 'hour', 'day', 'week', 'month', 'year'. In case of hourly resolution, the columns can be split to minutes (1, 5, 15, 20, 30) or merge to multiple hours (2, 3, 4, 6, 8, 12) using the timeCellStep and timeLabelStep properties.
    • resolutionVertical: String (default 'none') - Sets the vertical time unit of a timeline rows Possible values: 'day', 'none'. If set to 'day', the days will be rendered on the vertical axis, while the hours of the day will be displayed on the horizontal axis.
    • size: Number - Specifies the number of displayed days/weeks/months.
    • currentTimeIndicator: Boolean (default true when the resolution is less than a day) - Show or hide the current time indicator
    • eventList: Boolean (default false) - If true, transforms the hour-by-hour layout into a daily summary view. The events are listed under the appropriate day one after the other.
    • startDay: Number (default 0) - Set the first visible weekday of the view. Sunday is 0, Monday is 1, etc. Days outside of the startDay and endDay range will not be visible. Should not be mistaken for the firstDay option, which sets the first day of the week, and, if not set, is defined by the localization.
    • endDay: Number (default 6) - Set the last visible weekday of the view. Sunday is 0, Monday is 1, etc.
    • rowHeight: String (default 'variable') - Controls the height of the timeline view rows. By default timeline rows will have 'variable' height and will expand to accommodate the displayed events. If it is set to 'equal', the rows will have equal heights.
    • startTime: String (default 00:00) - Set the start time of timeline days. Hours and minutes can be specified in the string, example: '09:30'.
    • endTime: String (default 24:00) - Set the end time of timeline days. Hours and minutes can be specified in the same string, example: '18:30'.
    • timeCellStep: Number (default 60) - Set the step of the grid cells in minutes. Supported values: 1, 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440.
    • timeLabelStep: Number (default 60) - Set the step of the time labels in minutes. Supported values: 1, 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440.
    • weekNumbers: Boolean (default false) - Show or hide week numbers.

Example

view: {
  calendar: {
    type: 'week',
    size: 2
  },
  agenda: {
    type: 'week',
    size: 2
  }
}
width Number, String undefined Sets the width of the popup container. This will take no effect in inline display mode.

Setting options dynamically

To change one or more options on the component after initialization, use the setOptions method. This will update the component without losing it's internal state. 

$('#elm').mobiscroll().eventcalendar({
  theme: 'ios'
});
// Changes the theme to Material
$('#elm').mobiscroll('setOptions', { theme: 'material' });

Events

Name Description
onCellClick(event, inst) Triggered when a cell is clicked on the calendar scheduler, or timeline grid .

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the clicked cell.
    • domEvent: Event The DOM event of the click.
    • events: Array - The events for the clicked date.
    • resource: String, Number - The id of the resource where the cell was clicked, if resources are set.
    • selected: Boolean - Specifies if the day is currently selected or not (before it was clicked).
    • source: String - The view where the cell was clicked, 'calendar', 'schedule' or 'timeline'.
    • target: HTMLElement - The DOM element of the clicked cell.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onCellClick: function (event, inst) {
    }
});
onCellDoubleClick(event, inst) Triggered when a cell is double-clicked on the calendar scheduler, or timeline grid . This event will only trigger on desktop environment where mouse events are fired.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the clicked cell.
    • domEvent: Event The DOM event of the click.
    • events: Array - The events for the clicked date.
    • resource: String, Number - The id of the resource where the cell was clicked, if resources are set.
    • selected: Boolean - Specifies if the day is currently selected or not (before it was clicked).
    • source: String - The view where the cell was clicked, 'calendar', 'schedule' or 'timeline'.
    • target: HTMLElement - The DOM element of the clicked cell.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onCellDoubleClick: function (event, inst) {
    }
});
onCellHoverIn(event, inst) Triggered when the mouse pointer hovers a day on the calendar. (does not apply for agenda, schedule and timeline views).

Parameters

  • event: Object - The event object has the following properties:
    • date: The selected date as a Date object.
    • events: The events for the hovered day.
    • labels: If the day has labels, contains the label objects for the hovered day.
    • marked: If the day is marked, contains the marked objects for the hovered day.
    • selected: Specifies if the day is currently selected or not.
    • target: The table cell HTML DOM element.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onCellHoverIn: function (event, inst) {
    }
});
onCellHoverOut(event, inst) Triggered when the mouse pointer leaves a day on the calendar. (does not apply for agenda, schedule and timeline views).

Parameters

  • event: Object - The event object has the following properties:
    • date: The selected date as a Date object.
    • events: The events for the hovered day.
    • labels: If the day has labels, contains the label objects for the hovered day.
    • marked: If the day is marked, contains the marked objects for the hovered day.
    • selected: Specifies if the day is currently selected or not.
    • target: The table cell HTML DOM element.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onCellHoverOut: function (event, inst) {
    }
});
onCellRightClick(event, inst) Triggered when a cell is right-clicked on the calendar scheduler, or timeline grid .

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the clicked cell.
    • domEvent: Event The DOM event of the click.
    • events: Array - The events for the clicked date.
    • resource: String, Number - The id of the resource where the cell was clicked, if resources are set.
    • selected: Boolean - Specifies if the day is currently selected or not (before it was clicked).
    • source: String - The view where the cell was clicked, 'calendar', 'schedule' or 'timeline'.
    • target: HTMLElement - The DOM element of the clicked cell.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onCellRightClick: 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').mobiscroll().eventcalendar({
    onDestroy: function (event, inst) {
    }
});
onEventClick(event, inst) Triggered when an event is clicked.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the day on which the event was clicked.
    • domEvent: Event - The DOM event of the click.
    • event: Object - The clicked calendar event.
    • resource: String, Number - The id of the resource where the event was clicked, if resources are set.
    • source: String - The view where the event was clicked, 'agenda', 'calendar', 'schedule', 'timeline' or 'popover'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventClick: function (event, inst) {
    }
});
onEventCreate(event, inst) Triggered when an event is about to create. Event creation can be prevented by returning false from the handler function.

Parameters

  • event: Object - The event object has the following properties:
    • action: String - The action which created the event ('click', 'drag' or 'externalDrop').
    • domEvent: Event - The DOM event from the end of the gesture (mouseup or touchend).
    • event: Object - The newly created event object.
    • originEvent: Object - The occurrence of the event which was dragged. Will be set only if the event was created by dragging a recurring event occurrence.
    • source: String - The view where the event is being created, 'calendar', 'timeline' or 'schedule'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventCreate: function (event, inst) {
    }
});
onEventCreated(event, inst) Triggered when an event is created is rendered in its position.

Parameters

  • event: Object - The event object has the following properties:
    • action: String - The action which created the event ('click', 'drag' or 'externalDrop').
    • event: Object - The newly created event object.
    • source: String - The view where the event was created, 'calendar', 'timeline' or 'schedule'.
    • target: HTMLElement - The DOM element of the created event.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventCreated: function (event, inst) {
    }
});
onEventCreateFailed(event, inst) Triggered when an event is interacted with a blocked out date during the creation.

Parameters

  • event: Object - The event object has the following properties:
    • action: String - The action which created the event ('click', 'drag' or 'externalDrop').
    • event: Object - The newly created event object.
    • invalid: Object - The invalid object which the event interacted with.
    • originEvent: Object - The occurrence of the event which was dragged. Will be set only if the event was created by dragging a recurring event occurrence.
    • source: String - The view where the event was created, 'calendar', 'timeline' or 'schedule'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventCreateFailed: function (event, inst) {
    }
});
onEventDelete(event, inst) Triggered when an event is about to be deleted. Event deletion can be performed with delete and backspace button on an active event. Deletion can be prevented by returning false from the handler function.

Parameters

  • event: Object - The event object has the following properties:
    • domEvent: Event - The DOM event from the onKeyDown action.
    • event: Object - The deleted event's data object.
    • events: Array - The selected events in case of multiple select.
    • source: String - The view where the event is being deleted, 'calendar', 'timeline' or 'schedule'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventDelete: function (event, inst) {
    }
});
onEventDeleted(event, inst) Triggered when an event is deleted and it is removed from it's position.

Parameters

  • event: Object - The event object has the following properties:
    • event: Object - The deleted event's data object.
    • events: Array - The selected events in case of multiple select.
    • source: String - The view where the event was deleted, 'calendar', 'timeline' or 'schedule'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventDeleted: function (event, inst) {
    }
});
onEventDoubleClick(event, inst) Triggered when an event is double-clicked. This event will only trigger on desktop environment where mouse events are fired.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the day on which the event was clicked.
    • domEvent: Event - The DOM event of the click.
    • event: Object - The clicked calendar event.
    • resource: String, Number - The id of the resource where the event was clicked, if resources are set.
    • source: String - The view where the event was clicked, 'agenda', 'calendar', 'schedule', 'timeline' or 'popover'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventDoubleClick: function (event, inst) {
    }
});
onEventDragEnd(event, inst) Triggered when an event drag has ended.

Parameters

  • event: Object - The event object has the following properties:
    • domEvent: Event - The DOM event of the dragged event.
    • event: Object - The dragged calendar event.
    • resource: String, Number - The id of the resource where the event is dragged, if resources are set.
    • slot: String, Number - The id of the slot where the event is dragged, if slots are set.
    • source: String - The view where the event is dragged, 'calendar', 'schedule' or 'timeline'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventDragEnd: function (event, inst) {
    }
});
onEventDragEnter(event, inst) Triggered when an event is dragged onto the componenet from the outside. To enable external drag & drop use the externalDrag or the externalDrop options.

Parameters

  • event: Object - The event object has the following properties:
    • domEvent: Event - The DOM event of the dragged event.
    • event: Object - The dragged calendar event.
    • source: String - The view where the event is dragged, 'calendar', 'schedule' or 'timeline'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventDragEnter: function (event, inst) {
    }
});
onEventDragLeave(event, inst) Triggered when an event is dragged outside from the componenet. To enable external drag & drop use the externalDrag or the externalDrop options.

Parameters

  • event: Object - The event object has the following properties:
    • domEvent: Event - The DOM event of the dragged event.
    • event: Object - The dragged calendar event.
    • source: String - The view where the event is dragged, 'calendar', 'schedule' or 'timeline'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventDragLeave: function (event, inst) {
    }
});
onEventDragStart(event, inst) Triggered when an event drag has started.

Parameters

  • event: Object - The event object has the following properties:
    • action: String - The user action which triggered the event: 'create', 'resize' or 'move'.
    • domEvent: Event - The DOM event of the dragged event.
    • event: Object - The dragged calendar event.
    • resource: String, Number - The id of the resource where the event is dragged, if resources are set.
    • slot: String, Number - The id of the slot where the event is dragged, if slots are set.
    • source: String - The view where the event is dragged, 'calendar', 'schedule' or 'timeline'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventDragStart: function (event, inst) {
    }
});
onEventHoverIn(event, inst) Triggered when the mouse pointer hovers an event on the calendar.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the day on which the event was hovered.
    • domEvent: Event - The DOM event of the hover.
    • event: Object - The hovered calendar event.
    • resource: String, Number - The id of the resource where the event was hovered, if resources are set.
    • source: String - The view where the event was hovered, 'agenda', 'calendar', 'schedule', 'timeline' or 'popover'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventHoverIn: function (event, inst) {
    }
});
onEventHoverOut(event, inst) Triggered when the mouse pointer leaves an event on the calendar.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the day on which the event was hovered.
    • domEvent: Event - The DOM event of the hover.
    • event: Object - The hovered calendar event.
    • resource: String, Number - The id of the resource where the event was hovered, if resources are set.
    • source: String - The view where the event was hovered, 'agenda', 'calendar', 'schedule', 'timeline' or 'popover'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventHoverOut: function (event, inst) {
    }
});
onEventRightClick(event, inst) Triggered when an event is right-clicked.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the day on which the event was clicked.
    • domEvent: Event - The DOM event of the right click.
    • event: Object - The clicked calendar event.
    • resource: String, Number - The id of the resource where the event was clicked, if resources are set.
    • source: String - The view where the event was clicked, 'agenda', 'calendar', 'schedule', 'timeline' or 'popover'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventRightClick: function (event, inst) {
    }
});
onEventUpdate(event, inst) Triggered when an event is about to update. Update can be prevented by returning false from the handler function.

Parameters

  • event: Object - The event object has the following properties:
    • domEvent: Event - The DOM event from the end of the gesture (mouseup or touchend).
    • newEvent: Object - The newly created event object. Will be set only if the dragged event was a recurring event occurrence.
    • event: Object - The updated event object.
    • events: Object - The updated events. This property is present on recurring event delete, when selectMultipleEvents is set to true.
    • oldEvents: Object - The original events before the update. This property is present on recurring event delete, when selectMultipleEvents is set to true..
    • oldEvent: Object - The original event object before the update.
    • oldEventOccurrence: Object - The occurrence of the event which was dragged. Will be set only if the dragged event was a recurring event occurrence.
    • source: String - The view where the event is being updated, 'calendar', 'timeline' or 'schedule'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventUpdate: function (event, inst) {
    }
});
onEventUpdated(event, inst) Triggered when an event is updated and is rendered in its new position. This is where you update the event in your database or persistent storage.

Parameters

  • event: Object - The event object has the following properties:
    • event: Object - The updated event object.
    • events: Object - The updated events. This property is present on recurring event delete, when selectMultipleEvents is set to true.
    • oldEvents: Object - The original events before the update. This property is present on recurring event delete, when selectMultipleEvents is set to true..
    • oldEvent: Object - The original event object before the update.
    • source: String - The view where the event was updated, 'calendar', 'timeline' or 'schedule'.
    • target: HTMLElement - The DOM element of the created event.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventUpdated: function (event, inst) {
    }
});
onEventUpdateFailed(event, inst) Triggered when an event is interacted with a blocked out date at drop or resize.

Parameters

  • event: Object - The event object has the following properties:
    • event: Object - The updated event object.
    • newEvent: Object - The newly created event object. Will be set only if the dragged event was a recurring event occurrence.
    • oldEvent: Object - The original event object before the update.
    • oldEventOccurrence: Object - The occurrence of the event which was dragged. Will be set only if the dragged event was a recurring event occurrence.
    • invalid: Object - The invalid object which the event interacted with.
    • source: String - The view where the event was updated, 'calendar', 'timeline' or 'schedule'.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onEventUpdateFailed: 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').mobiscroll().eventcalendar({
    onInit: function (event, inst) {
    }
});
onLabelClick(event, inst) Triggered when a label on the calendar is clicked.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The date of the day on which the label was clicked.
    • domEvent: Event - The DOM event of the click.
    • label: Object - The original object of the label which was clicked, undefined in case of the "more" label.
    • labels: Array - An array containing each label object for the given day.
    • target: HTMLElement - The DOM element of the label.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onLabelClick: function (event, inst) {
    }
});
onPageChange(event, inst) Triggered when the calendar page is changed (month or week, with buttons or swipe).

Parameters

  • event: Object - The event object has the following property:
    • firstDay: Date - The first day of the displayed page.
    • lastDay: Date - The last day of the displayed page.
    • month: Date - The first day of the visible month in case of month view.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onPageChange: function (event, inst) {
    }
});
onPageLoaded(event, inst) Triggered when the calendar page is changed (month or week, with buttons or swipe) and the animation has finished.

Parameters

  • event: Object - The event object has the following property:
    • firstDay: Date - The first day of the displayed page.
    • lastDay: Date - The last day of the displayed page.
    • month: Date - The first day of the visible month in case of month view.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onPageLoaded: function (event, inst) {
    }
});
onPageLoading(event, inst) Triggered before the markup of a calendar page (month or week) is starting to render.

Parameters

  • event: Object - The event object has the following property:
    • firstDay: Date - The first day of the displayed page.
    • lastDay: Date - The last day of the displayed page.
    • month: Date - The first day of the visible month in case of month view.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onPageLoading: function (event, inst) {
    }
});
onResourceCollapse(event, inst) Triggered when a parent resource is collapsed on the timeline.

Parameters

  • event: Object - The event object has the following properties:
    • domEvent: Event - The DOM event of the click.
    • resource: String, Number - The id of the collapsed resource.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onResourceCollapse: function (event, inst) {
    }
});
onResourceExpand(event, inst) Triggered when a parent resource is expanded on the timeline.

Parameters

  • event: Object - The event object has the following properties:
    • domEvent: Event - The DOM event of the click.
    • resource: String, Number - The id of the expanded resource.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onResourceExpand: function (event, inst) {
    }
});
onSelectedDateChange(event, inst) Triggered when the selected date is changed, e.g. by clicking on a day on a calendar view, or by using the navigation arrows.

Parameters

  • event: Object - The event object has the following properties:
    • date: Date - The selected date.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onSelectedDateChange: function (event, inst) {
    }
});
onSelectedEventsChange(event, inst) Triggered when an event is selected or deselected, or when everything is deselected, when selectMultipleEvents is set to true.

Parameters

  • args: Object - The args object has the following properties:
    • events: Array - The selected events.
  • inst: Object - The instance object of the eventcalendar.

Example

$('#mobiscroll').mobiscroll().eventcalendar({
    onSelectedEventsChange: 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 
// With selector
$('#mobiscroll').mobiscroll('addEvent', {
    start: new Date(2016, 1, 1),
    end: new Date(2016, 1, 2),
    title: 'Conference',
    color: 'red'
});

// With instance
mobiscrollInstance.addEvent({
    start: new Date(2016, 1, 1),
    end: new Date(2016, 1, 2),
    title: 'Conference',
    color: 'red'
});
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 
// With selector
$('#mobiscroll').mobiscroll('destroy');

// With instance
mobiscrollInstance.destroy();
getEvents([startDate, endDate]) Returns the event data between two dates. If startDate and endDate are not specified, it defaults to the start and end days of the current view. If endDate is not specified, it defaults to startDate + 1 day.

Parameters

  • startDate (Optional): Date - Start date of the specified interval.
  • endDate (Optional): Date - End date of the specified interval.

Returns: Array

  • An array containing the event objects.

Example

Methods can be called on an instance. For more details see calling methods 
// With selector
$('#mobiscroll').mobiscroll('getEvents');

// With instance
mobiscrollInstance.getEvents();
getInst() Returns the object instance.

Returns: Object

  • The object instance.

Example

Methods can be called on an instance. For more details see calling methods 
// With selector
$('#mobiscroll').mobiscroll('getInst');

// With instance
mobiscrollInstance.getInst();
getInvalids([startDate, endDate]) Returns the invalids between two dates. If startDate and endDate are not specified, it defaults to the start and end days/times of the current view. If endDate is not specified, it defaults to startDate + 1 day.

Parameters

  • startDate (Optional): Date - Start date of the specified interval.
  • endDate (Optional): Date - End date of the specified interval.

Returns: Array

  • An array containing the invalid objects.

Example

// With selector
$('#mobiscroll').mobiscroll('getInvalids');

// With instance
mobiscrollInstance.getInvalids();
getSelectedEvents() Returns the selected events.

Returns: Array

  • An array containing the selected event objects.
The selected events can be set with the setSelectedEvents method. The multiple event selection can be turned on with the selectMultipleEvents option.

Example

Methods can be called on an instance. For more details see calling methods 
// With selector
$('#mobiscroll').mobiscroll('getSelectedEvents');

// With instance
mobiscrollInstance.getSelectedEvents();
navigate(date) Navigates to the specified date on the calendar. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day.

To change the initial date of the calendar, use the selectedDate option instead.

Parameters

  • date: Date, String, Object - Date to navigate to. Can be a Date object, ISO8601 date string, or moment object.

Example

Methods can be called on an instance. For more details see calling methods 
// With selector
$('#mobiscroll').mobiscroll('navigate', new Date(2016, 1, 1));

// With instance
mobiscrollInstance.navigate(new Date(2016, 1, 1));
navigateToEvent(event)

Navigates to the specified event on the agenda/calendar/schedule/timeline views.

eventCalendarInstance.navigateToEvent(event);

Parameters

  • event: Object - The javascript event object of the event. The id, start and resource(in case if resources are used in timeline or schedule views) properties must be present in the object.
print(config)

Prints the Eventcalendar, when the print module is properly set up.

eventCalendarInstance.print();

The Print Module is an optional module, that includes styles and functions for printing. It can be installed and used with the Eventcalendar as described in the Print Module section.

Parameters

The print method can be passed a config object as parameter, that supports the following properties:
removeEvent(eventIDs) Removes one or more events from the event list based on IDs. For events without IDs, the 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 
// With selector
$('#mobiscroll').mobiscroll('removeEvent', [1, 3]);

// With instance
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 
// With selector
$('#mobiscroll').mobiscroll('setEvents', [{
    start: new Date(2016, 1, 1),
    end: new Date(2016, 1, 2),
    title: 'Conference',
    color: 'red'
}]);

// With instance
mobiscrollInstance.setEvents([{
    start: new Date(2016, 1, 1),
    end: new Date(2016, 1, 2),
    title: 'Conference',
    color: 'red'
}]);
setOptions(options) Update 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 
// With selector
$('#mobiscroll').mobiscroll('setOptions', {
    display: 'bottom'
});

// With instancee
mobiscrollInstance.setOptions({
    display: 'bottom'
});
setSelectedEvents() Sets the selected events.

Parameters

  • events: Array - An array containing the selected event objects.
The selected events are returned by the getSelectedEvents method. The multiple event selection can be turned on with the selectMultipleEvents option.

Example

Methods can be called on an instance. For more details see calling methods 
// With selector
$('#mobiscroll').mobiscroll('setSelectedEvents', [{
    id: 1,
    title: 'My selected event'
}]);

// With instance
mobiscrollInstance.setSelectedEvents([{
    id: 1,
    title: 'My selected event'
}]);
updateEvent(event) Updates an event from the event list.

Parameters

  • event: Object - The event object to update.

Example

Methods can be called on an instance. For more details see calling methods 
// With selector
$('#mobiscroll').mobiscroll('updateEvent', updatedEvent);

// With instance
mobiscrollInstance.updateEvent(updatedEvent);

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/YYYY' The format for parsed and displayed dates.
  • M - month of year (no leading zero)
  • MM - month of year (two digit)
  • MMM - month name short
  • MMMM - month name long
  • D - day of month (no leading zero)
  • DD - day of month (two digit)
  • DDD - day of week (short)
  • DDDD - day of week (long)
  • YY - year (two digit)
  • YYYY - year (four digit)
  • '...' - literal text
  • '' - single quote
  • anything else - literal text
dateFormatFull String 'DDDD, MMMM D, YYYY' Human readable date format, used by screen readers to read out full dates. Characters have the same meaning as in the dateFormat option.
dateFormatLong String 'D DDD MMM YYYY' Long date format, used by the agenda view day headers. Characters have the same meaning as in the dateFormat option.
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 Number 0 Set the first day of the week: Sunday is 0, Monday is 1, etc.
locale Object undefined Sets the language of the component. The locale option is an object containing all the translations for a given language. Mobiscroll supports a number of languages listed below. If a language is missing from the list, it can also be provided by the user. Here's a guide on how to write language modules.
Supported languages:
  • Arabic: localeAr, 'ar'
  • Bulgarian: localeBg, 'bg'
  • Catalan: localeCa, 'ca'
  • Czech: localeCs, 'cs'
  • Chinese: localeZh, 'zh'
  • Croatian: localeHr, 'hr'
  • Danish: localeDa, 'da'
  • Dutch: localeNl, 'nl'
  • English: localeEn or undefined, 'en'
  • English (UK): localeEnGB, 'en-GB'
  • Farsi: localeFa, 'fa'
  • German: localeDe, 'de'
  • Greek: localeEl, 'el'
  • Spanish: localeEs, 'es'
  • Finnish: localeFi, 'fi'
  • French: localeFr, 'fr'
  • Hebrew: localeHe, 'he'
  • Hindi: localeHi, 'hi'
  • Hungarian: localeHu, 'hu'
  • Italian: localeIt, 'it'
  • Japanese: localeJa, 'ja'
  • Korean: localeKo, 'ko'
  • Lithuanian: localeLt, 'lt'
  • Norwegian: localeNo, 'no'
  • Polish: localePl, 'pl'
  • Portuguese (Brazilian): localePtBR, 'pt-BR'
  • Portuguese (European): localePtPT, 'pt-PT'
  • Romanian: localeRo, 'ro'
  • Russian: localeRu, 'ru'
  • Russian (UA): localeRuUA, 'ru-UA'
  • Slovak: localeSk, 'sk'
  • Serbian: localeSr, 'sr'
  • Swedish:localeSv, 'sv'
  • Thai: localeTh, 'th'
  • Turkish: localeTr, 'tr'
  • Ukrainian: localeUa, 'ua'
  • Vietnamese: localeVi, 'vi'
$('#myexample').mobiscroll().eventcalendar({
  locale: mobiscroll.localeDe
});

In some cases it's more convenient to set the locale using the language code string. You can do that by using the locale object, which contains all translations by language codes as keys.

The locale object is not tree-shakeable, meaning that all translations present in the object will end up in the application bundle, whether it's being used or not. 
$('#myexample').mobiscroll().eventcalendar({
  locale: mobiscroll.locale['de']
});
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.
newEventText String New Event Title text for the newly created event with the dragToCreate action.
nextPageText String 'Next page' Text for the next page button in the calendar header, used as accessibility label.
noEventsText String 'No events' Text for empty event list.
pmText String 'pm' Text for PM.
prevPageText String 'Previous page' Text for the previous page button in the calendar header, used as accessibility label.
rtl Boolean false Right to left display.
timeFormat String 'hh:mm 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)
  • m - minutes (no leading zero)
  • mm - 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
todayText String 'Today' Label for the "Today" button.
weekText String 'Week {count}' Text for week numbers in the timeline header. The {count} inside the string will be replaced with the number of the current week.

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:

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/JQuery/dist/css/mobiscroll.jquery.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:

  1. Theme specific variables (ex. $mbsc-material-background, $mbsc-ios-dark-text) are applied to all components in a theme. Complete list of variables here.
  2. Component specific global variables (ex. $mbsc-card-background-light, $mbsc-listview-text-dark) are applied to all themes for a specific component.
  3. 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.

Tree Shaking for styles

Tree shaking is a term commonly used in web development and particularly in JavaScript for unused code removal. Since websites are served (mostly) over the network, loading times depend on content size, so minification and unused content elimination plays a major role in making webapps fluid.

For the JavaScript part, popular frameworks already have the treeshaking built in, so the components that are not used will be left out from the built project.

Eliminating unused styles

In case of the styles, leaving out the unused rules is not as straight forward.
The overarching idea is that CSS selectors match elements in the DOM, and those elements in the DOM come from all sorts of places: your static templates, dynamic templates based on server-side state, and of course, JavaScript, which can manipulate the DOM in any way at all, including pull things from APIs and third parties.

Sass variables to the rescue

The Mobiscroll Library comes with a modular SASS bundle, that can be configured which component styles and which themes to leave in and out for the compiled css file.

Every component and theme has a SASS variable that can be turned on or off. If the variable is falsy the styles that it needs will not be added to the bundle.

Example on configuring the styles
// include the ios theme
$mbsc-ios-theme: true;

// include the components:
$mbsc-datepicker: true;
$mbsc-eventcalendar: true;
        
@import "@mobiscroll/jquery/dist/css/mobiscroll.modular.scss"

In the above example the styles needed for the eventcalendar and datepicker will be included and only for the ios theme. All other components (like select or grid-layout) and all other themes will be left out from the bundle.

It's important that you override the variables BEFORE the scss file import, otherwise it won't make any difference.

Here's the complete list of the components and themes that can be used:

Some components use others internally, so it might happen that even though you don't want to include some styles, they will still end up in your bundle.
For example if you don't want to include the form components (input, button, segmented, etc...), but you are using the select component, the styles for the mobiscroll buttons, will still be in, because of the dependency.

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-calendar-background-light Sets the background color of the Eventcalendar
$mbsc-calendar-background-dark
$mbsc-calendar-text-light Sets the text color of the Eventcalendar
$mbsc-calendar-text-dark
$mbsc-calendar-accent-light Sets the accent color of the Eventcalendar
$mbsc-calendar-accent-dark
$mbsc-calendar-border-light Sets the color of the border
$mbsc-calendar-border-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-calendar-background
#f7f7f7 		The Eventcalendar background color
$mbsc-ios-calendar-text
#000000 		The Eventcalendar text color
$mbsc-ios-calendar-accent
#007bff 		The Eventcalendar accent color
$mbsc-ios-calendar-border
#cccccc 		Sets the color of the border
$mbsc-ios-calendar-mark
#cccccc 		Sets the default color of the mark on marked days

iOS Dark theme

$mbsc-ios-dark-calendar-background
##000000 		The Eventcalendar background color
$mbsc-ios-dark-calendar-text
#ffffff 		The Eventcalendar text color
$mbsc-ios-dark-calendar-accent
#ff8400 		The Eventcalendar accent color
$mbsc-ios-dark-calendar-border
#333333 		Sets the color of the border
$mbsc-ios-dark-calendar-mark
#333333 		Sets the default color of the mark on marked days

Calendar view

Indication on what the color variables affect

Agenda view

Indication on what the color variables affect

Schedule view

Indication on what the color variables affect

Windows theme

Variable name Default value Description
$mbsc-windows-calendar-background
#ffffff 		The Eventcalendar background color
$mbsc-windows-calendar-text
#333333 		The Eventcalendar text color
$mbsc-windows-calendar-accent
#0078d7 		The Eventcalendar accent color
$mbsc-windows-calendar-border
#e6e6e6 		Sets the color of the border
$mbsc-windows-calendar-mark
rgba(51, 51, 51, 0.5); 		Sets the default color of the mark on marked days

Windows Dark theme

Variable name Default value Description
$mbsc-windows-dark-calendar-background
#1a1a1a 		The Eventcalendar background color
$mbsc-windows-dark-calendar-text
#ffffff 		The Eventcalendar text color
$mbsc-windows-dark-calendar-accent
#0078d7 		The Eventcalendar accent color
$mbsc-windows-dark-calendar-border
#343434 		Sets the color of the border
$mbsc-windows-dark-calendar-mark
rgba(255, 255, 255, 0.5); 		Sets the default color of the mark on marked days

Calendar view

Indication on what the color variables affect

Agenda view

Indication on what the color variables affect

Schedule view

Indication on what the color variables affect

Material theme

Variable name Default value Description
$mbsc-material-calendar-background
#ffffff 		The Eventcalendar background color
$mbsc-material-calendar-text
#303030 		The Eventcalendar text color
$mbsc-material-calendar-accent
#1a73e8 		The Eventcalendar accent color
$mbsc-material-calendar-border
#cfcfcf 		Sets the color of the border
$mbsc-material-calendar-mark
##1a73e8 		Sets the default color of the mark on marked days

Material Dark theme

Variable name Default value Description
$mbsc-material-dark-calendar-background
#000000 		The Eventcalendar background color
$mbsc-material-dark-calendar-text
#ffffff 		The Eventcalendar text color
$mbsc-material-dark-calendar-accent
#87b0f3 		The Eventcalendar accent color
$mbsc-material-dark-calendar-border
#2b2b2b 		Sets the color of the border
$mbsc-material-dark-calendar-mark
#87b0f3 		Sets the default color of the mark on marked days

Calendar view

Indication on what the color variables affect

Agenda view

Indication on what the color variables affect

Schedule view

Indication on what the color variables affect

Google Calendar Integration

The Google Calendar Integration is a part of the third party calendar integrations plugin that manages the synchronization with your Google calendar services. For examples - simple and complex use-cases - check out the event calendar demos for jquery.

Server side tokens

By default the authentication happens entirely on the client side. However, since the introduction of the new Google Identity Services, the received access token, which ensures access to the user's calendars, is only valid for an hour. After expiry, the user will be prompted again for consent.

You can refresh an access token without prompting the user for permission, but this needs to be done on server side. To enable this, in the init config object set the auth option to 'server', and specify the authUrl and refreshUrl pointing to your server endpoints.

The authUrl endpoint will receive a POST request, containing a unique authorization code. To exchange an authorization code for an access token, send a POST request to the https://oauth2.googleapis.com/token endpoint and set the following parameters:

A sample request: 
POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=postmessage&
grant_type=authorization_code
A sample response: 
{
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3599,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/calendar.events.public.readonly https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events.owned",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}
Return the received response from the request.

The refreshUrl endpoint will also receive a POST request, containing the refresh token, received earlier. To refresh an access token, send a POST request to the https://oauth2.googleapis.com/token endpoint and set the following parameters:

A sample request: 
POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=your_refresh_token&
grant_type=refresh_token
A sample response: 
{
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3599,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/calendar.events.public.readonly https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events.owned"
}
Return the received response from the request.

Complete examples using Node.js, ASP.NET or PHP: 

// Client
import { googleCalendarSync } from '@mobiscroll/calendar-integration';

googleCalendarSync.init({
  auth: 'server',
  authUrl: 'http://example.com/auth',
  clientId: 'YOUR_CLIENT_ID',
  refreshUrl: 'http://example.com/refresh',
});

// Server
const http = require('http');
const https = require('https');

const YOUR_CLIENT_ID = 'YOUR_CLIENT_ID';
const YOUR_CLIENT_SECRET = 'YOUR_CLIENT_SECRET';

function getToken(type, codeOrToken, callback) {
    const postData =
        'client_id=' + YOUR_CLIENT_ID + '&' +
        'client_secret=' + YOUR_CLIENT_SECRET + '&' +
        (type === 'refresh' ?
            'grant_type=refresh_token&' +
            'refresh_token=' + codeOrToken
            :
            'grant_type=authorization_code&' +
            'code=' + codeOrToken + '&' +
            'redirect_uri=postmessage&' +
            'code_verifier='
        )

    const postOptions = {
        host: 'oauth2.googleapis.com',
        port: '443',
        path: '/token',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Content-Length': Buffer.byteLength(postData)
        }
    };

    const postReq = https.request(postOptions, function (response) {
        response.setEncoding('utf8');
        response.on('data', d => {
            callback(d);
        });
    });

    postReq.on('error', (error) => {
        console.log(error)
    });

    // Post the request with data
    postReq.write(postData);
    postReq.end();
}

function getPostData(req, callback) {
    let body = '';

    req.on('data', (data) => {
        body += data;
    });

    req.on('end', () => {
        const parsed = new URLSearchParams(body);
        const data = {}
        for (const pair of parsed.entries()) {
            data[pair[0]] = pair[1];
        }
        callback(data);
    });
}

function checkCSRF(req, res) {
    // Check if CSRF header is present
    if (req.headers['x-requested-with'] === 'XmlHttpRequest') {
        return true;
    }
    // Otherwise end the request
    res.statusCode = 500;
    res.end();
    return false;
}

function sendResponse(res, data) {
    // Set the headers in case of CORS request
    res.setHeader('Access-Control-Allow-Origin', '*');
    res.setHeader('Access-Control-Allow-Headers', 'X-Requested-With');
    // Send data
    res.end(data);
}

const server = http.createServer(function (req, res) {
    if (req.method === 'OPTIONS') { // Handle preflight request (in case of CORS request)
        res.setHeader('Access-Control-Allow-Origin', '*'); // Use your own domain instead of the '*'
        res.setHeader('Access-Control-Allow-Headers', 'X-Requested-With');
        res.end();
    } else if (req.url.startsWith('/auth')) { // Handle auth
        if (checkCSRF(req, res)) {
            getPostData(req, (data) => {
                // Exchange auth code to access token (on sign in)
                getToken('auth', data.code, (token) => {
                    sendResponse(res, token);
                });
            });
        }
    } else if (req.url.startsWith('/refresh')) { // Handle refresh
        if (checkCSRF(req, res)) {
            getPostData(req, (data) => {
                // Exchange refresh token to access token (on access token expiry)
                getToken('refresh', data.refresh_token, (token) => {
                    sendResponse(res, token);
                });
            });
        }
    }
});

server.listen(8080);

class HttpServer
{
    public static HttpListener listener;
    public static string url = "http://localhost:8080/";
    private static readonly HttpClient client = new HttpClient();

    public static Dictionary GetKeyValuePairs(string data)
    {
        return data.Split('&')
            .Select(value => value.Split('='))
            .ToDictionary(pair => pair[0], pair => pair[1]);
    }

    public static void SendResponse(HttpListenerRequest request, HttpListenerResponse resp, string type)
    {
        if (!request.HasEntityBody)
        {
            resp.Close();
        }
        Stream body = request.InputStream;
        StreamReader reader = new StreamReader(body, request.ContentEncoding);
        string codeOrToken = type == "auth" ? GetKeyValuePairs(reader.ReadToEnd())["code"] : GetKeyValuePairs(reader.ReadToEnd())["refresh_token"];
        string postData = "client_id=" + YOUR_CLIENT_ID + "&" +
        "client_secret=" + YOUR_CLIENT_SECRET + "&" +
        (type == "refresh" ?
            "grant_type=refresh_token&" +
            "refresh_token=" + codeOrToken
            :
            "grant_type=authorization_code&" +
            "code=" + codeOrToken + "&" +
            "redirect_uri=postmessage&" +
            "code_verifier=");

        // Set the headers in case of CORS request
        resp.AppendHeader("Access-Control-Allow-Origin", "*");
        resp.AppendHeader("Access-Control-Allow-Headers", "X-Requested-With");

        // Post the request with data
        FormUrlEncodedContent content = new FormUrlEncodedContent(GetKeyValuePairs(postData));
        HttpResponseMessage response = client.PostAsync("https://oauth2.googleapis.com/token", content).Result;

        if (response.IsSuccessStatusCode)
        {
            HttpContent responseContent = response.Content;
            string responseString = responseContent.ReadAsStringAsync().Result;
            byte[] buffer = Encoding.UTF8.GetBytes(responseString);
            // Get a response stream and write the response to it
            resp.ContentLength64 = buffer.Length;
            Stream output = resp.OutputStream;
            output.Write(buffer, 0, buffer.Length);
            output.Close();
        }
        else
        {
            Console.WriteLine("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
        }
        resp.Close();
    }

    public static bool CheckCSRF(HttpListenerRequest req, HttpListenerResponse resp)
    {
        // Check if CSRF header is present
        if (req.Headers["x-requested-with"] == "XmlHttpRequest")
        {
            return true;
        }
        // Otherwise end the request
        resp.StatusCode = 500;
        resp.Close();
        return false;
    }

    public static async Task HandleIncomingConnections()
    {
        bool runServer = true;

        // Handling requests
        while (runServer)
        {
            HttpListenerContext ctx = await listener.GetContextAsync();
            HttpListenerRequest req = ctx.Request;
            HttpListenerResponse resp = ctx.Response;

            if (req.HttpMethod == "OPTIONS")
            {   // Handle preflight request (in case of CORS request)
                resp.AppendHeader("Access-Control-Allow-Origin", "*");  // Use your own domain instead of the '*'
                resp.AppendHeader("Access-Control-Allow-Headers", "X-Requested-With");
                resp.Close();
            }
            else if (req.Url.ToString().Contains("/auth"))
            {   // Handle auth
                if (CheckCSRF(req, resp))
                {
                    SendResponse(req, resp, "auth");
                }
            }
            else if (req.Url.ToString().Contains("/refresh"))
            {   // Handle refresh
                if (CheckCSRF(req, resp))
                {
                    SendResponse(req, resp, "refresh");
                }
            }
        }
    }

    public static void Main()
    {
        // Create a Http server and start listening for incoming connections
        listener = new HttpListener();
        listener.Prefixes.Add("http://localhost:8080/");
        listener.Start();

        // Handle requests
        Task listenTask = HandleIncomingConnections();
        listenTask.GetAwaiter().GetResult();

        // Close the listener
        listener.Close();
    }
}

function checkCSRF()
{
    // Check if CSRF header is present
    if ($_SERVER['HTTP_X_REQUESTED_WITH'] === 'XmlHttpRequest') {
        return true;
    }

    // Otherwise end the request
    header("HTTP/1.1 500 Internal Server Error");
    return false;
}

function sendResponse($type)
{
    // Set the headers in case of CORS request
    header('Access-Control-Allow-Origin: *');
    header('Access-Control-Allow-Headers: X-Requested-With');

    // The data you want to send via POST
    $post_data = [
        "client_id" => $YOUR_CLIENT_ID,
        "client_secret" => $YOUR_CLIENT_SECRET,
        "grant_type" => $type === 'refresh' ? "refresh_token" : "authorization_code",
        "refresh_token" => $type === 'refresh' ? $_POST['refresh_token'] : "",
        "code" => $type === 'refresh' ? "" : $_POST['code'],
        "redirect_uri" => "postmessage",
        "code_verifier" => ""
    ];

    // url-ify the data for the POST
    $data_string = http_build_query($post_data);

    // Open connection
    $ch = curl_init();

    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'Content-Type: application/x-www-form-urlencoded',
        'Content-Length: ' . strlen($data_string),
    ));

    // Set the url, number of POST vars, POST data
    curl_setopt($ch, CURLOPT_URL, "https://oauth2.googleapis.com/token");
    curl_setopt($ch, CURLOPT_PORT, 443);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
    // SSL options are set for testing purposes
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);


    // So that curl_exec returns the contents of the cURL; rather than echoing it
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    // Execute post
    $result = curl_exec($ch);
    if (curl_errno($ch)) {
        print curl_error($ch);
    }
    echo $result;
    curl_close($ch);
}

if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') { // Handle preflight request (in case of CORS request)
    header('Access-Control-Allow-Origin: *'); // Use your own domain instead of the '*'
    header('Access-Control-Allow-Headers: X-Requested-With');
} else if (htmlspecialchars($_GET["action"]) === 'auth') { // Handle auth
    if (checkCSRF()) {
        sendResponse('auth');
    }
} else if (htmlspecialchars($_GET["action"]) === 'refresh') { // Handle refresh
    if (checkCSRF()) {
        sendResponse('refresh');
    }
}

Typescript Types

When using with typescript, the following types are available for the Calendar Integration:

Type Description
MbscGoogleCalendarSyncConfig Type of the Google Calendar init config
MbscCalendarSync Type of the synchronizable calendar service

Google Calendar Methods

Name Description
init(config) Makes the necessary initializations for the 3rd party. Calls the onInit function when the initialization is ready, if specified. The config data has the following properties:
  • clientId: String - The client ID obtained from the Google API Console Credentials page.
  • apiKey: String - The API Key obtained from the Google API Console Credentials page.
  • auth: String - Can be 'client', or 'server'. If set to 'server', server-side endpoints must be implemented to get the auth access token from Google. See the Server side tokens section for details and examples.
  • authUrl: String - Server side endpoint for receiving an access token from Google on sign in, when the auth option is set to 'server'.
  • refreshUrl: String - Server side endpoint for receiving a new access token from Google on expiry, when the auth option is set to 'server'.
  • gapi: Object - The gapi object, if already loaded. If not specified, the library will load it.
  • gis: Object - The Google Identity Services client library, if already loaded. If not specified, the library will load it.
  • scopes: String - Specify custom scopes for Google authentication. The default scopes are 'https://www.googleapis.com/auth/calendar.events.public.readonly https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events.owned'.
  • timezone: String - If specified, the event dates will be returned in this timezone.
  • timezonePlugin: Object - The timezone plugin, needed if timezone is specified.
  • onInit: Function - Callback executed when the library is initialized and ready to use.
  • onSignedIn: Function - Callback executed when the user signed in.
  • onSignedOut: Function - Callback executed when the user signed out.

Example

googleCalendarSync.init({
    apiKey: 'YOUR_APY_KEY',
    clientId: 'YOUR_CLIENT_ID',
});
signIn() If the user is not signed in, starts the sign in flow. On success, calls the onSignedIn function, if specified in the config.

Example

googleCalendarSync.signIn();
signOut() If the user is signed in, signs out. On success calls the onSignedOut function, if specified in the config.

Example

googleCalendarSync.signOut();
isSignedIn() Checks if the user is signed in or not.

Returns: Boolean

  • true if the user is signed in, false if not.

Example

googleCalendarSync.isSignedIn();
getCalendars([callback]) Returns a promise which resolves with an array containing the calendars of the signed in user. Calls the callback function, if specified.

Parameters

  • callback(Optional): Function - Callback function which is executed then the request is complete. Receives the list of calendars as parameter.

Returns: Promise

  • Returns a promise which resolves with an array containing the calendar list.

Example

googleCalendarSync.getCalendars();
getEvents(calendarIds, start, end, [callback]) Returns a promise which resolves with the events of the specific calendars between two dates. Calls the callback function, if specified.

Parameters

  • calendarIds: Array - Array of the calendar IDs.
  • start: Date - Start date of the specified interval.
  • end: Date - End date of the specified interval.
  • callback(Optional): Function - Callback function which is executed then the request is complete. Receives the list of events as parameter.

Returns: Promise

  • Returns a promise which resolves with an array containing the events.

Example

googleCalendarSync.getEvents(
    ['MY_FIRST_CALENDAR_ID', 'MY_SECOND_CALENDAR_ID'],
    new Date(2022, 1, 1),
    new Date(2022, 3, 0)
).then(function(events){
    mobiscrollInstance.setEvents(events);
});
addEvent(calendarId, event, [callback]) Adds an event to the specified calendar.

Parameters

  • calendarId: Array - The ID of the calendar.
  • event: Object - The event to add. You can pass Google specific event properties through the `googleEvent` property. The rest of custom properties will be passed to the `extendedProperties` field.
  • callback(Optional): Function - Callback function which is executed then the request is complete. Receives the added event.

Returns: Promise

  • Returns a promise which resolves with the added event.

Example

googleCalendarSync.addEvent(
    'MY_CALENDAR_ID', 
    { 
        start: new Date(2022, 1, 15, 12),
        end: new Date(2022, 1, 16, 14),
        title: 'My new event',
        googleEvent: {
            description: 'My new event description'
        }
    });
updateEvent(calendarId, event, [callback]) Updates an event in the specified calendar.

Parameters

  • calendarId: Array - The ID of the calendar.
  • event: Object - The event to update. You can pass Google specific event properties through the `googleEvent` property.
  • callback(Optional): Function - Callback function which is executed then the request is complete. Receives the updated event as parameter.

Returns: Promise

  • Returns a promise which resolves with the updated event.

Example

googleCalendarSync.updateEvent(
    'MY_CALENDAR_ID', 
    { 
        start: new Date(2022, 1, 20, 10),
        end: new Date(2022, 1, 11, 15),
        title: 'My updated event',
        id: 1,
        googleEvent: {
            description: 'My updated event description'
        }
    });
deleteEvent(calendarId, event, [callback]) Removes an event in the specified calendar.

Parameters

  • calendarId: Array - The ID of the calendar.
  • event: Object - The event to remove.
  • callback(Optional): Function - Callback function which is executed then the request is complete. Receives the deleted event as parameter.

Returns: Promise

  • Returns a promise which resolves with the removed event.

Example

googleCalendarSync.deleteEvent(
    'MY_CALENDAR_ID', 
    { 
        title: 'My event'
        id: 1, 
    });

Click here to find more information about the Third Party Calendar Integration.

Outlook Calendar Integration

The Outlook Calendar Integration is a part of the third party calendar integrations plugin that manages the synchronization with your Outlook calendar services. For examples - simple and complex use-cases - check out the event calendar demos for jquery.

Typescript Types

When using with typescript, the following types are available for the Calendar Integration:

Type Description
MbscOutlookCalendarSyncConfig Type of the Outlook Calendar init config
MbscCalendarSync Type of the synchronizable calendar service

Methods

Name Description
init(config) Makes the necessary initializations for the 3rd party. Calls the onInit function when the initialization is ready, if specified. The config data has the following properties:
  • clientId: String - The client ID obtained from the Outlook web app.
  • msal: Object - The Microsoft Authentication Library, if already loaded. If not specified, the library will load it.
  • msalClient: Object - The instance of the client application, if already loaded. If not specified, the library will load it.
  • pageSize: Number - The maximum number of events to retreive with one request. Default value is '1000'.
  • redirectUri: String - The location where the authorization server sends the user once the app has been successfully authorized. Default value is 'http://localhost:3000'.
  • timezone: String - If specified, the event dates will be returned in this timezone.
  • timezonePlugin: Object - The timezone plugin, needed if timezone is specified.
  • onInit: Function - Callback executed when the library is initialized and ready to use.
  • onSignedIn: Function - Callback executed when the user signed in.
  • onSignedOut: Function - Callback executed when the user signed out.

Example

outlookCalendarSync.init({
    clientId: 'YOUR_CLIENT_ID',
    redirectUri 'MY_REDIRECT_URI',
});
signIn() If the user is not signed in, starts the sign in flow. On success, calls the onSignedIn function, if specified in the config.

Example

outlookCalendarSync.signIn();
signOut() If the user is signed in, signs out. On success calls the onSignedOut function, if specified in the config.

Example

outlookCalendarSync.signOut();
isSignedIn() Checks if the user is signed in or not.

Returns: Boolean

  • true if the user is signed in, false if not.

Example

outlookCalendarSync.isSignedIn();
getCalendars([callback]) Returns a promise which resolves with an array containing the calendars of the signed in user. Calls the callback function, if specified.

Parameters

  • callback(Optional): Function - Callback function which is executed then the request is complete. Receives the list of calendars as parameter.

Example

outlookCalendarSync.getCalendars();
getEvents(calendarIds, start, end, [callback]) Returns a promise which resolves with the events of the specific calendars between two dates. Calls the callback function, if specified.

Parameters

  • calendarIds: Array - Array of the calendar IDs.
  • start: Date - Start date of the specified interval.
  • end: Date - End date of the specified interval.
  • callback(Optional): Function - Callback function which is executed then the request is complete. Receives the list of events as parameter.

Returns: Promise

  • An array containing the event list.

Example

outlookCalendarSync.getEvents(
    ['MY_FIRST_CALENDAR_ID', 'MY_SECOND_CALENDAR_ID'],
    new Date(2022,1,1),
    new Date(2022,3,0)
).then(function(events){
    mobiscrollInstance.setEvents(events);
});
addEvent(calendarId, event, [callback]) Adds an event to the specified calendar.

Parameters

  • calendarId: Array - The ID of the calendar.
  • event: Object - The event to add. You can pass Outlook specific event properties through the `outlookEvent` property.
  • callback(Optional): Function - Callback function which is executed then the request is complete. Receives the added event as parameter.

Returns: Promise

  • Returns a promise which resolves with the added event.

Example

outlookCalendarSync.addEvent(
    'MY_CALENDAR_ID', 
    { 
        start: new Date(2022,1,15,12),
        end: new Date(2022,1,16,14),
        title: 'My new event',
        outlookEvent: {
            isReminderOn: true
        }
    });
updateEvent(calendarId, event, [callback]) Updates an event in the specified calendar.

Parameters

  • calendarId: Array - The ID of the calendar.
  • event: Object - The event to update. You can pass Outlook specific event properties through the `outlookEvent` property.
  • callback(Optional): Function - Callback function which is executed then the request is complete. Receives the updated event as parameter.

Returns: Promise

  • Returns a promise which resolves with the updated event.

Example

outlookCalendarSync.updateEvent(
    'MY_CALENDAR_ID', 
    { 
        start: new Date(2022,1,20,10),
        end: new Date(2022,1,11,15),
        title: 'My updated event'
        id: 1,
        outlookEvent: {
            isReminderOn: false
        }
    });
deleteEvent(calendarId, event, [callback]) Removes an event in the specified calendar.

Parameters

  • calendarId: Array - The ID of the calendar.
  • event: Object - The event to remove.
  • callback(Optional): Function - Callback function which is executed then the request is complete. Receives the deleted event as parameter.

Returns: Promise

  • Returns a promise which resolves with the removed event.

Example

outlookCalendarSync.deleteEvent(
    'MY_CALENDAR_ID', 
    { 
        title: 'My event'
        id: 1, 
    });

Click here to find more information about the Third Party Calendar Integration.

Accessibility

Keyboard Support

The event calendar supports different views for different jobs and each of these views support keyboard navigation.

Focus can be moved with the Tab key. Focusable elements depend on the displayed view (more details below).

Buttons can be triggered using the Space key when focused.

Rendered events act like buttons. When an event is focused, the onEventClick event can be triggered using the Space or Enter keys.

Calendar view

Focusable elements are:

When the selected day is focused, the focus can be moved using the Up, Down, Left and Right arrow keys and set with the Space or Enter keys.

When the popover is enabled on events, it can be toggled using the Space and Esc keys.

Agenda

Focusable elements are:

Scheduler

Focusable elements are:

Timeline

Focusable elements are:

Products
for Javascript
for jQuery
for Angular
for React
for Vue
View Controls
View Pricing
Download Products
Features
Event calendar & scheduler
Date picker & calendar
FullCalendar alternative
Resources
blog
community forum
ui patterns
support & learning
knowledge base
docs
releases
status
faq
report a bug
Company
about us
contact
customers
reviews
twitter
facebook
Legal
terms & conditions
privacy
cookie policy
eula
© 2024 Acid Media LLC - VAT No. RO19333154     All trademarks © their respective owners. Site uses cookies, you agree to this by browsing it.