A jQuery plugin that attaches a popup keyboard to a text field for mouse-driven entry or adds an inline keypad in a division or span. If you find this plugin useful please vote for it on the jQuery site.
This page provides a documentation reference for working with the plugin v1.2.2. See a demonstration of the keypad plugin and download the code from there. Or see a minimal page that you could use as a basis for your own investigations.
Customise each targetted field with the settings below (all are optional):
$(selector).keypad({randomiseNumeric: true});.
appendText | beforeShow | buttonImage | buttonImageOnly | duration | keypadClass | keypadOnly | layout | onClose | onKeypress | prompt | randomiseAll | randomiseAlphabetic | randomiseNumeric | randomiseOther | separator | showAnim | showOn | showOptions| target
| Name | Type | Default | Comments |
|---|---|---|---|
| showOn | string | 'focus' | Control when the keypad is displayed: 'focus' for only on focus of the text field, 'button' for only on clicking the trigger button, or 'both' for either. |
| buttonImage | string | '' | The URL of an image to use for the trigger button. |
| buttonImageOnly | boolean | false | Set to true to indicate that the trigger image should appear by itself and not on a button. |
| showAnim | string | 'show' | Set which animation is used to display the keypad. Choose from three standard animations: 'show', 'fadeIn', or 'slideDown', or use one of the jQuery UI effects if you include that package. |
| showOptions | object | {} | If you use one of the jQuery UI effects for the animation above,
you can supply additional options for that effect via this setting.$(selector).keypad({showAnim: 'clip',
showOptions: {direction: 'horizontal'}}); |
| duration | string | 'normal' | Control the speed of the show/hide animation with this setting: 'slow', 'normal', 'fast', or a number of milliseconds. |
| appendText | string | '' | Text that is to be appended to all affected fields, perhaps to describe the presence or purpose of the keypad. |
| keypadClass | string | '' | One popup keypad is shared by all instances, so this setting allows you to apply different CSS styling by adding an extra class to the keypad for each instance. |
| prompt | string | '' | Text that is displayed at the top of the keypad. The value may include HTML markup. |
| layout | string[] | ['123' + this.CLOSE, '456' + this.CLEAR, '789' + this.BACK, this.SPACE + '0'] |
Set the layout of the keypad by defining the characters present on each row.
All alphabetic characters should be in lower case.
Make use of the keypad constants to add special features into the layout:
Since 1.2.0 - added SPACE_BAR. |
| separator | string | '' | The character that separates the text content of the keys,
used in conjunction with the layout setting.
By default it is blank, so each key contains only one character.$(selector).keypad({separator: '|', layout:
['ACT|NSW|NT', 'QLD|SA|TAS', 'VIC|WA']});Since 1.2.0. |
| target | element or jQuery or string | null | When using an inline keypad you can set this field to an input field
to have the keypad update it automatically. The value can be either the element
itself, a jQuery wrapper around the element, or the jQuery selector for it.
When null use the onKeypress
callback instead.Since 1.2.1. |
| keypadOnly | boolean | true | Set to true to indicate that only the keypad can be used to enter text, or false to allow normal entry as well. This option does not apply to inline keypads. |
| randomiseAlphabetic | boolean | false | Set to true to indicate that the alphabetic characters in the layout
should be randomised for each display. The isAlphabetic
setting determines which characters are alphabetic. |
| randomiseNumeric | boolean | false | Set to true to indicate that the numeric characters in the layout
should be randomised for each display. The isNumeric
setting determines which characters are numeric. |
| randomiseOther | boolean | false | Set to true to indicate that the non-alphanumeric characters in the layout should be randomised for each display. |
| randomiseAll | boolean | false | Set to true to indicate that all characters in the
layout should be randomised for each display.
When true, this setting overrides the other randomise settings. Since 1.0.2. |
| beforeShow | function | null | A function that is called after the keypad is constructed but before it is displayed,
allowing you to update it. For example, you could add extra buttons that
perform tasks outside the scope of the normal keypad.
The function receives the division to be displayed and the keypad instance
object as parameters, while this refers to the text field.$(selector).keypad({
beforeShow: function(div, inst) {
$('<button id="clickMe" class="keypad-key">'+
'Click me</button>').
appendTo(div).
click(function() {
alert('Clicked');
});
}
});Since 1.2.0. |
| onKeypress | function | null | A function that is called when a key is pressed on the keypad.
The function receives the current key value ($.keypad.BS
for the Back key, $.keypad.DEL for the
Clear key, and '' for other control keys),
the full field value, and the keypad instance object
as parameters, while this refers to the text field.
Of course, you can still have an onchange handler
for the input field itself.$(selector).keypad({
onKeypress: function(key, value, inst) {
$('#keypress').text(key || ' ');
$('#current').text(value);
}
});Since 1.2.0 - added current key parameter. Since 1.2.1 - added $.keypad.BS and
$.keypad.DEL characters for Back and Clear keys. |
| onClose | function | null | A function that is called when the keypad is closed.
The function receives the current field value and the keypad instance object
as parameters, while this refers to the text field.$(selector).keypad({
onClose: function(value, inst) {
alert('Closed with value ' + value);
}
}); |
These settings comprise the
regional settings that may be localised by a
language package.
They can be overridden for individual instances:
$(selector).keypad({backText: 'BS'});
alphabeticLayout | backStatus | backText | buttonStatus | buttonText | clearStatus | clearText | closeStatus | closeText | fullLayout | isAlphabetic | isNumeric | isRTL | shiftStatus | shiftText
| Name | Type | Default | Comments |
|---|---|---|---|
| buttonText | string | '...' | The text to display on a trigger button for the keypad. |
| buttonStatus | string | 'Open the keypad' | The description of the button's purpose, used in a tool tip. |
| closeText | string | 'Close' | The text to display for the button to close the keypad. |
| closeStatus | string | 'Close the keypad' | The description of the close button's purpose, used in a tool tip. |
| clearText | string | 'Clear' | The text to display for the button to clear the text field. |
| clearStatus | string | 'Erase all the text' | The description of the clear button's purpose, used in a tool tip. |
| backText | string | 'Back' | The text to display for the button to erase the previous character. |
| backStatus | string | 'Erase the previous character' | The description of the back button's purpose, used in a tool tip. |
| shiftText | string | 'Shift' | The text to display for the button to shift between upper and lower case characters. |
| shiftStatus | string | 'Toggle upper/lower case characters' | The description of the shift button's purpose, used in a tool tip. |
| alphabeticLayout | string[] | $.keypad.qwertyAlphabetic | The layout for alphabetic keyboard characters in this language. |
| fullLayout | string[] | $.keypad.qwertyLayout | The layout for the full standard keyboard in this language. |
| isAlphabetic | function | $.keypad.isAlphabetic | A function to determine whether or not a character is alphabetic. The character to test is passed as the parameter and a boolean response is expected. The default accepts 'A' to 'Z' and 'a' to 'z'. |
| isNumeric | function | $.keypad.isNumeric | A function to determine whether or not a character is numeric. The character to test is passed as the parameter and a boolean response is expected. The default accepts '0' to '9'. |
| isRTL | boolean | false | Set to true to indicate that the current language flows right-to-left. |
| Name | Type | Default | Comments |
|---|---|---|---|
| regional | object[] | See regional settings | The set of regional settings for the keypad fields. Entries are indexed
by the country/region code with '' providing the default (English) settings.
Each entry is an object with the following properties:
buttonText,
buttonStatus,
closeText,
closeStatus,
clearText,
clearStatus,
backText,
backStatus,
shiftText,
shiftStatus,
alphabeticLayout,
fullLayout,
isAlphabetic,
isNumeric,
isRTL.
Language packages load new entries into this array and
automatically apply them as global defaults.<script type="text/javascript"
src="jquery.keypad-fr.js"></script>If necessary, you can then revert to the default language settings with $.keypad.setDefaults($.keypad.regional['']);and apply the language settings to individual fields with $('#frenchKeypad').keypad(
$.keypad.regional['fr']);.Check out the list of available localisation packages. |
| qwertyAlphabetic | string[] | ['qwertyuiop', 'asdfghjkl', 'zxcvbnm'] | The alphabetic character layout for the standard
Qwerty keyboard.
This is the default value for the
alphabeticLayout setting. |
| qwertyLayout | string[] | ['!@#$%^&*()_=' + HALF_SPACE + SPACE + CLOSE, HALF_SPACE + '`~[]{}<>\\|/' + SPACE + '789', 'qwertyuiop\'"' + HALF_SPACE + '456', HALF_SPACE + 'asdfghjkl;:' + SPACE + '123', SPACE + 'zxcvbnm,.?' + SPACE + HALF_SPACE + '-0+', SHIFT + SPACE + SPACE_BAR + SPACE + SPACE + HALF_SPACE + BACK + CLEAR] | The full keyboard layout for the standard
Qwerty keyboard.
This is the default value for the
fullLayout setting.Since 1.2.0 - reordered and space bar added. |
change | destroy | disable | enable | hide | insertValue | isAlphabetic | isDisabled | isNumeric | setDefaults | show
| Signature | Returns | Comments |
|---|---|---|
| $.keypad.setDefaults(settings) | Keypad object | Update the default instance settings to use with all keypad instances. |
| $(selector).keypad('change', settings) | jQuery object | Update the instance settings
for the keypad instance(s) attached to the given field(s).settings (object) is the collection of new settings. |
| $(selector).keypad('change', name, value) | jQuery object | Update a setting
for the keypad instance(s) attached to the given field(s).name (string) is the name of the setting,value (any) is the new value, or null to reset to the default. |
| $(selector).keypad('destroy') | jQuery object | Remove the keypad functionality from the given field(s). |
| $(selector).keypad('show') | jQuery object | Pop up the keypad for the given field. |
| $(selector).keypad('hide') | jQuery object | Hide the keypad for the given field. |
| $(selector).keypad('enable') | jQuery object | Enable the keypad for the given field(s) as well as the field itself. |
| $(selector).keypad('disable') | jQuery object | Disable the keypad for the given field(s) as well as the field itself. |
| $(selector).keypad('isDisabled') | boolean | Determine whether the keypad functionality has been disabled for the first of the given field(s). |
| $.keypad.isAlphabetic(ch) | boolean | Default test for English alphabetic characters.
See the
isAlphabetic setting. |
| $.keypad.isNumeric(ch) | boolean | Default test for English numeric characters.
See the
isNumeric setting. |
| $.keypad.insertValue(input, value) | - | Insert text into an input field at its current cursor position.
This replaces text if a selection has been made.input (jQuery or element) is the input field,value (string) is the text to insert.Since 1.2.2. |
Contact Keith Wood at kbwood{at}iinet.com.au with comments or suggestions.