Instance Settings

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| useThemeRoller

NameTypeDefaultComments
showOnstring'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.
buttonImagestring'' The URL of an image to use for the trigger button.
buttonImageOnlybooleanfalse Set to true to indicate that the trigger image should appear by itself and not on a button.
showAnimstring'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. For no animation use ''.

Since 1.2.3 - use '' for no animation.
showOptionsobjectnull 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'}});
durationstring'normal' Control the speed of the show/hide animation with this setting: 'slow', 'normal', 'fast', or a number of milliseconds.
appendTextstring'' Text that is to be appended to all affected fields, perhaps to describe the presence or purpose of the keypad.
useThemeRollerbooleanfalse Set to true to add ThemeRoller classes to the keypad to allow the keypad to integrate with other UI components using a theme.

Since 1.3.0.
keypadClassstring'' 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.
promptstring'' Text that is displayed at the top of the keypad. The value may include HTML markup.
layoutstring[] $.keypad.numericLayout 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:

  • $.keypad.CLOSE - the button to close the keypad
  • $.keypad.CLEAR - the button to clear the input field
  • $.keypad.BACK - the button to erase the previous character
  • $.keypad.SHIFT - the button to toggle between upper/lower case characters
  • $.keypad.SPACE_BAR - an extended space character
  • $.keypad.ENTER - the button to add a carriage return
  • $.keypad.TAB - the button to add a tab character
  • $.keypad.SPACE - blank space equivalent to one key
  • $.keypad.HALF_SPACE - blank space equivalent to half a key

Use the regional settings to set what is shown for each of these buttons.

Since 1.2.0 - added SPACE_BAR.
Since 1.2.4 - added ENTER.
Since 1.4.0 - added TAB.
separatorstring'' 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.
targetelement or jQuery or stringnull 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.
keypadOnlybooleantrue 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.
randomiseAlphabeticbooleanfalse 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.
randomiseNumericbooleanfalse 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.
randomiseOtherbooleanfalse Set to true to indicate that the non-alphanumeric characters in the layout should be randomised for each display.
randomiseAllbooleanfalse 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.
beforeShowfunctionnull 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.
onKeypressfunctionnull 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.
onClosefunctionnull 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);
  }
});

Regional Settings

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 | enterStatus | enterText | fullLayout | isAlphabetic | isNumeric | isRTL | shiftStatus | shiftText | spacebarStatus | spacebarText | tabStatus | tabText | toUpper

NameTypeDefaultComments
buttonTextstring'...' The text to display on a trigger button for the keypad.
buttonStatusstring'Open the keypad' The description of the button's purpose, used in a tool tip.
closeTextstring'Close' The text to display for the button to close the keypad.
closeStatusstring'Close the keypad' The description of the close button's purpose, used in a tool tip.
clearTextstring'Clear' The text to display for the button to clear the text field.
clearStatusstring'Erase all the text' The description of the clear button's purpose, used in a tool tip.
backTextstring'Back' The text to display for the button to erase the previous character.
backStatusstring'Erase the previous character' The description of the back button's purpose, used in a tool tip.
spacebarTextstring'&#160;' The text to display for the extended button to add a space.

Since 1.4.0.
spacebarStatusstring'Space' The description of the space bar button's purpose, used in a tool tip.

Since 1.4.0.
enterTextstring'Enter' The text to display for the button to add a carriage return.

Since 1.2.4.
enterStatusstring'Carriage return' The description of the enter button's purpose, used in a tool tip.

Since 1.2.4.
tabTextstring'?' The text to display for the button to add a tab.

Since 1.4.0.
tabStatusstring'Horizontal tab' The description of the tab button's purpose, used in a tool tip.

Since 1.4.0.
shiftTextstring'Shift' The text to display for the button to shift between upper and lower case characters.
shiftStatusstring'Toggle upper/lower case characters' The description of the shift button's purpose, used in a tool tip.
alphabeticLayoutstring[] $.keypad.qwertyAlphabetic The layout for alphabetic keyboard characters in this language.
fullLayoutstring[] $.keypad.qwertyLayout The layout for the full standard keyboard in this language.
isAlphabeticfunction $.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'.
isNumericfunction $.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'.
toUpperfunction $.keypad.toUpper A function to convert a character into its upper case form. It accepts one parameter being the current character and returns the corresponding upper case character. The default uses the standard JavaScript toUpperCase function.
$(selector).keypad({layout: ['12345', $.keypad.SHIFT],
	toUpper: function(ch) {
		return {'1': '!', '2': '@', '3': '#', '4': '$', '5': '%'}[ch] || ch;
	}});
Since 1.5.0.
isRTLbooleanfalse Set to true to indicate that the current language flows right-to-left.

Global Settings

NameTypeDefaultComments
regionalOptionsobject[] 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 properties shown on the Regional tab. 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.regionalOptions['']);
and apply the language settings to individual fields with
$('#frenchKeypad').keypad($.keypad.regionalOptions['fr']);
Check out the list of available localisation packages.

Since 2.0.0 - previously called regional.
numericLayoutstring[]['123' + CLOSE,
'456' + CLEAR,
'789' + BACK,
SPACE + '0']		 The standard numeric button layout. This is the default value for the layout setting.

Since 2.0.0.
qwertyAlphabeticstring[]['qwertyuiop', 'asdfghjkl', 'zxcvbnm'] The alphabetic character layout for the standard Qwerty keyboard. This is the default value for the alphabeticLayout setting.
qwertyLayoutstring[]['!@#$%^&*()_=' + HALF_SPACE + SPACE + CLOSE, HALF_SPACE + '`~[]{}<>\\|/' + SPACE + '789', 'qwertyuiop\'"' + HALF_SPACE + '456', HALF_SPACE + 'asdfghjkl;:' + SPACE + '123', SPACE + 'zxcvbnm,.?' + SPACE + HALF_SPACE + '-0+', TAB + ENTER + SPACE_BAR + SHIFT + 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.
Since 1.2.4 - Enter added.
Since 1.4.0 - Tab added.

Functions

addKeyDef | destroy | disable | enable | hide | insertValue | isAlphabetic | isDisabled | isNumeric | option (get) | option (set) | setDefaults | show | toUpper

SignatureReturnsComments
$.keypad.addKeyDef(id, name, action, noHighlight) Keypad object Define a new action key for use on the keypad. Up to 32 keys may be defined, including the built-in ones.

id (string) is the name of the variable to use to include this key in a layout,

name (string) is the name used for a CSS styling class for the key (keypad-<name>) and for finding its display text (using <name>Text and <name>Status),

action (function) is the code to be run when the key is pressed, it receives the keypad instance as a parameter, while this refers to the attached input field,

noHighlight (boolean, optional) is true to suppress the highlight class when using ThemeRoller styling.
$.keypad.addKeyDef('UPPER', 'upper', function(inst) {
		this.val(this.val().toUpperCase()).focus();
	});
$('#keypad').keypad({upperText: 'U/C',
	upperStatus: 'Convert to upper case',
	layout: 'abc' + $.keypad.CLOSE,
		'def' + $.keypad.CLEAR,
		'ghi' + $.keypad.BACK,
		'jkl' + $.keypad.UPPER]});
Since 1.4.0.
$.keypad.setDefaults(settings)Keypad object Update the default instance settings to use with all keypad instances.
$(selector).keypad('option', options)jQuery object Update the settings for the keypad instance(s) attached to the given field(s).

options (object) the collection of new settings.
$(selector).keypad('option', {prompt: 'Keypad', keypadOnly: false});
Since 1.5.0 - previously you used the 'change' command.
$(selector).keypad('option', name, value)jQuery object Update a particular setting for the keypad instance(s) attached to the given field(s).

name (string) the name of the setting to change;
value (any) the new value of that setting.
$(selector).keypad('option', 'prompt', 'Keypad');
Since 1.5.0 - previously you used the 'change' command.
$(selector).keypad('option', name)object or any Retrieve one or all of the current settings for the first keypad instance attached to the given field(s).

name (string, optional) the name of the setting to retrieve; omit for all settings.
var settings = $(selector).keypad('option');
var prompt = $(selector).keypad('option', 'prompt');
Since 1.5.0.
$(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. Note that a field that is disabled when the keypad is applied to it causes the keypad to become disabled as well.

Since 1.3.0 - automatic disabling.
$(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 - accepting 'A' to 'Z' and 'a' to 'z'. See the isAlphabetic setting.
$.keypad.isNumeric(ch)boolean Default test for English numeric characters - accepting '0' to '9'. See the isNumeric setting.
$.keypad.toUpper(ch)string Convert a character into its upper case form - using the standard JavaScript toUpperCase function. See the toUpper setting.

Since 1.5.0.
$.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.