Maskerade jQuery Plug-in

Overview

The Maskerade jQuery plug-in allows for validating dates/times, enforcing masks, automatically interprets keyboard entries based on mask settings, and tries to incorporate all of the best functionality of other date/time plug-ins.

Requirements

In order to use the Maskerade plug-in, you need the following:

jQuery v1.6.3 (or higher)
jquery.maskerade.js Plug-in

Optional Plugins

To support browsers that don't support the "placeholder" attribute, you can use a placeholder shim, such as https://github.com/parndt/jquery-html5-placeholder-shim

Features

Keypress validation (ie. you don't need to submit the form for the mask to be applied)
Full keyboard support, including number to text-date interpretation (eg. typing 6 for a month will show June) and number-entry interpretation (eg. typing 02 in a yyyy date field will be interpreted as 2002)
Full mouse support
Masks can be defined as attributes of the input field; individual jQuery mask calls are not needed
Includes time-mask capability, with a date or alone
Default values and masks set as placeholders in the input field
Ability to set min and max dates allowed on a field
Allows for enforcing relational validation (ie. date1 must be before date2)
Automatic adjusting for invalid dates (eg. Feb 29, 2001 is adjusted to Feb 28, 2001)
Each date/time part fully highlighted on focus
Automatic tabbing to next date/time part once interpreted (eg. typing 2 in a "mm" date part will automatically tab you to the next date part), which allows quick keyboard entry
Allows for dask masks by quarters (eg. Q1, Q2, etc.)
Ability to support multiple languages
Custom event handlers; for example, a single keystroke can be defined to change the date to the current date
Detach/attach Maskerade behavior from the element

Usage

To attach Maskerade to your form elements, just invoke the jQuery plug-in using the following syntax:

$("#myDate").maskerade([options]);

You can use any selector that will target date input elements on your page.

Arguments

options: This argument is optional and allows you to customize the settings used for each instance of the plug-in. For a list of all available options, see the Options section.

Now that we have a reference to the widget, we can invoke any of the public API calls.

Public API

$("#id").maskerade("val" [, value]): Use the val() method to get/set the value of your input element. The value argument is an optional: if not include, val() returns the value of the field; if it's included, it sets the value of the field to value.
$("#id").maskerade("destroy" [, callback()]): Destroys the Maskerade widget. This restores the original input element in the DOM. A callback can be optionally included.
$("#id").maskerade("hasFocus"): Boolean of whether or not the field has focus on it or not.
$("#id").maskerade("isDirty"): Boolean whether or not the field has been changed from it's original value when Maskerade was attached to the field.
$("#id").maskerade("previousValue"): Returns the original value when Maskerade was attached to the field.

Options

There are a number of options available for customizing handling of the widget.

{
     mask:                      // The date mask; this can be defined as a "data-mask"
                                //   parameter on the input element (see Example
                                //   below)
   , lang: "en"                 // The i18n language to display the dates in;
                                //   languages other than english need to be defined
                                //   to the plugin (see Example below)
   , keyBufferDelay: 1250       // Delay to reset the keyboard buffer after mask input

   // event handlers
   , init: null                 // Callback that occurs when initialization starts
   , ready: null                // Callback that occurs once the plug-in is ready for
                                //   use
   , changed: null              // Callback that occurs once the field has changed
   , completed: null            // Callback that occurs when a value has been
                                //   successfully completed
   , corrected: null            // Callback that occurs when a field has been
                                //   automatically corrected (eg. Feb 29, 2001 being
                                //   corrected to Feb 28, 2001)
   , invalid: null              // Callback that occurs when there is an invalid
                                //   keyboard entry
   , keydown: null              // Callback that occurs when the keyboard key is
                                //   pressed down
   , keyup: null                // Callback that occurs when the keyboard key is
                                //   released
   , keypress: null             // Callback that occurs when the keyboard key has
                                //   been pressed down and released
   , formatMask: null           // Callback used to format the mask for display to
                                //   the user (can be a string "toLowerCase" or
                                //   "toUpperCase" to convert display case of the mask)
}

Keyboard

TAB: Go to next mask position (or next field)
⇧ + TAB: Go to previous mask position (or previous field)
→: Go to next mask position
←: Go to previous mask position
↑: Increase the current mask value
↓: Decrease the current mask value
ESC: Reset current changes
DEL: Deletes current mask value (or entire mask if selected)
BKSP: Same as [DEL] key.
HOME: Go to first mask position
END: Go to last mask position

NOTE: Standard keyboard operations such as "Select All", "Copy" and "Paste" should all work.

Mask Definitions

d: 1 or 2 digit numeric day of the month (1-31)
dd: 2 digit numeric day of the month (01-31)
m: 1 or 2 digit numeric month (1-12)
mm: 2 digit numeric month (01-12)
mmm: Abbreviated name of month
mmmm: Full name of month
qq: Start of quarter (Q1, Q2, Q3, Q4)
qqq: Start of quarter w/date (Q1 - Jan 1, Q2 - Apr 1, Q3 - Jul 1, Q4 - Oct 1)
qqqq: Start of quarter w/full date (Q1 - January 1, Q2 - April 1, Q3 - July 1, Q4 - October 1)
QQ: End of quarter (Q1, Q2, Q3, Q4)
QQQ: End of quarter w/date (Q1 - Mar 31, Q2 - Jun 30, Q3 - Sep 31, Q4 - Dec 31)
QQQQ: End of quarter w/full date (Q1 - March 31, Q2 - June 30, Q3 - September 31, Q4 - December 31)
yy: 2 digit numeric year (00-99)
yyyy: 4 digit numeric year
h: 1 or 2 digit numeric 12 hour clock (1-12)
hh: 2 digit numeric 12 hour clock (01-12)
H: 1 or 2 digit numeric 24 hour clock (1-24)
HH: 2 digit numeric 24 hour clock (01-24)
M: 1 or 2 digit numeric minute (0-59)
MM: 2 digit numeric minute (00-59)
s: 1 or 2 digit numeric seconds (0-59)
ss: 2 digit numeric seconds (00-59)
t: First character of am/pm
tt: am/pm

Getting Started

The first thing we need to do is to load the required JavaScript libraries and the CSS stylesheet used by the widget:

<!---// load jQuery and the jQuery iButton Plug-in //--->
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.6.3/jquery.min.js"></script>
<script type="text/javascript" src="./lib/jquery.maskerade.js"></script>
<script type="text/javascript" src="./lib/jquery.html5-placeholder-shim.js"></script>

<!---// load the Maskerade CSS stylesheet //--->
<link type="text/css" href="./css/jquery.maskerade.css" rel="stylesheet" media="all" />

Before you can invoke an instance of the Maskerade widget, you must have one or more input elements on your page.

<input type="text" class="input-date" data-mask="mmm dd, yyyy" />

The next step is to actually create an instance of the Maskerade widget. You want to make sure to initialize the widget after all the necessary DOM elements are available, which makes the document.ready event a great place to initialize the widget.

<script type="text/javascript">
$(document).ready(function (){
  $(".input-date").maskerade();
});
</script>

Now let us take a look at what the code above produced.

Example

You can use all various forms of keyboard input to manipulate the date.

Language Definition Example

Here is how to define a language:

$.maskerade.i18n["fr"] = {
  date: {
      defaultMask: "d mmm yyyy"
    , monthNames: ["Janvier","Février","Mars","Avril","Mai","Juin","Juillet","Août","Septembre","Octobre","Novembre","Décembre"]
    , monthNamesShort: ["Jan","Fév","Mar","Avr","Mai","Jun","Jul","Aoû","Sep","Oct","Nov","Déc"]
  }
};

// on DOM ready
jQuery(function ($){
  $(".input-date").maskerade({lang: "fr"});
}

For many more examples, see the Giva Labs - Maskerade Example Page page.

License

Copyright 2017 Giva, Inc. (https://www.givainc.com/labs/)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Revisions

v1.0.02 (2017-10-25)

Fixed issue in IE11 where an error was thrown when clicking in a date part

v1.0.01 (2012-02-03)

Initial release

Download

The following download includes both uncompressed and minified versions of the plug-in and all the CSS and image files required to get you started. See the gettingstarted.htm file for usage instructions and a working example.

jquery.maskerade.zip (35 KB)