digitalBush

This is a masked input plugin for the jQuery javascript library. It allows a user to more easily enter fixed width input where you would like them to enter the data in a certain format (dates,phone numbers, etc). It has been tested on Internet Explorer 6/7, Firefox 1.5/2, Safari, and Opera.

A mask is defined by a format made up of mask and placeholder characters. Any character not in the placeholder character list below is considered a mask character. Mask characters will be automatically entered for the user as they type and will not be able to be removed by the user.

The following placeholder characters are predefined:

• a - Represents an alpha character (A-Z,a-z)
• 9 - Represents a numeric character (0-9)
• * - Represents an alphanumeric character (A-Z,a-z,0-9)

First, include the masked input javascript file.

<script src="jquery.maskedinput.js" type="text/javascript"></script>

Next, call the mask function for those items you wish to have masked.

jQuery(function($){
   $("#date").mask("99/99/9999");
   $("#phone").mask("(999) 999-9999");
   $("#tin").mask("99-9999999");
   $("#ssn").mask("999-99-9999");
});

Optionally, if you are not satisfied with the underscore (’_') character as a placeholder, you may pass an optional argument to the maskedinput method.

jQuery(function($){
   $("#product").mask("99/99/9999",{placeholder:" "});   
});

Optionally, if you would like to execute a function once the mask has been completed, you can specify that function as an optional argument to the maskedinput method.

jQuery(function($){
   $("#product").mask("99/99/9999",{completed:function(){alert("You typed the following: "+this.val());}});   
});

You can now supply your own placeholder character definitions.

jQuery(function($){
   $.mask.addPlaceholder('~',"[+-]");
   $("#eyescript").mask("~9.99 ~9.99 999");
});

The following example is a demonstration from the usage tab.

1.1.3

• Fixed a bug where the buffer wasn’t being cleared properly, causing characters that had been shifted to be duplicated.

1.1.2

• Fixed a bug in Mac Firefox with backspacing.
• Fixed a bug where delete at end of mask produced an extra placeholder character.
• Exposed the caret positioning and retrieval methods as a jQuery function extension. You can now call $().caret() to get a caret position and $().caret(start [,end]) to set a caret position.

1.1.1

• Fixed a bug introduced with the code changes that prevented IE from working at all.

1.1

• NEW FEATURE: unmask() method to remove masking for a previously masked input.
• Safari cursor position fix.
• Cursor position behavior change: Cursor goes to the end of the input on a completed input. Cursor goes to the first placeholder position on a blank input.
• Fixed improper escaping of certain mask characters.
• Code refactoring to reduce size and complexity.

1.0

• Cosmetic code cleanup

Release Candidate 3

• BREAKING CHANGE: The mask function has been changed to more closely match the style of the jQuery library. Instead of calling .maskedinput(), you will need to call .mask(). Additionally the .AddMaskDefinition() has been moved to a namespace and renamed. Instead, you should make a call to .mask.addPlaceholder().
• Fixed a bug where the buffer was wiped when text was selected and a non-typeable character was pressed.
• Fixed a bug where the buffer was not cleared, but the text was when pressing the escape key.
• More code cleanup.

Release Candidate 2

• Now supports user defined placeholder characters by calling “$.AddMaskDefinition(char,regex)” Please see the Eye Prescription example above.
• Fixed a bug where backspace from the first character position deleted the mask.
• General code cleanup.

Release Candidate 1a

• Corrected the kludgey syntax for the optional mask completed function. You no longer need to pass an argument to your function to gain access to the input making the call. You can now simply reference “this”. Please see the above corrected example.

Release Candidate 1

• Fixed a Safari issue where backspace deleted wrong characters and messed up cursor position.
• Fixed an issue where pre-filled input (value=”something”) was deleted on focus.

Masked Input Beta 2a

• Fixed an issue with the mask disappearing on focus when the input box has no data.

Beta 2

• BREAKING CHANGE: If you were using the optional placeholder argument, you will need to change it to a hashmap syntax. Please see the example above for reference.
• Fixed an issue with pasted values not persisting after a blur/focus.
• Added an optional user defined function to execute when the mask has been completed. I’m using this for my personal projects to advance focus to another area of the form, but this could also be used to validate the value inside the input box. Please see example above.
• Fixed the naming convention to conform to the jQuery standard of jquery.pluginname.js
• Moved the project files to a more logical location on the web server.

Beta 1

• Fixed issues with allowing punctuation on number masks.
• Added validation cleanup of text. Example: pasting in “123-456-7890″ into a “(999) 999-9999″ mask should format correctly.
• Added validation on paste events for Mozilla and IE.

Alpha 1

• Initial Release

Copyright (c) 2007 Josh Bush (digitalbush.com)

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the “Software”), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.