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 < 5.0 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({
    locale: 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, calendar and range components into a single datepicker component. Use this instead of the v4 standalone components. You can specify the appearance using the controls option, and the select mode (date or range) using the select option

Old code
// Mobiscroll 4.x

// Date scroller
<mobiscroll.Date />

// Time scroller
<mobiscroll.Time />

// Date & time scroller expanded
<mobiscroll.Datetime />

// Date & time scroller compact
<mobiscroll.Datetime dateWheels="|D M d|" />

// Calendar
<mobiscroll.Calendar />

// Calendar & time
<mobiscroll.Calendar controls={['calendar', 'time']} />

// Range
<mobiscroll.Range />
New code
// Mobiscroll 5.x

// Date scroller
<Datepicker controls={['date']} />

// Time scroller
<Datepicker controls={['time']} />

// Date & time scroller expanded
<Datepicker controls={['date', 'time']} />

// Date & time scroller compact
<Datepicker controls={['datetime']} />

// Calendar
<Datepicker controls={['calendar']} />

// Calendar & time
<Datepicker controls={['calendar', time]} />

// Range
<Datepicker select="range" />

Removed

We removed the calendarHeight option, use the heigth option instead.

We removed the calendarWidth option, use the width option instead.

We removed the layout option, use the width and heigth options instead.

We removed the outerMonthChanged option, this is now handled automatically.

We removed the selectType option, week selection is currently not supported in v5.

We removed the selectType option, week selection is currently not supported in v5.

We removed the showLabel option, wheel labels are currently not supported in v5.

We removed the showScrollArrows option, wheel scroll arrows are currently not supported in v5.

We removed the yearChange option, now the calendar has a re-designed navigation.

We removed the weekDays option, this is now handled automatically.

We removed the onBeforeClose event.

We removed the onBeforeShow event.

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 Datepicker component will now render a Mobiscroll Input by default, compared to version 4, where a standard html input was the default. The rendered input component can be changed using the inputComponent and the inputProps options.

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

We renamed the counter option to selectCounter to specify the show / hide number of selected dates in the header.

We renamed the defaultValue option to defaultSelection to specify the initial selection, for better compatibility with React, where defaultValue refers to the actual value instead of a pre-selection in case of uncontrolled usage.

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 months option to pages, because it sets the number of displayed pages in case of week view as well, not just month view.

We've broken up the select option into selectMultiple and selectMax.

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

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

We renamed the weekCounter option to showWeekNumbers for showing the week numbers on the calendar.

We changed the behavior of the weeks option, weeks: 6 no longer means month view automatically. Month or week view needs to be set with the calendarType option.

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 onChange event to onTempChange This was part of the lifecycle event cleanup we performed.

We renamed the onDayChange event to onCellClick This was part of the lifecycle event cleanup we performed.

We renamed the onLabelTap event to onLabelClick This was part of the lifecycle event cleanup we performed.

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

We renamed the onShow event to onOpen 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.

Button

Changed

Instead of the flat and outline props we added the variant option to the button, which can be 'standard', 'flat', or 'outline'.

Checkbox

Changed

Instead of specifying the label text as the component children, it can be passed using the label prop.

Old code
// Mobiscroll 4.x
<mobiscroll.Checkbox>Label text</mobiscroll.Checkbox>
New code
// Mobiscroll 5.x
<Checkbox label="Label text" />

Dropdown

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

Input

Changed

Instead of specifying the label text as the component children, it can be passed using the label prop.

Old code
// Mobiscroll 4.x
<mobiscroll.Input>Label text</mobiscroll.Input>
New code
// Mobiscroll 5.x
<Input label="Label text" />

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

Radio

Changed

Instead of specifying the label text as the component children, it can be passed using the label prop.

Old code
// Mobiscroll 4.x
<mobiscroll.Radio>Label text</mobiscroll.Radio>
New code
// Mobiscroll 5.x
<Radio label="Label text" />

Switch

Changed

Instead of specifying the label text as the component children, it can be passed using the label prop.

Old code
// Mobiscroll 4.x
<mobiscroll.Switch>Label text</mobiscroll.Switch>
New code
// Mobiscroll 5.x
<Switch label="Label text" />

Popup

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.

We removed the layout option, giving better control with the width, height, maxWidth, maxHeight and fullScreen options options.

We removed the onBeforeClose event.

We removed the onBeforeShow event.

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

For the sake of clarity we renamed the showOnOverlayTap option to showOnOverlayClick, and the onShow event to onOpen.

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

Using Mobiscroll v4 alongside v5

The 5th major version of Mobiscroll contains a limited number of components, compared to v4. If you need to keep using some components from v4, which are not present in the newer version, please follow this guide.