Mobiscroll 2.2.0 Documentation

Last updated Wednesday, November 22, 2012

Welcome to the Mobiscroll API Reference. You can find the most up to date information about usage and customization options here.

Requires jQuery >= 1.6, Zepto.js >= 1.0rc1 or jqMobi >= 1.0.3

Starting from version 2.0rc2 the 'preset' option no longer defaults to 'date'. If you want to use the date preset, you must explicitly specify. 'ampm' and 'seconds' options were also removed. Use the timeWheels option instead

Having trouble? Ask for help.


Mobiscroll Core Documentation

These are the core functions, options, events and methods that are available, if they are not overriden by a preset implementation.

Utility functions

Name Parameters Description
setDefaults function(settings) Set settings for all scroller instances

Options

Options for controlling the modal dialog button labels and header text.

Name Type Default value Description
cancelText String 'Cancel' Text for Cancel button
setText String 'Set' Text for Set button
headerText Mixed '{value}' Specifies a custom string which appears in the popup header. If the string contains '{value}' substring, it is replaced with the formatted value of the scroller. If it's set to false, the header is hidden. If a function is passed, it receives the formatted value as parameter and the returned value appears in the header
lang String 'en-US' Language of the scroller. Based on the language string the scroller loads the language based default settings from the language modules.
Name Type Default value Description
anchor jQuery Object undefined Specifies the anchor element for positioning, if 'display' is set to 'bubble'. If undefined, it defaults to the element on which the scroller was called.
animate String undefined Animation to use for show/hide (if display is not inline). Possible values:
  • 'fade'
  • 'flip'
  • 'pop'
  • 'swing'
  • 'slidevertical'
  • 'slidehorizontal'
  • 'slidedown'
  • 'slideup'
Requires the animation plugin.
delay Integer 300 Specifies the speed in milliseconds to change values in clickpick mode with tap & hold
disabled Boolean false Disables (true) or enables (false) the scroller. Can be set when initialising the scroller
display String 'modal' Controls the positioning of the scroller. Possible options:
  • 'modal' - Scroller appears as a popup at the center of the viewport.
  • 'inline' - If called on div element, scroller is placed inside the div (overwriting existing content), otherwise is placed after the original element.
  • 'bubble' - Scroller appears as a bubble positioned to the element defined by the 'anchor' setting. By default the anchor is the original element.
  • 'top' - Scroller appears docked to the top of the viewport.
  • 'bottom' - Scroller appears docked to the bottom of the viewport.
height Number 40 Height in pixels of one row on the wheel
mode String 'scroller' Option to choose between modes. Possible modes: 'scroller' - standard behaviour, 'clickpick' - '+' and '-' buttons
preset String '' Preset configurations for date, time and datetime pickers or select replacement, possible values: 'date', 'time', 'datetime', 'select', 'rating'. It is possible to write custom presets.
scrollLock Boolean true Disables page scrolling on touchmove (if not in inline mode)
At the time of 2.1-beta on Android 2.3 fast touchmoves sometimes causes pagescroll which may cause that the scroller gets out of the viewport.
readonly Boolean or Array of Booleans false If true, the scroller is displayed, but wheels are not moveable. If an array, it can be specified as a per wheel configuration, e.g. for 3 wheels: [true, false, false] - disables the first wheel.
rows Number 3 Number of visible rows on the wheel
showLabel Boolean true Show/hide labels above wheels
showOnFocus Boolean true Pops up the scroller on input focus
theme String '' Sets the scroller's visual appearance. Supplied themes:
  • 'android' - Android 2.x theme
  • 'android-ics' - Android 4.x theme
  • 'android-ics light' - Android 4.x theme (light version)
  • 'ios' - iOS theme
  • 'jqm' - Integrates with jQuery Mobile look & feel
  • 'sense-ui' - HTC Android Sense UI theme
  • 'wp' - Windows Phone Metro UI theme
  • 'wp light' - Windows Phone Metro UI theme (light version)
It's possible to create custom themes in css by prefixing any css class used in the scroller markup with the theme name, e.g.: .my-theme .dww { / My CSS / }, and set the theme option to 'my-theme'
wheels Object [] Wheels configuration. Example: [ { 'Label 1': { x: 'x', y: 'y', z: 'z' }, 'Label 2': { a: 'a', b: 'b' } }, { 'Label 3': { 1: '1', 2: '2' }, 'Label 4': { 4: '4', 5: '5' } } ]
width Number 80 Minimum width in pixels of the wheels, expand to fit values and labels

Events

Name Parameters Description
formatResult function(data) Receives selected scroller values as an array and must return a string to set as the value of the input element. By default it concatenates the values to a string, or, if a preset is selected, formats the date/time according to dateFormat/timeFormat option
onCancel function(valueText, inst) Allows you to define your own event when cancel is pressed. The function receives the selected value as text and the scroller instance as parameters
onChange function(valueText, inst) Allows you to define your own event when a wheel value is changed. The function receives the selected value as text and the scroller instance as parameters
onClose function(valueText, inst) Allows you to define your own event when the scroller is closed. The function receives the selected value as text and the scroller instance as parameters. If returns false, close is prevented
onSelect function(valueText, inst) Allows you to define your own event when a scroller value is set. The function receives the selected value as text and the scroller instance as parameters
onShow function(html, inst) Gets called when the scroller appears. The function receives the jQuery object containing the generated html and the scroller instance as parameters
parseValue function(valueText) Receives a string as parameter and must return an array which represents the selected scroller values.
validate function(html, index, time) Gets called on initialization and on every wheel change, can be used to validate the selected values. Has 3 parameters: html - jQuery object containing the generated html, index - index of the changed wheel (undefined on initial call), time - animation time of the wheel (if wheel is still moving)

Methods

Name Parameters Description
destroy .scroller('destroy') Remove the scroller functionality completely. This will return the element back to its pre-init state
disable .scroller('disable') Disable the scroller
enable .scroller('enable') Enable the scroller
getValue .scroller('getValue') Returns the selected scroller values as an array
hide .scroller('hide') Hide the scroller
isDisabled .scroller('isDisabled') Determine whether a scroller has been disabled.
option .scroller('option', optionName, value) or .scroller('option', options) Set scroller options
setValue .scroller('setValue', data, fill, time) Sets the scroller values from the data parameter passed as array. If the 'fill' parameter is true, the associated input field is also updated with the new value. The 'time' parameter specifies the duration of the animation in seconds to scroll the wheels to the new values. There is no animation, if 'time' is not specified
show .scroller('show') Show the scroller