Mobiscroll 3.0 removes or modifies several APIs that behaved inconsistently or inefficiently in the past. The majority of these changes have been foreshadowed by their deprecation in previous versions of Mobiscroll, however there are a few, which could not be intruduced incrementally, without breaking backward compatibility.

In making these changes, our goal was to fix inconsistencies between components, and in the process improve both file size and overall performance.

One of the greatest improvements in Mobiscroll 3.0 is that jQuery is no longer a dependency, but, if jQuery is loaded, Mobiscroll still works with the jQuery plugin syntax, so this change in itself does not break backward compatibility.

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

Browser support

Starting from Mobiscroll 3.0 we no longer support Android 2.3, IE8 and IE9.

If you still need to support some of browsers above mentioned above, keep using Mobiscroll 2.x.

New way of passing event arguments

This is probably the change that will affect the most Mobiscroll users. Until now the event arguments were passed as individual parameters to the handler function, the last always being the instance of the component. There were problems with this approach:

If we decided to introduce a new event argument, it meant that the instance parameter was shifted, so if someone used the instance parameter in that event handler, the code broke when upgraded to the new version
It's inconvenient to use, if you only need some of the parameters, but you still have to list them for your handler functions.

Mobiscroll 3.0 introduces a unified way of passing event arguments, there are always 2 parameters passed:

An event object containing the necessary properties.
The instance of the component.

If you are using any events in your existing code, make sure you rewrite your event handler functions. Example:

Old code

// Mobiscroll 2.x
onEventSelect: function (e, event, date, inst) {
    // Original code ...
}

New code

// Mobiscroll 3.x
onEventSelect: function (event, inst) {
    var e = event.domEvent,
        event = event.event,
        date = event.date;
    // Original code ...
}

For the event object property names see the API docs reference for the particular component.

Removed component names

rangepicker - Renamed to range.

Old code

$('#range').mobiscroll().rangepicker({
    // ...
});

New code React

$('#range').mobiscroll().range({
    // ...
});

colorpicker - Renamed to color.

Old code

$('#color').mobiscroll().colorpicker({
    // ...
});

New code

$('#color').mobiscroll().color({
    // ...
});

Removed functionality

Calendar

In Mobiscroll 3.x the Event Calendar is a separate component, the Calendar has no more event management functionality, however it can still display marked days, text and icons on days.

Migrating from the Calendar to the Event Calendar is easy, use .eventcalendar() instead of .calendar(), and the data setting instead of events.

Old code

$('#events').mobiscroll().calendar({
    events: [
        // ...
    ]
});

New code

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

Removed methods

The getValue, getValues, setValue and setValues deprecated methods were removed from all components. If you were still using these, change them to the new setVal and getVal methods.

The order of parameters also changed, so make sure you pass them in the correct order.

Old method	New method
`getValue`	`getVal([temp])`
`getValues`	`getVal([temp])`
`setValue(value [, fill ] [, time ] [, temp ])`	`setVal(value [, fill ] [, change ] [, temp ] [, time ])`
`setValues([ fill ])`	`setVal(value [, fill ] [, change ] [, temp ] [, time ])`

Removed options

General

tap - This option was used to enable/disable 'fastclick' functionality (remove 300ms click delay on touch screens). It was true by default, but could be turned of, to use normal click events. We consider the implementation stable, so there should not be any reason to turn this off.

Scroller based components

mode - 'clickpick' mode is no longer supported. Use the showScrollArrows setting to display arrows for the wheel. This is the equivalent of the 'mixed' mode in Mobiscroll 2.x.

Calendar

swipe - This option was used to disable changing the month using swipe gesture. We consider this is no longer necessary.
liveSwipe - If was set to false, month container was slided only after the swipe gesture was finished. It was useful on older systems, which had trouble moving the month container live during the touch gesture. We consider this is no longer necessary.
markedDisplay - This option was used to define the styling of marked days. In 3.x only one marked styling is available.
markedText - This option was used to display text and icons on days instead of marks. Use the events option instead.
quickNav - If true, tapping on month name or year in month header switches the calendar in month or year selection mode. We consider this an essential feature, so turning it off is no longer an option.
selectedValues - Use the defaultValue setting instead.

Range

rangeTap - In Mobiscroll 3.x this is the behavior by default.

Timer

controls - Use the buttons setting instead.

Changed methods

Scroller

changeWheel - The usage of the method slightly changed, there is no need to modify the wheels setting before calling the method.

Old code

// Mobiscroll 2.x
mobiscrollInstance.settings.wheels[0][0] = {
    label: 'Wheel 1',
    data: [
        { value: 0, display: 'a' },
        { value: 1, display: 'b' },
        { value: 2, display: 'c' }
    ]
};
mobiscrollInstance.changeWheel([0]);

New code

// Mobiscroll 3.x
mobiscrollInstance.changeWheel({
    0: {
        data: [
            { value: 0, display: 'a' },
            { value: 1, display: 'b' },
            { value: 2, display: 'c' }
        ]
    }
});

Changed options

General

display - The 'modal' value is renamed to 'center'. The modal term was confusing, as 'top', 'bottom' and 'bubble' also display the control in modal mode (meaning that interaction of other parts of the page is temporary disabled).
closeOnOverlay - Renamed to closeOnOverlayTap.

Scroller based components

fixedWidth - Use width to set the fixed width of the wheels instead.
width - Use minWidth to set the minimal width of the wheels instead.

Scroller

wheels - keys can be no longer specified as a separate array, instead pass an array of objects through the values property.

Old code

// Mobiscroll 2.x
wheels: [[
    {
        label: 'Wheel 1',
        keys: [0, 1, 2, 3],
        values: ['a', 'b', 'c', 'd']
    }
]]

New code

// Mobiscroll 3.x
wheels: [[
    {
        label: 'Wheel 1',
        data: [
            { value: 0, display: 'a' },
            { value: 1, display: 'b' },
            { value: 2, display: 'c' },
            { value: 3, display: 'd' }
        ]
    }
]]

Calendar

closeOnSelect - Renamed to setOnDayTap.
divergentDayChange - Renamed to outerMonthChange.
multiSelect - Renamed to select to be consistent with other components. Possible values are 'single' and 'multiple'.
navigation - Renamed to yearChange, with true and false as possible values.
showDivergentDays - Renamed to showOuterDays.
swipeDirection - Renamed to calendarScroll.

Calendar, Date & Time

dateOrder - Renamed to dateWheels to be consistent with the timeWheels setting.
minDate - Renamed to min to be consistent with other components.
maxDate - Renamed to max to be consistent with other components.

Listview

altRow - Renamed to striped.

Measurements

defUnit - Renamed to defaultUnit.

Numpad

leftButton - Renamed to leftKey.
rightButton - Renamed to rightKey.

Select

multiple - Renamed to select to be consistent with other components. Possible values are 'single' and 'multiple'. If mulitiple selection was enabled from HTML attribute, there's no need to change anything.

Timespan

minTime - Renamed to min to be consistent with other components.
maxTime - Renamed to max to be consistent with other components.

Changed events

General

onClose - This event was deprecated in version 2.17.0, and the onBeforeClose and onClosed events were introduced instead. In 3.x the onClosed event is renamed to onClose.

Old code

// Mobiscroll 2.x
onClose: function (valueText, btn, inst) {
    // Original code ...
},
onClosed: function (valueText, inst) {
   // Original code ...
}

New code

// Mobiscroll 3.x
onBeforeClose: function (event, inst) {
    var btn = event.button,
        valueText = event.valueText;
    // Original code ...
},
onClose: function (event, inst) {
   var valueText = event.valueText;
   // Original code ...
}

onSelect - Renamed to onSet, will be triggered not only on Set button click, but whenever the value is written, either programmatically, or from the UI.

Scroller based components

onValueTap - Renamed to onItemTap to be consistent with other components.

Measurement changes

Distance, Force, Mass, Speed and Temperature were merged into one single component, named Measurement.

Utility functions moved

Due to collisions with the jQuery-less initialization the formatDate and parseDate utility functions were moved:

Old location	New location
`$.mobiscroll.datetime.formatDate(format, date[, settings = {}])`	`mobiscroll.util.datetime.formatDate(format, date[, settings = {}])`
`$.mobiscroll.datetime.parseDate(format, value[, settings = {}])`	`mobiscroll.util.datetime.parseDate(format, value[, settings = {}])`

Removed theme names

The following deprecated theme names were removed:

'android-ics' - Use 'android-holo' instead.
'android-ics light' - Use 'android-holo-light' instead.
'android-holo light' - Use 'android-holo-light' instead.
'wp light' - Use 'wp-light' instead.
'ios7' - Use 'ios' instead.

Removed themes

In 3.0 we decided to remove some of the themes, which mimics the appearance of outdated and/or low marketshare operating systems.

The following themes were removed:

'android'
'ios-classic'
'sense-ui'
'sense'
'sense-dark'

If you still wish to use some of the above themes, keep using Mobiscroll 2.x. Mobiscroll 2.x will be still maintained, but new features won't be introduced.

Bootstrap theme

From Mobiscroll 3.0 the Bootstrap theme no longer supports Bootstrap 2.x, Bootstrap 3.x is required.

If you still need support for Bootstrap 2.x, keep using Mobiscroll 2.x. Mobiscroll 2.x will be still maintained, but new features won't be introduced.

jQuery Mobile theme

From Mobiscroll 3.0 the jQuery Mobile theme no longer supports jQuery Mobile < 1.4, jQuery Mobile 1.4.x is required.

If you still need support for jQuery Mobile < 1.4, keep using Mobiscroll 2.x. Mobiscroll 2.x will be still maintained, but new features won't be introduced.

The `mobiscroll` global variable

Prior to 3.0 the utility functions and other internal functionality was stored in the $.mobiscroll object. Since jQuery is no longer a dependency, everything is moved in the mobiscroll global object.

To make the transition easier, the mobiscroll object is still mapped to $.mobiscroll, if jQuery is loaded. But if you'd like to use Mobiscroll without jQuery, or to make the code future-proof, refactor the code to use the functions and properties through the mobiscroll global object:

To set global options, instead of the setDefaults function, use the mobiscroll.settings global object.

Old location	New location
`$.mobiscroll.activeInstance`	`mobiscroll.activeInstance`
`$.mobiscroll.setDefaults(options)`	`mobiscroll.settings`
`$.mobiscroll.datetime.formatDate(format, date[, settings = {}])`	`mobiscroll.util.datetime.formatDate(format, date[, settings = {}])`
`$.mobiscroll.datetime.parseDate(format, value[, settings = {}])`	`mobiscroll.util.datetime.parseDate(format, value[, settings = {}])`
`$.mobiscroll.util.vibrate([time = 50])`	`mobiscroll.util.vibrate([time = 50])`

Changed css classes

Some of the css classes were also refactored to use the .mbsc- prefix. This only affects your existing code, if you used custom CSS classes to override built in styling.

List of changed CSS classes:

Popup

Old CSS class	New CSS class	Element
.dwo	.mbsc-fr-overlay	Background overlay
.dw-persp	.mbsc-fr-persp	Perspective (used for animations)
.dw	.mbsc-fr-popup	Component container
.dw-liq	.mbsc-fr-liq	Liquid layout component
.dw-inline	.mbsc-fr-inline	Inline display mode
.dw-bubble	.mbsc-fr-bubble	Bubble display mode
.dw-bubble-top	.mbsc-fr-bubble-top	Bubble above anchor
.dw-bubble-bottom	.mbsc-fr-bubble-bottom	Bubble belove anchor
.dw-arrw	.mbsc-fr-arr-w	Bubble arrow wrapper
.dw-arrw-i	.mbsc-fr-arr-i	Bubble arrow inner wrapper
.dw-arr	.mbsc-fr-arr	Bubble arrow
.dwwr	.mbsc-fr-w	Component content wrapper
.dwv	.mbsc-fr-hdr	Component header
.dwbc	.mbsc-fr-btn-cont	Button container
.dwbw	.mbsc-fr-btn-w	Button wrapper
.dwb	.mbsc-fr-btn	Button
.dwb-e	.mbsc-fr-btn-e	Enabled button
.dwb-d	.mbsc-fr-btn-d	Disabled button

Scroller

Old CSS class	New CSS class	Element
.dwc	.mbsc-sc-whl-gr-c	Wheel group container
.dwwc	.mbsc-sc-whl-gr	Wheel group
.dwfl	.mbsc-sc-whl-w	Wheel wrapper
.dwl	.mbsc-sc-lbl	Wheel label
.dwwl	.mbsc-sc-whl	Wheel
.dwa	.mbsc-sc-whl-a	Active wheel
.dwwo	.mbsc-sc-whl-o	Wheel overlay
.dwwol	.mbsc-sc-whl-l	Wheel selection line
.dwww	-	Wheel scroller container wrapper
.dww	.mbsc-sc-whl-c	Wheel scroller container
.dw-ul	.mbsc-sc-whl-sc	Wheel scroller
.dw-bf	-	Wheel item batch
.dw-li	.mbsc-sc-itm	Wheel item
.dw-i	-	Wheel item inner
.dw-v	-	Valid item
-	.mbsc-sc-itm-inv	Invalid item
.dw-sel	.mbsc-sc-itm-sel	Selected wheel item
.dw-ml .dw-li	.mbsc-sc-itm-ml	Multiline item
.dw-hl	.mbsc-sc-itm.mbsc-btn-a	Active (tapped) wheel item
.dwwb	.mbsc-sc-btn	Clickpick button
.dwwb.dwb-a	.mbsc-sc-btn-a	Active clickpick button
.dwwbp	.mbsc-sc-btn-plus	Clickpick plus button
.dwwbm	.mbsc-sc-btn-minus	Clickpick minus button

Select

Old CSS class	New CSS class	Element
.dw-hsel	.mbsc-sel-hdn	Hidden select element
.dw-w-gr	.mbsc-sel-gr	Select group header
.dwwms	.mbsc-sc-whl-multi	Wheel with multiple select
.dw-msel	.mbsc-sc-itm-sel	Selected wheel item

Using Mobiscroll with Zepto or App Framework

In Mobiscroll 2.x we provided extensions for Zepto and App Framework, making possible to use with those libraries instead of jQuery.

In Mobiscroll 3.x, since jQuery no longer is a dependency, we also don't provide extensions for Zepto and App Framework, because the plain javascript version of Mobiscroll can be used. See the next section on how to migrate to the plain javascript version of Mobiscroll.

Using Mobiscroll without jQuery

If you are using Mobiscroll integrations with frameworks which do not require jQuery (Angular or Knockout), the usage remains the same, you just need to check for the breaking changes listed above.

Starting from Mobiscroll 3.0 jQuery is no longer a dependency. If you were using the jQuery version of Mobiscroll, you can migrate to the Javascript version in a few easy steps.

1. Download the Javascript version of Mobiscroll

When downloading Mobiscroll, make sure you select "Javascript" at the Framework section.

2. Initialization

Since Mobiscroll 2.x. used the jQuery Plugin syntax to initialize the components, the non-jQuery version initialization is slightly different.

The first parameter of the initialization function defines the element(s) on which Mobiscroll should be initialized. It can be a CSS selector string, or a DOM element.

Old code

// Mobiscroll 2.x

// Initialization on one element
$('#mydate').mobiscroll().date({
    theme: 'mobiscroll',
    display: 'bottom'
});

// Initialization on multiple elements
$('.my-dates').mobiscroll().date({
    theme: 'mobiscroll',
    display: 'bottom'
});

New code

// Mobiscroll 3.x

// Initialization on one element
mobiscroll.date('#mydate', {
    theme: 'mobiscroll',
    display: 'bottom'
});

// Initialization on multiple elements
mobiscroll.date('.my-dates', {
    theme: 'mobiscroll',
    display: 'bottom'
});

3. Getting the instance

In the Javascript version you have the reference to the instance returned on initialization.

If a DOM element is passed, or the selector string matches only one element, the initialization returns the single instance, otherwise returns an object with all the instances, the keys being the ids of the matched elements.

HTML

<input id="mydate" />
<input id="mydate1" class="my-dates" />
<input id="mydate2" class="my-dates" />

Old code

// Mobiscroll 2.x

// Single instance initialization
$('#mydate').mobiscroll().date();
var dateInstance = $('#mydate').mobiscroll('getInst');

// Mulitple instances initialization
$('.my-dates').mobiscroll().date();
var dateInstance1 = $('.my-dates').eq(0).mobiscroll('getInst');
var dateInstance2 = $('.my-dates').eq(1).mobiscroll('getInst');

New code

// Mobiscroll 3.x

// Single instance initialization
var dateInstance = mobiscroll.date('#mydate');

// Mulitple instances initialization
var dateInstances = mobiscroll.date('.my-dates');
var dateInstance1 = dateInstances.mydate1;
var dateInstance2 = dateInstances.mydate2;

4. Method calls

In Mobiscroll 2.x methods can be called in the jQuery plugin way.

In Mobiscroll 3.x methods can be called only through the instance.

Old code

// Mobiscroll 2.x
$('#mydate').mobiscroll().date({
    theme: 'mobiscroll',
    display: 'bottom'
});

$('#mydate').mobiscroll('show');

New code

// Mobiscroll 3.x
var dateInstance = mobiscroll.date('#mydate', {
    theme: 'mobiscroll',
    display: 'bottom'
});

dateInstance.show();

5. Utility functions

In Mobiscroll 2.x. the utility functions were inside the $.mobiscroll object. Since jQuery is no longer required, the functions are moved in the mobiscroll.util object.

Old code

// Mobiscroll 2.x
$.mobiscroll.datetime.formatDate('mm/dd/yy', new Date());

New code

// Mobiscroll 3.x
mobiscroll.util.datetime.formatDate('mm/dd/yy', new Date());

Scheduling & calendaring

Date & time picking

Mobile UI Patterns

Docs

Community Forum

Knowledge base

Customers

Blog

Scheduling & calendaring

Date & time picking

Mobile UI Patterns

Docs

Community Forum

Knowledge base

Customers

Blog

Mobiscroll 3.0 Upgrade Guide

Overview

Browser support

New way of passing event arguments

Removed component names

Removed functionality

Calendar

Removed methods

Removed options

General

Scroller based components

Calendar

Range

Timer

Changed methods

Scroller

Changed options

General

Scroller based components

Scroller

Calendar

Calendar, Date & Time

Listview

Measurements

Numpad

Select

Timespan

Changed events

General

Scroller based components

Measurement changes

Utility functions moved

Removed theme names

Removed themes

Bootstrap theme

jQuery Mobile theme

The mobiscroll global variable

Changed css classes

Popup

Scroller

Select

Using Mobiscroll with Zepto or App Framework

Using Mobiscroll without jQuery

1. Download the Javascript version of Mobiscroll

2. Initialization

3. Getting the instance

4. Method calls

5. Utility functions

The `mobiscroll` global variable