A jQuery plugin that attaches a popup calculator to an input field. 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.3.2. See a demonstration of the calculator 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).calculator({showOn: 'button'});appendText | base | buttonImage | buttonImageOnly | calculatorClass | constrainInput | cookieExpires | cookieName | cookiePath | duration | isOperator | layout | memoryAsCookie | onButton | onClose | onOpen | precision | prompt | showAnim | showOn | showOptions | useDegrees | useThemeRoller | value
| Name | Type | Default | Comments |
|---|---|---|---|
| showOn | string | 'focus' | Control when the calculator is displayed: 'focus' for only on focus of the text field,
'button' for only on clicking the trigger button, 'both' for either focus or the button,
'operator' for only when a non-numeric character is entered, or
'opbutton' for either non-numeric entry or a button. Since 1.1.1 - added 'operator' and 'opbutton'. |
| 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. |
| isOperator | function | null | A callback function to determine whether or not an entered character should
trigger display of the calculator in 'operator' or 'opbutton'
modes. The function is passed the character being typed,
the corresponding key event, the current value of the input field,
the current number base, and the current decimal character.
By default any non-numeric character is a trigger.
The example below only triggers on the basic maths operators.Since 1.2.3. |
| showAnim | string | 'show' | Set which animation is used to display the calculator. 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.4 - use '' for no animation. |
| 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. |
| 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 calculator. |
| useThemeRoller | boolean | false | Set to true to add ThemeRoller
classes to the keypad to allow the calculator to integrate with other UI
components using a theme. Since 1.3.0. |
| calculatorClass | string | '' | One popup calculator is shared by all instances, so this setting allows you to apply different CSS styling by adding an extra class to the calculator for each instance. |
| prompt | string | '' | Text that is displayed at the top of the calculator. |
| layout | string[] | this. standardLayout | Set the layout of the calculator by defining the keys present on each row. Use the two-character codes for each of the keys, or their equivalent constants. |
| value | number | 0 | The initial value shown in the calculator.
It only applies to inline calculators - popup calculators
take their initial value from their input field. Since 1.2.3. |
| base | number | 10 | The numeric base for values shown in the calculator. It should only be one of 2, 8, 10, or 16. Use the number base keys for controls to change this setting interactively. |
| precision | number | 10 | The number of digits of precision to use in rounding.
This value can resolve obvious rounding errors in JavaScript
(e.g. 2.1 * 7), but may then affect the accuracy of other calculations.
You need to strike a balance between these two requirements.
Note that this setting only affects the displayed value and that
the full value is retained in the calculator for further computations. Since 1.0.1. |
| memoryAsCookie | boolean | false | Set to true to indicate that the memory value should be saved as a cookie
and be re-initialised on page load, or false to just have it in-memory.
Use the following settings to fine tune the cookie. Since 1.3.2. |
| cookieName | string | 'calculatorMemory' | The name of the cookie to store when
memoryAsCookie is true. Since 1.3.2. |
| cookieExpires | number or Date | 24 * 60 * 60 | The expiry period for the cookie when
memoryAsCookie is true.
Specify as a Date or as the number of seconds offset
from now (default is one day). Since 1.3.2. |
| cookiePath | string | '' | The path of the cookie to store when
memoryAsCookie is true. Since 1.3.2. |
| useDegrees | boolean | false | Set to true to indicate that values are in degrees when using trigonometric functions, or false for radians (2π per circle). Use the degrees/radians keys for controls to change this setting interactively. |
| constrainInput | boolean | true | Indicate whether to restrict entry into the input field to numeric
values only (true) or to allow anything to be typed (false). Since 1.1.1. |
| onOpen | function | null | A function that is called before a popup calculator is opened.
The function receives the current field value and the calculator instance object
as parameters, while this refers to the text field.
The field value can be altered and will be used in the calculator.
Usually this function would be used in conjunction with the
onClose event.Since 1.2.5. |
| onButton | function | null | A function that is called when a button is activated on the calculator.
The function receives the button label, the current value,
and the calculator 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. |
| onClose | function | null | A function that is called when the calculator is closed.
The function receives the current field value and the calculator instance object
as parameters, while this refers to the text field. |
These settings comprise the regional settings that may be localised by a language package. They can be overridden for individual instances:
$(selector).calculator({useText: 'Save'});backspaceStatus | backspaceText | base10Status | base10Text | base16Status | base16Text | base2Status | base2Text | base8Status | base8Text | buttonStatus | buttonText | clearErrorStatus | clearErrorText | clearStatus | clearText | closeStatus | closeText | decimalChar | degreesStatus | degreesText | eraseStatus | eraseText | isRTL | memAddStatus | memAddText | memClearStatus | memClearText | memRecallStatus | memRecallText | memStoreStatus | memStoreText | memSubtractStatus | memSubtractText | radiansStatus | radiansText | useStatus | useText
| Name | Type | Default | Comments |
|---|---|---|---|
| regional | object[] | See regional settings | The set of regional settings for the calculator fields. Entries are indexed
by the country/region code with '' providing the default (English) settings.
Each entry is an object with the following
properties: decimalChar,
buttonText, buttonStatus, closeText,
closeStatus, useText, useStatus,
eraseText, eraseStatus, backspaceText,
backspaceStatus, clearErrorText, clearErrorStatus,
clearText, clearStatus, memClearText,
memClearStatus, memRecallText, memRecallStatus,
memStoreText, memStoreStatus, memAddText,
memAddStatus, memSubtractText, memSubtractStatus,
base2Text, base2Status, base8Text,
base8Status, base10Text, base10Status,
base16Text, base16Status, degreesText,
degreesStatus, radiansText, radiansStatus,
isRTL.
Language packages load new entries into this array and
automatically apply them as global defaults.If necessary, you can then revert to the default language settings with and apply the language settings to individual fields with Check out the list of available localisation packages. Since 1.2.0 - added decimalChar. |
| standardLayout | string[] | [' BSCECA', '_1_2_3_+@X', '_4_5_6_-@U', '_7_8_9_*@E', '_0_._=_/'] |
The standard layout for a basic decimal calculator. Use this with the layout field. See the key definitions for the meanings of the codes in the layout. |
| scientificLayout | string[] | ['@X@U@E BSCECA', 'DGRD _ MC_ _7_8_9_+', 'SNASSRLG_ MR_ _4_5_6_-', 'CSACSQLN_ MS_ _1_2_3_*', 'TNATXYEX_ M+_ _0_.+-_/', 'PIRN1X _ M-_ _%_='] | A full layout for a decimal calculator with common scientific functions and memory support. Use this with the layout field. See the key definitions for the meanings of the codes in the layout. |
addKeydef | change | destroy | disable | enable | hide | setDefaults | show
| Signature | Returns | Comments |
|---|---|---|
| $.calculator.setDefaults(settings) | calculator object | Update the default instance settings (see above) to use with all calculator instances. |
| $.calculator.addKeyDef( code, label, type, func, style, constant, keystroke, keyName) | calculator object | Add or update the definition for a key to appear on the calculator.
See the key definitions
for more details on the standard keys.code (string) is the two-character code that identifies this key and
can be used within a layout
to denote its position. Use lower-case characters for your names
to avoid conflicts with the standard keys.label (string) is the display text that appears on the
button for this key. If prefixed by a hash (#) the rest of the
label is used to look up the actual text in the regional settings.
For example, '#erase' looks for an 'eraseText' setting for the
button text and an 'eraseStatus' setting for a popup tool-tip.type (enumerated) denotes the type of key and must be
one of the defined constants ($.calculator.):
digit for digits that make up a number,
binary for binary operators (need two values),
unary for unary operators (only need one value),
control for special control buttons,
or space for empty space between buttons.func (function) is the function to call when this key is
activated. The function accepts a single parameter, being the instance
settings for the calculator, and should update its state via the
curValue and prevValue
(for binary operations) fields. See examples on the
key definitions page.style (string) is a space-separated list of CSS styles to
apply to this button. Each style is prefixed by 'calculator-' when applied.constant (string) is the name of a constant
(within $.calculator) that can be used instead of
the code to position a key within a
layout.keystroke (char or number) is the character or keycode that
maps onto this button for keyboard-driven calculations.keyName (string, optional) is the name of the keystroke above
(up to three characters) that is shown when the Alt is held down.
This value is not needed if the keystroke is a standard character.Since 1.0.2 - keyName added.Since 1.2.0 - func
is now a function, previously it was only function name. |
| $('selector').calculator('change', settings) | jQuery object | Update the settings (see above) for the calculator instance(s)
attached to the given field(s).settings (object) is the collection of new settings. |
| $('selector').calculator('change', name, value) | jQuery object | Update a setting (see above) for the calculator 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').calculator('destroy') | jQuery object | Remove the calculator functionality from the given field(s). |
| $('selector').calculator('show') | jQuery object | Pop up the calculator for the given field. |
| $('selector').calculator('hide') | jQuery object | Hide the calculator for the given field. |
| $('selector').calculator('enable') | jQuery object | Enable the calculator for the given field(s) as well as the field itself. |
| $('selector').calculator('disable') | jQuery object | Disable the calculator for the given field(s) as well as the field itself.
Note that a field that is disabled when the calculator is applied to it
causes the calculator to become disabled as well. Since 1.3.0 - automatic disabling. |
| $('selector').calculator('isDisabled') | boolean | Determine whether the calculator functionality has been disabled for the first of the given field(s). |
A number of standard keys are defined for use within the calculator. They may be referenced by their two-character code or their constant name when constructing a layout for the calculator. Two common layouts are defined for your use: standardLayout and scientificLayout.
Use the addKeyDef function to add or update a key definition. The functions that implement the actions operate on the calculator instance object passed in as a parameter. Examples of a binary operation (add) and a unary operation (ln) are shown below.
function add(inst) {
inst.curValue = inst.prevValue + inst.curValue;
}
function ln(inst) {
inst.curValue = Math.log(inst.curValue);
}Contact Keith Wood at kbwood{at}iinet.com.au with comments or suggestions.