The jQuery UI Month Picker Plugin

The jQuery UI Month Picker Plugin is designed to allow user input for only a month and year when only that input is required. Clicking on the year, allows the user to jump ahead or back 5 years at a time. Clicking anywhere on the page, except on the month picker menu itself, will cause the month picker to hide. The Month Picker has lots of options for date validation, setting the start year, using an icon button, input masking and more.

-See a demo with unit tests running on jsFiddle at... -http://jsfiddle.net/kidsysco/JeZap/

Prerequisites

This plugin has been tested using the following configuration.

• jQuery 1.9
• jQuery UI 1.9, 1.10
  • jQuery UI Widget Factory required
  • .button() plugin required
  • .datepicker() plugin required
• (optional) Digital Bush Masked Input jQuery Plugin

Installation

Attach all required css and js files to the web page as follows...

link href="http://code.jquery.com/ui/1.10.2/themes/smoothness/jquery-ui.css" media="all" rel="stylesheet" type="text/css" />
link href="css/MonthPicker.2.0.css" media="all" rel="stylesheet" type="text/css" />
script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js" type="text/javascript"></script>
script src="http://code.jquery.com/ui/1.10.2/jquery-ui.js" type="text/javascript"></script>
script src="https://raw.github.com/digitalBush/jquery.maskedinput/1.3.1/dist/jquery.maskedinput.min.js" type="text/javascript"></script>
script src="MonthPicker.2.0.min.js" type="text/javascript"></script>

Source Code Example

This plugin can only be called on the text or month input types as follows.

$('#TextBox1').MonthPicker({ StartYear: 2020, ShowIcon: false });
$('#TextBox2').MonthPicker().css('backgroundColor', 'lightyellow');

HTML 5 Month Input Support

Calling the MonthPicker on HTML 5 Month Input types is currently addressed but still under development. The version of Chrome that I currently run shows some nice examples of how this plugin works with the HTML 5 Month Input Type.

W3C Month Input Type Documentation: http://www.w3.org/TR/html-markup/input.month.html

API Methods

$('.selector').MonthPicker('Clear')
Clears the state of all input and validation warnings.

$('.selector').MonthPicker('ClearAllCallbacks')
Disables all previously assigned event callbacks listed in the Events tab.

$('.selector').MonthPicker('Disable')
Disables the MonthPicker and its associated elements.

$('.selector').MonthPicker('Enable')
Enables the MonthPicker and its associated elements.

$('.selector').MonthPicker('GetSelectedMonthYear')
Validates the selected month/year and returns the selected value if it is a valid date. Returns null if there is no valid date, displays an error message if the message is specified, focuses and selects the violating text.

$('.selector').MonthPicker('GetSelectedMonth')
Returns only the month portion of the selected date as an integer. Returns NaN if there is no valid date.

$('.selector').MonthPicker('GetSelectedYear')
Returns only the year portion of the selected date as an integer. Returns NaN if there is no valid date.

$('.selector').val()
Use jQuery .val() to get the input without any date validation.

Theme Support

The MonthPicker plugin uses the jQuery UI CSS Framework to style its look and feel, including the colors of buttons and background textures. We recommend using the ThemeRoller tool to create and download custom themes that are easy to build and maintain.

If a deeper level of customization is needed, there are widget-specific classes referenced within the MonthPicker.css stylesheet that can be modified. These classes are highlighed below.

.month-picker-disabled

Customize the disabled look of the MonthPicker text box.

.month-picker-invalid-message

Customize the look of validation message.

.month-year-input

Customize the look of the MonthPicker text input box in an enabled state.

Options

Disabled

Type: Boolean
Default: false
Disables and enables the MonthPicker.

Set the option upon init.

$('.selector').MonthPicker({ ShowIcon: true });

Get or set the option, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'Disabled');

//setter
$('.selector').MonthPicker('option', 'Disabled', true );

ShowIcon

Type: Boolean
Default: true
Shows an icon that opens the month picker. Without an icon, the month picker menu will show upon focus of the text box.

Set the option upon init.

$('.selector').MonthPicker({ ShowIcon: true });

Get or set the option, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'ShowIcon');

//setter
$('.selector').MonthPicker('option', 'ShowIcon', false );

StartYear

Type: Int
Default: Current Year
Sets the starting year in the month picker. This option will override all other start year behaviors.

Set the option upon init.

$('.selector').MonthPicker({ StartYear: 2023 });

Get or set the option, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'StartYear');

//setter
$('.selector').MonthPicker('option', 'StartYear', false );

ValidationErrorMessage

Type: Nullable String
Default: null
Sets the starting year in the month picker. Set to null to omit this behavior. This option will override all other start year behaviors.

Set the option upon init.

$('.selector').MonthPicker({ ValidationErrorMessage: 'Invalid Date!' });

Get or set the option, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'ValidationErrorMessage');

//setter
$('.selector').MonthPicker('option', 'ValidationErrorMessage', null );

UseInputMask

Type: Bool
Default: false
Directs the MonthPicker to use the Digital Bush Masked Input jQuery Plugin which must be loaded to the page if this option is to be used.

Set the option upon init.

$('.selector').MonthPicker({ UseInputMask: true });

Get or set the option, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'UseInputMask');

//setter
$('.selector').MonthPicker('option', 'UseInputMask', false );

Events

OnAfterMenuOpen

Type: function
Default: null
This event is triggered after the Month Picker menu opens.

Supply a callback function to handle the event as an init option.

$('.selector').MonthPicker({ OnAfterMenuOpen: function(){ ... } });

Get or set the callback function, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'OnAfterMenuOpen');

//setter
$('.selector').MonthPicker('option', 'OnAfterMenuOpen', function(){ ... } );

OnAfterMenuClose

Type: function
Default: null
This event is triggered after the Month Picker menu closes.

Supply a callback function to handle the event as an init option.

$('.selector').MonthPicker({ OnAfterMenuClose: function(){ ... } });

Get or set the callback function, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'OnAfterMenuClose');

//setter
$('.selector').MonthPicker('option', 'OnAfterNextYear', function(){ ... } );

OnAfterNextYear

Type: function
Default: null
This event is triggered after the Month Picker next year button has been clicked.

Supply a callback function to handle the event as an init option.

$('.selector').MonthPicker({ OnAfterNextYear: function(){ ... } });

Get or set the callback function, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'OnAfterNextYear');

//setter
$('.selector').MonthPicker('option', 'OnAfterNextYear', function(){ ... } );

OnAfterNextYears

Type: function
Default: null
This event is triggered after the Month Picker next 5 years button has been clicked.

Supply a callback function to handle the event as an init option.

$('.selector').MonthPicker({ OnAfterNextYears: function(){ ... } });

Get or set the callback function, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'OnAfterNextYears');

//setter
$('.selector').MonthPicker('option', 'OnAfterNextYears', function(){ ... } );

OnAfterPreviousYear

Type: function
Default: null
This event is triggered after the Month Picker previous year button has been clicked.

Supply a callback function to handle the event as an init option.

$('.selector').MonthPicker({ OnAfterPreviousYear: function(){ ... } });

Get or set the callback function, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'OnAfterPreviousYear');

//setter
$('.selector').MonthPicker('option', 'OnAfterPreviousYear', function(){ ... } );

OnAfterPreviousYears

Type: function
Default: null
This event is triggered after the Month Picker previous 5 years button has been clicked.

Supply a callback function to handle the event as an init option.

$('.selector').MonthPicker({ OnAfterPreviousYears: function(){ ... } });

Get or set the callback function, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'OnAfterPreviousYears');

//setter
$('.selector').MonthPicker('option', 'OnAfterPreviousYears', function(){ ... } );

OnAfterChooseMonth

Type: function
Default: null
This event is triggered after the Month Picker month button has been clicked.

Supply a callback function to handle the event as an init option.

$('.selector').MonthPicker({ OnAfterChooseMonth: function(){ ... } });

Get or set the callback function, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'OnAfterChooseMonth');

//setter
$('.selector').MonthPicker('option', 'OnAfterChooseMonth', function(){ ... } );

OnAfterChooseMonths

Type: function
Default: null
This event is triggered after the Month Picker choose months button has been clicked.

Supply a callback function to handle the event as an init option.

$('.selector').MonthPicker({ OnAfterChooseMonths: function(){ ... } });

Get or set the callback function, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'OnAfterChooseMonths');

//setter
$('.selector').MonthPicker('option', 'OnAfterChooseMonths', function(){ ... } );

OnAfterChooseYear

Type: function
Default: null
This event is triggered after the Month Picker choose year button has been clicked.

Supply a callback function to handle the event as an init option.

$('.selector').MonthPicker({ OnAfterChooseYear: function(){ ... } });

Get or set the callback function, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'OnAfterChooseYear');

//setter
$('.selector').MonthPicker('option', 'OnAfterChooseYear', function(){ ... } );

OnAfterChooseYears

Type: function
Default: null
This event is triggered after the Month Picker choose years button has been clicked.

Supply a callback function to handle the event as an init option.

$('.selector').MonthPicker({ OnAfterChooseYears: function(){ ... } });

Get or set the callback function, after init. 

//getter
var disabled = $('.selector').MonthPicker('option', 'OnAfterChooseYears');

//setter
$('.selector').MonthPicker('option', 'OnAfterChooseYears', function(){ ... } );