Contents

Numpad

Basic usage

Javascript
// create a numpad control
mobiscroll.numpad('#numpad', { 
    theme: 'ios', 
    preset: 'timespan'
});
HTML
<input id="numpad"/>

Options

Name Type Default value Description
allowLeadingZero Boolean false If true, allows value to start with zero.
anchor String or HTMLElement undefined Specifies the anchor element for positioning, if display is set to 'bubble'. If undefined, it defaults to the element on which the component was initialized.
animate String or Boolean undefined Animation to use for show/hide (if display is not inline). Possible values:
  • 'fade'
  • 'flip'
  • 'pop'
  • 'swing'
  • 'slidevertical'
  • 'slidehorizontal'
  • 'slidedown'
  • 'slideup'
If false, turns the animation off.
buttons Array ['set', 'cancel'] Buttons to display. Each item in the array will be a button. A button can be specified as a string, or as a button object.

If a string, it must be one of the predifined buttons:
  • 'set' - Sets the value.
  • 'clear' - Clears the value.
  • 'cancel' - Dismisses the popup.
To modify the text of the predfined buttons, you can use the setText, clearText , cancelText settings.

If an object, it may have the following properties:
  • text String - Text of the button.
  • handler String, Function - The function which will run when the button is pressed. If a string, it must be one of the predefined button handlers:
    • 'set' - Sets the value.
    • 'clear' - Clears the value.
    • 'cancel' - Dismisses the popup.
  • icon String (Optional) - Icon of the button.
  • cssClass String (Optional) - Css class of the button.
Predefined and custom buttons example
buttons: [ 
    'set',
    { 
        text: 'Custom',
        icon: 'checkmark',
        cssClass: 'my-btn', 
        handler: function (event, inst) { 
            alert('Custom button clicked!'); 
        } 
    },
    'cancel'
]
Predefined button handler example
buttons: [
    'set',
    { 
        text: 'Hide',
        handler: 'cancel',
        icon: 'close',
        cssClass: 'my-btn'
    }
]
closeOnOverlayTap Boolean true If true, the popup is closed on overlay tap/click.
context String or HTMLElement 'body' Context in which mobiscroll is appended and positioned (if not inline). Can be a selector string or a DOM element.
cssClass String undefined Applies custom css class to highest level element.
deleteIcon String 'backspace' Delete icon.
disabled Boolean false Initial disabled state of the component.
display String 'center' Controls the positioning of the component. Possible options:
  • 'center' - The component appears as a popup at the center of the viewport.
  • 'inline' - If called on div element, the component is placed inside the div (overwriting existing content), otherwise is placed after the original element.
  • 'bubble' - The component appears as a bubble positioned to the element defined by the 'anchor' setting. By default the anchor is the original element.
  • 'top' - The component appears docked to the top of the viewport.
  • 'bottom' - The component appears docked to the bottom of the viewport.
fill String 'rtl' Direction of filling the values into the template. Possible options:
  • 'rtl' - Right to left
  • 'ltr' - Left to right
focusOnClose Boolean, String or jQuery Object true Element to focus after the popup is closed. If undefined, the original element will be focused. If false, no focusing will occur.
focusTrap Boolean true If not in inline mode, focus won't be allowed to leave the popup.
headerText Mixed false Specifies a custom string which appears in the popup header.
If the string contains the '{value}' substring, it is replaced with the formatted value of the numpad.
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.
The default value depends on the theme:

Mobiscroll: false
Android Holo: {value}
Bootstrap: {value}
iOS: false
jQuery Mobile: {value}
Material: false
Windows Phone: false
layout String undefined Sets the layout of the component. Possible values:
  • 'liquid' - Wheels will expand to the maximum available width, but will not exceed the width set by the maxWidth setting. If maxWidth is not specified, the total width of all wheels will not exceed 600px. In 'top' or 'bottom' display mode this is the default behavior.
  • 'fixed' or undefined - Wheels will expand to the size of the longest wheel value, but will not exceed the width set by the maxWidth setting.
leftKey Object undefined Defines a custom key on the left side of the 0.

The object has the following properties:
  • text - The text of the button.
  • value - One or more digit values which will be filled into the template when pressed, e.g. '00', or '30'.
  • variable - Specifies a value for a variable present in the template in '{variable}:{value}' format, e.g. 'ampm:AM'.
A sample custom key object:
leftKey: {
    text: 'AM',
    variable: 'ampm:AM',
    value: '00'
}
When pressed, the {ampm} variable in the template will display the 'AM' value, and 2 zeroes will be filled into the template (if enough place left).
mask String undefined If specified, the mask character will be displayed instead of the entered numbers.
placeholder String '0' Default character to fill the template's digit values.
preset String undefined Load preset configurations. Availaible presets:
If no preset is specified, the parseValue and formatValue conversion functions must be specified to define a custom behavior.
rightKey Object undefined Defines a custom key on the right side of the 0.

The object has the following properties:
  • text - The text of the button.
  • value - One or more digit values which will be filled into the template when pressed, e.g. '00', or '30'.
  • variable - Specifies a value for a variable present in the template in '{variable}:{value}' format, e.g. 'ampm:PM'.
A sample custom key object:
rightKey: {
    text: 'PM',
    variable: 'ampm:PM',
    value: '00'
}
When pressed, the {ampm} variable in the template will display the 'PM' value, and 2 zeroes will be filled into the template (if enough place left).
showOnFocus Boolean false Pops up the component on element focus.
showOnTap Boolean true Pops up the component on element tap.
template String 'dd.dd' Template for the numpad value. 'd' stands for digit, and will be filled with the values entered on the numpad keys.
Can contain variables as well, in a format of alphanumeric strings in braces. Optionally a placeholder can also be specified after a ':' character. E.g. 'dd:dd {ampm}' (without placeholder) or 'dd:dd {ampm:--}' (with placeholder).
The variables can be filled using custom buttons.

Any other character in the template will be handled as literal string. HTML markup is also accepeted.

If a preset is specified, the template will be generated by the preset.
theme String undefined Sets the visual appearance of the component.

If it is 'auto' or 'undefined', the theme will automatically be chosen based on the platform. If the theme for the specific platform is not present, it will revert to the Mobiscroll theme.

Supplied themes:
  • 'android-holo' - Android 4.x theme
  • 'android-holo-light' - Android 4.x theme (light version)
  • 'bootstrap' - Bootstrap themes
  • 'ios' - new iOS 7, 8, 9 theme
  • 'material' - Material theme (Android 5.x)
  • 'material-dark' - Material dark theme (Android 5.x)
  • 'jqm' - Integrates with jQuery Mobile look & feel
  • 'mobiscroll' - Mobiscroll theme
  • 'mobiscroll-dark' - Mobiscroll Dark 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 numpad markup with the theme name and the 'mbsc' prefix, e.g.: .mbsc-my-theme .dwwr { /* My CSS */ }, and set the theme option to 'my-theme'
Make sure that the theme you set is included in the downloaded package.

Setting options runtime (changing options dynamically)

There are two ways to modify options after initalization

  1. Using the option method.

    The option method always triggers reinitialization. Most of the settings can be updated only this way, updating without initialization has no effect, because the markup is already generated. If the scroller was visible, the reinitialization hides it and it's not shown again automatically (except in inline display mode).

    Javascript
    // Modify options
    mobiscrollInstance.option({ 
        theme: 'ios', 
        lang: 'de'
    });
    HTML
    <input id="mobiscroll"/>
  2. Modify directly the settings object.

    Useful when changing dynamic settings, which do not need redraw (e.g. readonly, calendar marked days).

    // Modify a setting
    mobiscrollInstance.settings.readonly = true;
    
    // Modify settings in an event
    mobiscroll.numpad('#mobiscroll', {
        onBeforeShow: function (event, inst) {
            inst.settings.readonly = true;
        }
    });

Events

Name Description
onBeforeClose(event, inst) Triggered before the component closes. Close can be prevented by returning false from the handler function.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
    • button: String - The name of the button which triggered the component to close ('set', or 'cancel').
  • inst: Object - The instance object of the numpad.

Example

mobiscroll.numpad('#mobiscroll', {
    onBeforeClose: function (event, inst) {
    }
});
onBeforeShow(event, inst) Triggered before the component is shown. It is useful if you want to modify the settings object before generating the markup. It can be used also to prevent the showing the control by returning false.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the numpad.

Example

mobiscroll.numpad('#mobiscroll', {
    onBeforeShow: function (event, inst) {
    }
});
onCancel(event, inst) Allows you to define your own event when cancel is pressed.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the numpad.

Example

mobiscroll.numpad('#mobiscroll', {
    onCancel: function (event, inst) {
    }
});
onClear(event, inst) Triggered when the value is cleared.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the numpad.

Example

mobiscroll.numpad('#mobiscroll', {
    onClear: function (event, inst) {
    }
});
onClose(event, inst) Triggered when the component is closed.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the numpad.

Example

mobiscroll.numpad('#mobiscroll', {
    onClose: function (event, inst) {
    }
});
onDestroy(event, inst) Triggered when the component is destroyed.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the numpad.

Example

mobiscroll.numpad('#mobiscroll', {
    onDestroy: function (event, inst) {
    }
});
onInit(event, inst) Triggered when the component is initialized.

Parameters

  • event: Object - The event object.
  • inst: Object - The instance object of the numpad.

Example

mobiscroll.numpad('#mobiscroll', {
    onInit: function (event, inst) {
    }
});
onMarkupReady(event, inst) Triggered when the html markup of the component is generated, but it is not yet shown. It is useful, if you want to make modifications to the markup (e.g. add custom elements), before the positioning runs.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
  • inst: Object - The instance object of the numpad.

Example

mobiscroll.numpad('#mobiscroll', {
    onMarkupReady: function (event, inst) {
    }
});
onPosition(event, inst) Triggered when the component is positioned (on initial show and resize / orientation change).

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
    • windowWidth: Number - The window width.
    • windowHeight: Number - The window height.
  • inst: Object - The instance object of the numpad.

Example

mobiscroll.numpad('#mobiscroll', {
    onPosition: function (event, inst) {
    }
});
onSet(event, inst) Triggered when a value is set.

Parameters

  • event: Object - The event object has the following properties:
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the numpad.

Example

mobiscroll.numpad('#mobiscroll', {
    onSet: function (event, inst) {
    }
});
onShow(event, inst) Triggered when the component is shown.

Parameters

  • event: Object - The event object has the following properties:
    • target: Object - The DOM element containing the generated html.
    • valueText: String - The selected value as text.
  • inst: Object - The instance object of the numpad.

Example

mobiscroll.numpad('#mobiscroll', {
    onShow: function (event, inst) {
    }
});
validate(data, inst) Gets called on initialization and on every button tap, can be used to validate the selected values.

Parameters

  • data: Object - The data object has the following properties:
    • values: Array - An array containing the currently entered digits.
    • variables: Object - An object containing the currently entered variables.
  • inst: Object - The instance object of the numpad.
Can return an object with the following properties:
  • disabled: Array - An array containing the digits that should be disabled.
  • invalid: Boolean - If true, the component state will be invalid, so the value will not be selected. The set button will be also disabled, if present.

Example

mobiscroll.numpad('#mobiscroll', {
    validate: function (data, inst) {
    }
});

Methods

Name Description
cancel() Hides the numpad and also invokes the onCancel event.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.cancel();
clear() Clears the numpad value.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.clear();
disable() Disables the numpad.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.disable();
enable() Enables the numpad.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.enable();
getArrayVal([temp]) Returns the selected wheel values as an array of digits.

Parameters

  • temp (Optional): Boolean - If true, temporary values are returned (prior clicking the Set button).

Returns: Array

  • An array containing the selected wheel values.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.getArrayVal();
getInst() Returns the object instance.

Returns: Object

  • The object instance.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.getInst();
getVal([temp]) Returns the selected numpad value.

Parameters

  • temp (Optional): Boolean - If true, returns the temporary values (prior clicking the Set button).

Returns: String

  • The selected numpad value.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.getVal();
hide([ prevAnim ] [, btn ]) Hides the component.

Parameters

  • prevAnim (Optional): Boolean - If true, hide will not be animated.
  • btn (Optional): String - Specifies which button caused the component to hide, and it's passed to the onBeforeClose event.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.hide();
isVisible() Returns a boolean indicating whether the component is visible or not.

Returns: Boolean

  • True if the component is visible, false if it's not.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.isVisible();
option(options) Sets one or more options for the component.

Parameters

  • options: Object - A map of option-value pairs to set.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.option({
    display: 'bottom',
    lang: 'de'
});
position([check]) Recalculates the position of the component (if not inline).

Parameters

  • check (Optional): Boolean - If true, the function checks if viewport size changed after last position call, if false or ommitted, position is recalculated anyway.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.position();
select() Hides the numpad and also invokes the onSelect event.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.select();
setArrayVal (values [, fill ] [, change ] [, temp ] [, time ]) Sets the numpad wheel values from the values parameter passed as array.

Parameters

  • values: Array - An array containing the wheel values.
  • fill (Optional): Boolean - If true, the associated input element is also updated with the new value.
  • change (Optional): Boolean - If false, change event won't be triggered on the input element.
  • temp (Optional): Boolean - If true, only temporary values are set.
  • time (Optional): Number - Specifies the duration of the animation in seconds to scroll the wheels to the new values. There is no animation, if time is omitted or 0.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.setArrayVal([4, 5]);
setVal(value [, fill ] [, change ] [, temp ] [, time ]) Sets the numpad value.

Parameters

  • value: String - The numpad value.
  • fill (Optional): Boolean - If true, the associated input element is also updated with the new value.
  • change (Optional): Boolean - If false, change event won't be triggered on the input element.
  • temp (Optional): Boolean - If true, only temporary value is set.
  • time (Optional): Number - Specifies the duration of the animation in seconds to scroll the wheels to the new values. There is no animation, if time is omitted or 0.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.setVal('9.25');
show([ prevAnim ] [, prevFocus ]) Shows the component.

Parameters

  • prevAnim (Optional): Boolean - If true, show will not be animated.
  • prevFocus (Optional): Boolean - If true, the popup will not be focused right after show.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.show();
tap(el, handler) Attaches the handler function to the tap event of element el.

Parameters

  • el: Object - The element with tap event.
  • handler: Function - If the action was initiated with touch event, handler is called on touchend, otherwise on click.

Example

Methods can be called on an instance. For more details see calling methods
mobiscrollInstance.tap('#element', function () { alert("It's a tap!"); });

Localization

Name Type Default value Description
cancelText String 'Cancel' Text for Cancel button.
clearText String 'Clear' Text for Clear button.
lang String 'en-US' Language of the component. Based on the language string the component loads the language based default settings from the language modules.
Supported languages:
  • 'en' or 'en-US' or undefined - English
  • 'en-UK' or 'en-GB' - English (UK)
  • 'cs' - Czech
  • 'zh' - Chinese
  • 'da' - Danish
  • 'de' - German
  • 'es' - Spanish
  • 'fa' - Farsi
  • 'fr' - French
  • 'it' - Italian
  • 'ja' - Japanese
  • 'hu' - Hungarian
  • 'nl' - Dutch
  • 'no' - Norwegian
  • 'pl' - Polish
  • 'pt-BR' - Brazilian Portuguese
  • 'pt-PT' - European Portuguese
  • 'ro' - Romanian
  • 'ru' - Russian
  • 'ru-UA' - Russian (UA)
  • 'sk' - Slovak
  • 'sv' - Swedish
  • 'tr' - Turkish
rtl Boolean false Right to left display.
setText String 'Set' Text for Set button.

Presets

Decimal

Name Type Default value Description
decimalSeparator String '.' Separates the integer part from the fractional part of the numeric value.
defaultValue Number 0 Initial value.
invalid Array undefined Array of numbers which values are unselectable.
scale Number 2 Number of decimal places (precision).
min Number 0 Minimum selectable value.
max Number 99.99 Maximum selectable value.
prefix String '' Prefix for the numeric value, e.g. '$'.
returnAffix Boolean false If true, the formatted value will also contain the prefix and suffix, otherwise the number only.
suffix String '' Suffix for the numeric value, e.g. '€'.
thousandsSeparator String ',' The character displayed at each separation of the numeric value.

Timespan

Name Type Default value Description
defaultValue Number 0 Initial value.
invalid Array undefined Array of numbers(seconds) which values are unselectable.
min Number 0 Minimum selectable value (in seconds).
max Number 362439 Maximum selectable value (in seconds).

Time

Name Type Default value Description
defaultValue String undefined Initial value.
invalid Array undefined Array of dates which values are unselectable.
max Date undefined Maximum time that can be selected
min Date undefined Minimum time that can be selected
timeFormat String 'hh:ii A' The format for parsed and displayed times
  • hh - hour format
  • ii - minutes
  • ss - seconds
  • a - lowercase am/pm - if peresent the time will be 12 hour format
  • A - uppercase AM/PM - if peresent the time will be 12 hour format

Date

Name Type Default value Description
dateFormat String 'mm/dd/yy' The format for parsed and displayed dates
  • m - month of year (no leading zero)
  • mm - month of year (two digit)
  • M - month name short
  • MM - month name long
  • d - day of month (no leading zero)
  • dd - day of month (two digit)
  • D - day of week (short)
  • DD - day of week (long)
  • y - year (two digit)
  • yy - year (four digit)
  • '...' - literal text
  • '' - single quote
  • anything else - literal text
dateOrder String 'mdy' The order of year, month and day of the date displayed on the picker.
delimiter String '/' Character between year, month and day values of the date displayed on the picker.
defaultValue String undefined Initial value.
invalid Array undefined Array of dates that can't be selected.
max Date undefined Maximum date that can be selected
min Date undefined Minimum date that can be selected
Preorder available for Ember JS
What you'll get:
- Exclusive Early Beta Access
- Show your interest in the product. Based on the preorders we'll set the development and shipping priorities
- Get access to the full Framework until we ship
- Support and Maintenance is on us until we release the Mobiscroll for Ember
- We believe in delivering great products so if for any reason you are not satisfied, you'll get a full refund