type: widget

release: 0.0

status: in development on ice

documentation: N/A

demo: http://view.jqueryui.com/mask/tests/visual/mask/mask.html

TODOs

• update description for custom mask definitions, ala <hh>:<mm>
• extend the spec for the mask option, including examples of what is supported 
• needs demos
• review all comments from https://github.com/jquery/jquery-ui/pull/494 

1 - Description:

The mask plugin shows the user the format to enter data in the field as they enter it. For example, if a phone number is entered in three parts, the three parts are rendered in a single input and as the user enters each part the plugin handles the spacing, which can be much preferred over having three separate inputs and a plugin automatically tabbing from one to the next as each is filled in.

Existing plugins

• https://github.com/digitalBush/jquery.maskedinput
• http://www.meiocodigo.com/projects/meiomask/ 

Alternative approaches:

• http://bradfrostweb.com/blog/post/labelmask/

2 - Visual Design:

3 - Functional Specifications/Requirements:

• Alphabetic masks support accented and other international characters. In a mask that only allows letters, you should be able to type González or Jörn.
• Supports specifying custom mask definitions.
• Allows optional input to accommodate things such as phone numbers with optional extensions. Masked input plugin has a '?' character marking the point at which optional input begins. (example: "(999) 999-9999? x99999"
• Allows pasting in values even when value is missing literals defined in the mask.
• When blurring an incomplete mask, nothing is changed (keep showing the placeholders and literals).
• Removing an incomplete value can be done by binding to the regular blur event, checking !mask("valid"), then using .val("") to clear the input.
• Without any value entered, show the mask only when focused. (clearEmpty option)
• When focusing on an empty element, and the mask is displayed, caret position should be in the beginning instead of where the user happened to click.

Options: 

• clearEmpty (boolean, default: true)
• Clears the input when value is empty and element is not focused.
• definitions (object)
• A map of strings that will be found in the mask, by default "9" allows numbers, "a" allows letters, and "*" allows numbers and letters.
• Each property on the object can point to either a regular expression, or a function which should return the "valid" value ( which should be the same length as the mask )
• If a definition is more than one character, it acts as a "field".
• mask (string, default:none, required)
• Combination of mask definitions and mask literals which describes the input.
• placeholder (char, default: '_')
• Replacement character to use when mask definition is missing user input.

Methods: 

• refresh
• Called after updating HTML, reads value from input again
• valid
• returns true if the mask is fully filled out 
• value 
• Returns a string value without the mask literals. Can also be used as a setter. 

Events: 

• (none)

4 - Markup & Style:

     4.1 Initial markup examples

     No HTML or markup is written or appended to the page. The plugin modifies the value of the targeted input, or html of the targeted element.

     4.2 Recommended transformed HTML markup

     No HTML or markup is written or appended to the page. The plugin modifies the value of the targeted input, or html of the targeted element.

     4.3 Accessibility recommendation

    (Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices) 

     4.4 CSS & Theme

     The class "ui-mask" will be added to elements which this plugin is applied to. The class will be removed when the plugin is destroyed.

5 - Latest version of plugin:

http://view.jqueryui.com/mask/tests/visual/mask/mask.html

6 - Open issues being discussed

• Andy E points out on https://forum.jquery.com/topic/html5-oninput-event :
• Breaks in IE 8 and lower for dropping text into the box, kind of an edge case but you could plug it by cancelling ondragstart and handling ondrop , or handling onpropertychange for the value property
• Prevents shift+cursor key text selection 

Suggested improvements:

• introduce reserved characters to wrap user-defined placeholder strings
• introduce ability to escape reserved characters (default placeholders, the pair of characters introduced by the previous task, and the optional segment delimiter)
• disallow use of multiple un-escaped optional segment delimiters (or add support for multiple optional segments)

Not that important for now:

• We have an issue with caret positioning on mobile android.