Skip to content

mrj/jquery-ui-month-picker

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

67 Commits
 
 
 
 
 
 
 
 

Repository files navigation

The jQuery UI Month Picker Version 2.2mrj

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. By default, 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, setting the earliest and latest date that can be picked, using an icon button, input masking, internationalization and localization and more.

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

Prerequisites

This plugin has been tested using the following configuration.

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 the HTML 5 Month Input Types as follows.

$('#TextBox1').MonthPicker({ StartYear: 2020, ShowIcon: false });
$('input[type=month]').MonthPicker().css('backgroundColor', 'lightyellow');

Internationalization and Localization i18n

All buttons, labels and other text can be changed out using the i18n support. Examples needed here.

HTML 5 Month Input Support

Calling the MonthPicker on HTML 5 Month Input types is currently working. The latest version of Chrome shows some nice examples of how this plugin works with the HTML 5 Month Input Type but we still feel that our UI is better than what Chrome offers... Wow, did I just say that? The jQuery UI month picker UI allows the user to choose any month of the year in a single click, while the Chrome version requires more tinkering. The HTML 5 support in Chrome appears to make input masking and validation obsolete, so those should be turned off when using this plugin on an HTML 5 Month Input Type. The HTML 5 Month Input Type is the reccomended element to call this plugin on but it is not required.

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 );

AlwaysShown

Type: Boolean
Default: false
Makes the picker visible on init instead of when the field/icon is clicked, and prevents it being hidden by either clicks outside the picker or when a month is selected. This useful when the month field is hidden and/or when the form is automatically submitted on an OnAfterChooseMonth event.

Set the option upon init.

$('.selector').MonthPicker({ AlwaysShown: true });
Get or set the option, after init. 
//getter
var disabled = $('.selector').MonthPicker('option', 'AlwaysShown');

//setter
$('.selector').MonthPicker('option', 'AlwaysShown', 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 );

EarliestMonthSelectable

Type: String
Default: Unrestricted
Sets the earliest month that can be selected. Option can either be formatted as MM/YYYY, or as YYYY-MM with an optional, and ignored, -DD suffix.

Set the option upon init.

$('.selector').MonthPicker({ EarliestMonthSelectable: '2005-07-05' });
Get or set the option, after init. 
//getter
var disabled = $('.selector').MonthPicker('option', 'EarliestMonthSelectable');

//setter
$('.selector').MonthPicker('option', 'EarliestMonthSelectable', '2005-07-05' );

LatestMonthSelectable

Type: String
Default: Unrestricted
Sets the latest month that can be selected. Option can either be formatted as MM/YYYY, or as YYYY-MM with an optional, and ignored, -DD suffix.

Set the option upon init.

$('.selector').MonthPicker({ LatestMonthSelectable: '2023-04-12' });
Get or set the option, after init. 
//getter
var disabled = $('.selector').MonthPicker('option', 'LatestMonthSelectable');

//setter
$('.selector').MonthPicker('option', 'LatestMonthSelectable', '2023-04-12' );

ValidationErrorMessage

Type: Nullable String
Default: null
Sets the validation error message for use with text input types. Set to null to omit this behavior. This option will be ignored if the HTML 5 Input Type is used.

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 on text inputs, the plugin must be loaded to the page if this option is to be used. This option will be ignored if the HTML 5 Input Type is 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(){ ... } );

About

jQuery UI Month Picker Plugin

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 93.5%
  • CSS 6.5%