Mobiscroll 5.0 Upgrade Guide

Overview

Introducing Mobiscroll 5 Beta 1 - a complete rewrite and retooling that enables better extensibility and performance. We moved away from the wrapper approach for Angular & React, and so with the new architecture we can ship native components for those frameworks.

We are shipping Mobiscroll 5 in steps and the first beta features Event calendar, Popup, the brand new Scheduler, most of the Form elements - Button, Input, Dropdown, Textarea, Checkbox, Switch, Radio, Segmented & Notifications and Date & time picker with limited functionality.

Below is the list of the breaking changes introduced with Mobiscroll 4.0.

Browser support

Starting from Mobiscroll 5.0 we no longer support Android < 4.4 and iOS < 9.

Frameworks

AngularJS (Angular 1.x) integration is not maintained anymore. Please use the plain Javascript version instead.

Angular 2 is no longer supported. Please upgrade to Angular 4+ to continue using Mobiscroll.

Themes

For the first beta release the Mobiscroll theme is not yet available. The currently available themes are iOS, Material and Windows, in light and dark variants.

General

Global options

We removed the mobiscroll.settings object, and added the setOptions function instead. The setOptions function can be called any time, and will update the options for the existing components.

Old code
// Mobiscroll 4.x
mobiscroll.settings = {
    theme: 'ios'
};
New code
// Mobiscroll 5.x
mobiscroll.setOptions({
    theme: 'ios'
});
ES6 format
// Mobiscroll 5.x
import { setOptions } from './path/to/mobiscroll';

setOptions({
    theme: 'ios'
});

option method rename

We renamed the option method to setOptions for each component.

Old code
// Mobiscroll 4.x
mobiscrollInst.option({
    theme: 'ios'
});
New code
// Mobiscroll 5.x
mobiscrollInst.setOptions({
    theme: 'ios'
});

lang option rename

We renamed the lang option to locale for localizing the components. Instead of a string now it accepts an object containing the localization settings.

Old code
// Mobiscroll 4.x
mobiscroll.settings = {
    lang: 'de'
};
New code
// Mobiscroll 5.x
mobiscroll.setOptions({
    locale: mobiscroll.localeDe
});
ES6 format
// Mobiscroll 5.x
import { localeDe, setOptions } from './path/to/mobiscroll';

setOptions({
    theme: localeDe
});

getJson util function location

We moved the getJson function to mobiscroll.util.http.getJson. In ES6 it can also be imported directly: import { getJson } from './path/to/mobiscroll';.

Old code
// Mobiscroll 4.x
mobiscroll.util.getJson('http://example.com/method', callback);
New code
// Mobiscroll 5.x
mobiscroll.util.http.getJson('http://example.com/method', callback);
ES6 format
// Mobiscroll 5.x
import { getJson } from './path/to/mobiscroll';

getJson('http://example.com/method', callback);

Datepicker

We merged the date, datetime, time and calendar components into a single datepicker component. Use this instead of the v4 standalone components. You can specify the appearance using the controls option.

Removed

We removed the tap method, which was a utility function used to attach the tap event to arbitrary elements, handling the 300ms click delay on older devices. On today's devices this is no longer needed, simply use the native click event.

Changed

The React component will render a mobiscroll input by default, instead of a standard html input.

We renamed the animate option to animation to specify the show / hide animation of the picker.

We renamed the height option to itemHeight for setting the height of the wheel items.

We renamed the width option to wheelWidth for setting the exact width of the wheels.

We renamed the maxWidth option to maxWheelWidth for setting the maximum width of the wheels.

We renamed the minWidth option to minWheelWidth for setting the minimum width of the wheels.

We renamed the showOnTap option to showOnClick for the sake of simplicity and to make it more obvious.

We've broken up the steps option into stepHour, stepMinute and stepSecond.

We updated the format of the dateFormat and timeFormat options to avoid some common confusions we met. See the API docs for the new formatting tokens.

We renamed the onSet event to onChange and theonShow event to onOpen for more clarity. This was part of the lifecycle event cleanup we performed.

We renamed the show method to open and the hide method to close.

Event calendar

Removed

We removed the following options: anchor, animate, buttons, closeOnOverlayTap, display, focusOnClose, focusTrap, formatDuration, headerText, showOnFocus, showOnTap, yearChange.

We removed the following events: onBeforeClose, onBeforeShow, onClose, onPosition, onShow.

We removed the following methods: hide, isVisible, position, redraw, refresh, show, tap.

Changed

We improved our recurring event support. More complex recurrence rules can be passed through the recurring property of an event as an object or as a string in RRULE format. Currently daily, weekly, monthly and yearly repeats are supported.

We slightly changed the structure of event objects. Instead of text, title should be used, and instead of the d property use the recurring property to create recurring events.

We slightly changed the structure of the marked, label and color objects. To specify the date, use the date property, or the start and end properties for multiple days, and use the recurring property to specify multiple occurrences.

We updated the format of the dateFormat and timeFormat options to avoid some common confusions we met. See the API docs for the new formatting tokens.

As part of the the lifecycle event cleanup, we renamed the onEventSelect event to onEventClick, the onDayChange event to onCellClick and the onSetDate event to onSelectedDateChange.

We renamed the calendarHeight option to height and changed its scope to the full calendar with header and everything.

We renamed the calendarWidth option to width.

We moved the calendarScroll option into the view option under view.calendar.scroll.

We moved the eventBubble option into the view option under view.calendar.popover.

We moved the showEventCount option into the view option under view.calendar.count.

We moved the showOuterDays option into the view option under view.calendar.outerDays.

We moved the weeks option into the view option under view.calendar.size.

We moved the weekCounter option into the view option under view.calendar.weekNumbers.

We renamed the eventList property of the view option to agenda.

Scheduler

We added the brand new scheduler to the Event Calendar product line for displaying the events on a 24-hour grid. Can be enabled using the view option.

Forms

Changed

We removed the iconAlign option, and added the startIcon and endIcon options instead to specify the input icons.

We added the variant option to the button, which can be 'standard', 'flat', or 'outline'.

Popup

Removed

We removed the tap method, which was a utility function used to attach the tap event to arbitrary elements, handling the 300ms click delay on older devices. On today's devices this is no longer needed, simply use the native click event.

Changed

We renamed the animate option to animation to specify the show / hide animation of the popup.

For the sake of clarity we renamed the showOnTap option to showOnClick and the onShow event to onOpen.

We renamed the show method to open and the hide method to close.