Contents

Mobiscroll 3.0 Upgrade Guide

Overview

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. Mobiscroll 2.x will be still maintained, but new features won't be introduced.

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:

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

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 Javascript
$('#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
mobiscroll.eventcalendar('#events', {
    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

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

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:

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:

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());