General Date & Time pickers Event Calendar Form components Gesture enabled responsive list Numeric pickers Pickers & dropdowns Page layout & navigation Tools Accessibility

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.

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 JQuery
$('#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 programatically, 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());