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.

// Mobiscroll 4.x
mobiscroll.settings = {
    theme: 'ios'
};

// Mobiscroll 5.x
mobiscroll.setOptions({
    theme: 'ios'
});

// 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.

// Mobiscroll 4.x
mobiscrollInst.option({
    theme: 'ios'
});

// 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.

// Mobiscroll 4.x
mobiscroll.settings = {
    lang: 'de'
};

// Mobiscroll 5.x
mobiscroll.setOptions({
    locale: mobiscroll.localeDe
});

// 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';.

// Mobiscroll 4.x
mobiscroll.util.getJson('http://example.com/method', callback);

// Mobiscroll 5.x
mobiscroll.util.http.getJson('http://example.com/method', callback);

// 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

// Mobiscroll 4.x

// Date scroller
mobiscroll.date('#mydate');

// Time scroller
mobiscroll.time('#mytime');

// Date & time scroller expanded
mobiscroll.datetime('#mydatetime');

// Date & time scroller compact
mobiscroll.datetime('#mydatetime', {
    dateWheels: '|D M d|'
});

// Calendar
mobiscroll.calendar('#mycalendar');

// Calendar & time
mobiscroll.calendar('#mycalendar', {
    controls: ['calendar', 'time']
});

// Range
mobiscroll.range('#myrange');

// Mobiscroll 5.x

// Date scroller
mobiscroll.datepicker('#mydate', {
    controls: ['date']
});

// Time scroller
mobiscroll.datepicker('#mytime', {
    controls: ['time']
});

// Date & time scroller expanded
mobiscroll.datepicker('#mydatetime', {
    controls: ['date', 'time']
});

// Date & time scroller compact
mobiscroll.datepicker('#mydatetime', {
    controls: ['datetime']
});

// Calendar
mobiscroll.datepicker('#mycalendar', {
    controls: ['calendar']
});

// Calendar & time
mobiscroll.datepicker('#mycalendar', {
    controls: ['calendar', 'time']
});

// Range
mobiscroll.datepicker('#myrange', {
    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

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.

Forms

In version 5 the Form component is no longer present, you need to use the individual form components instead.

When form components are added dynamically to the markup, you can use the enhance function, which will initialize the newly added form comonents inside the given container.

mobiscroll.enhance('#my-container');

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.

Select

Removed

We removed the counter option. This is currently not supported in v5.

We removed the dataGroup, dataHtml, dataValue and dataText options. These are currently not supported in v5.

We removed the dropdown and inputClass options. The rendered element can be entirely customized with the inputElement option.

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

We removed the multiline option. This is currently not supported in v5.

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

Changed

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

The data option only supports an array of items with the text, value, group and disabled properties. HTML content for options is supported from version 5.12.0 using the renderItem option. Read the "Customizing the select items" section for more details.
Remote data source is not supported out of the box in v5. You will have to manually get the remote data and pass that to the select.
For remote filtering the onFilter event can be used to get the filter text. By returning false in the onFilter handler, the filtering is left for the developer to be carried out. Then the text can be used to query the filtered data in any way you see fit and update the select.

We changed the group option to showGroupWheel. It no longer accepts an object, but only a boolean, which controls if the group wheel is shown or not. When available, the group headers are always shown and the clustered property is not longer supported.

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 changed the input option to inputElement option, which accepts a HTMLElement. Selectors are not supported, but can be used to query the element and pass the element to the option.

We renamed the select option to selectMultiple, which became a boolean indicating multiple select when true. We no longer support a fix number of selected items.

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

Button

Changed

Instead of adding the 'mbsc-btn-flat' and 'mbsc-btn-outline' css classes we added the data-variant option to the button, which can be 'standard', 'flat', or 'outline'.

Checkbox

Changed

Instead of specifying the label text before the input, it can be passed using the data-label attribute on the input.

// Mobiscroll 4.x
<label>
    Label text
    <input mbsc-checkbox type="checkbox" />
</label>

// Mobiscroll 5.x
<label>
    <input mbsc-checkbox type="checkbox" data-label="Label text" />
</label>

Dropdown

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

Image

There is no Image component in v5, instead the functionality can be achieved with the select component by customizing the select items. Starting from version 5.12.0 the select component items can be customized to any custom markup using the renderItem option. Please refer to the "Customizing the select items" section for more details.

Input

Changed

Instead of specifying the label text before the input, it can be passed using the data-label attribute on the input.

// Mobiscroll 4.x
<label>
    Label text
    <input mbsc-input />
</label>

// Mobiscroll 5.x
<label>
    <input mbsc-input data-label="Label text" />
</label>

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 before the input, it can be passed using the data-label attribute on the input.

// Mobiscroll 4.x
<label>
    Label text
    <input mbsc-radio type="radio" />
</label>

// Mobiscroll 5.x
<label>
    <input mbsc-radio type="radio" data-label="Label text" />
</label>

Switch

Changed

Instead of specifying the label text before the input, it can be passed using the data-label attribute on the input.

// Mobiscroll 4.x
<label>
    Label text
    <input mbsc-switch type="checkbox" />
</label>

// Mobiscroll 5.x
<label>
    <input mbsc-switch type="checkbox" data-label="Label text" />
</label>

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.

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.

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 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.