Mobiscroll 3.0 Upgrade Guide
Overview
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.
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:
// Mobiscroll 2.x
onEventSelect: function (e, event, date, inst) {
// Original 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
.
$('#range').mobiscroll().rangepicker({
// ...
});
$('#range').mobiscroll().range({
// ...
});
colorpicker
- Renamed to color
.
$('#color').mobiscroll().colorpicker({
// ...
});
$('#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
.
$('#events').mobiscroll().calendar({
events: [
// ...
]
});
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.
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 wastrue
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 theshowScrollArrows
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 tofalse
, 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 theevents
option instead. -
quickNav
- Iftrue
, 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 thedefaultValue
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 tocloseOnOverlayTap
.
Scroller based components
fixedWidth
- Usewidth
to set the fixed width of the wheels instead.width
- UseminWidth
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 thevalues
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 tosetOnDayTap
.divergentDayChange
- Renamed toouterMonthChange
.-
multiSelect
- Renamed toselect
to be consistent with other components. Possible values are'single'
and'multiple'
. navigation
- Renamed toyearChange
, withtrue
andfalse
as possible values.showDivergentDays
- Renamed toshowOuterDays
.swipeDirection
- Renamed tocalendarScroll
.
Calendar, Date & Time
-
dateOrder
- Renamed todateWheels
to be consistent with thetimeWheels
setting. -
minDate
- Renamed tomin
to be consistent with other components. -
maxDate
- Renamed tomax
to be consistent with other components.
Listview
altRow
- Renamed tostriped
.
Measurements
defUnit
- Renamed todefaultUnit
.
Numpad
leftButton
- Renamed toleftKey
.rightButton
- Renamed torightKey
.
Select
-
multiple
- Renamed toselect
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 tomin
to be consistent with other components. -
maxTime
- Renamed tomax
to be consistent with other components.
Changed events
General
-
onClose
- This event was deprecated in version 2.17.0, and theonBeforeClose
andonClosed
events were introduced instead. In 3.x theonClosed
event is renamed toonClose
.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 toonSet
, 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 toonItemTap
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'
Bootstrap theme
From Mobiscroll 3.0 the Bootstrap theme no longer supports Bootstrap 2.x, Bootstrap 3.x is required.
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.
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
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.
// 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'
});
// 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.
<input id="mydate" />
<input id="mydate1" class="my-dates" />
<input id="mydate2" class="my-dates" />
// 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');
// 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.
// Mobiscroll 2.x
$('#mydate').mobiscroll().date({
theme: 'mobiscroll',
display: 'bottom'
});
$('#mydate').mobiscroll('show');
// 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.
// Mobiscroll 2.x
$.mobiscroll.datetime.formatDate('mm/dd/yy', new Date());
// Mobiscroll 3.x
mobiscroll.util.datetime.formatDate('mm/dd/yy', new Date());