# jQuery UI Timepicker (By François Gélinas) Thanks !! (:

## What is this?

This is a jQuery UI time picker plugin build to match with other official jQuery UI widgets. Based on the existing date picker, it will blend nicely with your form and use your selected jQuery UI theme. The plugin is very easy to integrate in your form for you time (hours / minutes) inputs.

Licensed under the same license as jQuery : MIT and GPL licenses

- Examples
- Usage
- Requirements
- Release notes
- Get Timepicker version 0.3.0

Default time picker :
[Show code]

    $('#timepicker').timepicker();

Time picker with period (AM/PM) in input and with hours leading 0s :
[Show code]

    $('#timepicker').timepicker({
        showPeriod: true,
        showLeadingZero: true
    });

Time picker with buttons and labels in another language (Français) :
See the internationalisation page for more information and details.
[Show code]

    $('#timepicker').timepicker({
        hourText: 'Heures',
        minuteText: 'Minutes',
        amPmText: ['AM', 'PM'],
        timeSeparator: 'h',
        nowButtonText: 'Maintenant',
        showNowButton: true,
        closeButtonText: 'Fermer',
        showCloseButton: true,
        deselectButtonText: 'Désélectionner',
        showDeselectButton: true
    });

Time picker with restricted (disabled) hours / minutes. 8:30 PM to 6:30 AM disabled :
[Show code]

    $('#timepicker').timepicker({
            showPeriod: true,
            onHourShow: OnHourShowCallback,
            onMinuteShow: OnMinuteShowCallback
        });
    function OnHourShowCallback(hour) {
        if ((hour > 20) || (hour < 6)) {
            return false; // not valid
        }
        return true; // valid
    }
    function OnMinuteShowCallback(hour, minute) {
        if ((hour == 20) && (minute >= 30)) { return false; } // not valid
        if ((hour == 6) && (minute < 30)) { return false; }   // not valid
        return true;  // valid
    }

Define when the time picker is shown with the `showOn` option and set a trigger element with the `button` option
[Show code]

    $('#timepicker').timepicker({
            showOn: 'button',
            button: '.timepicker_button_trigger'
    });

Time picker without the AM/PM labels on the left (showPeriodLabels option set to false:
[Show code]

    $('#timepicker').timepicker({
        showPeriodLabels: false,
    });

Custom defined hours range (Business hours 6am to 7pm) and minutes increment set to 15 instead of 5, on 3 rows
[Show code]

     $('#timepicke').timepicker({
       hours: { starts: 6, ends: 19 },
       minutes: { interval: 15 },
       rows: 3
       showPeriodLabels: true,
       minuteText: 'Min'
    });

Input for hours only : , input for minutes only :
[Show code]

    $('#timepicker_hours').timepicker({
        showMinutes: false,
        showPeriod: true,
        showLeadingZero: false
    });
    $('#timepicker_minutes').timepicker({
        showHours: false
    });

Timepicker with the Now, Deselect and Close buttons
[Show code]

    $('#timepicker_buttons').timepicker({
        showNowButton: true,
        showDeselectButton: true,
        defaultTime: '',  // removes the highlighted time for when the input is empty.
        showCloseButton: true
    });

onSelect (hours and minutes both trigger event), beforeShow and onClose events :
[Show code]

    function log_event(event) {
        $('#events_log').val(
            $('#events_log').val() + "\n" + event
        )
    }
    $('#timepicker').timepicker({
        onClose: function(time, inst) {
            log_event('onClose triggered with time : ' + time + ' for instance id : ' + inst.id);
        },
        onSelect: function(time, inst) {
            log_event('onSelect triggered with time : ' + time + ' for instance id : ' + inst.id);
        }
    });

events log :

Inline time picker : Alternate field :
[Show code]

    $('#timepicker_inline_div').timepicker({
       altField: '#timepicker_alt_input',
       defaultTime: '9:20'
    });
    function setNewTime() {
        $('#timepicker_inline_div').timepicker('setTime','16:55');
    }
    function getTime() {
        $('#getTime_button').val('Selected time : ' + $('#timepicker').timepicker('getTime'));
    }
    function getHourMinute() {
        $('#getHourMinute_button').val(
                'Hour : ' + $('#timepicker').timepicker('getHour')
                + ', ' +
                'minute : ' + $('#timepicker').timepicker('getMinute')
        );
    }

Two timepickers to select chronological time range, the first timepicker is restricted to before the time selected in the second timepicker, and vice versa.
Start time : end time : [Show code]

    $(document).ready(function() {
        $('#timepicker_start').timepicker({
            showLeadingZero: false,
            onHourShow: tpStartOnHourShowCallback,
            onMinuteShow: tpStartOnMinuteShowCallback
        });
        $('#timepicker_end').timepicker({
            showLeadingZero: false,
            onHourShow: tpEndOnHourShowCallback,
            onMinuteShow: tpEndOnMinuteShowCallback
        });
    });

    function tpStartOnHourShowCallback(hour) {
        var tpEndHour = $('#timepicker_end').timepicker('getHour');
        // Check if proposed hour is prior or equal to selected end time hour
        if (hour <= tpEndHour) { return true; }
        // if hour did not match, it can not be selected
        return false;
    }
    function tpStartOnMinuteShowCallback(hour, minute) {
        var tpEndHour = $('#timepicker_end').timepicker('getHour');
        var tpEndMinute = $('#timepicker_end').timepicker('getMinute');
        // Check if proposed hour is prior to selected end time hour
        if (hour < tpEndHour) { return true; }
        // Check if proposed hour is equal to selected end time hour and minutes is prior
        if ( (hour == tpEndHour) && (minute < tpEndMinute) ) { return true; }
        // if minute did not match, it can not be selected
        return false;
    }

    function tpEndOnHourShowCallback(hour) {
        var tpStartHour = $('#timepicker_start').timepicker('getHour');
        // Check if proposed hour is after or equal to selected start time hour
        if (hour >= tpStartHour) { return true; }
        // if hour did not match, it can not be selected
        return false;
    }
    function tpEndOnMinuteShowCallback(hour, minute) {
        var tpStartHour = $('#timepicker_start').timepicker('getHour');
        var tpStartMinute = $('#timepicker_start').timepicker('getMinute');
        // Check if proposed hour is after selected start time hour
        if (hour > tpStartHour) { return true; }
        // Check if proposed hour is equal to selected start time hour and minutes is after
        if ( (hour == tpStartHour) && (minute > tpStartMinute) ) { return true; }
        // if minute did not match, it can not be selected
        return false;
    }

Example to disable and re-enable a timepicker.
[Show code]

    $('#timepicker_disable_inline').timepicker();
    $('#timepicker_disable').timepicker({showLeadingZero: false });
    $('#btn_disable_tp').click(function() {
        $('#timepicker_disable_inline').timepicker('disable');
        $('#timepicker_disable').timepicker('disable');
    });
    $('#btn_enable_tp').click(function() {
        $('#timepicker_disable_inline').timepicker('enable');
        $('#timepicker_disable').timepicker('enable');
    });

## Usage:

    $('#timepicker').timepicker({
        // Options
        timeSeparator: ':',           // The character to use to separate hours and minutes. (default: ':')
        showLeadingZero: true,        // Define whether or not to show a leading zero for hours < 10.
                                         (default: true)
        showMinutesLeadingZero: true, // Define whether or not to show a leading zero for minutes < 10.
                                         (default: true)
        showPeriod: false,            // Define whether or not to show AM/PM with selected time. (default: false)
        showPeriodLabels: true,       // Define if the AM/PM labels on the left are displayed. (default: true)
        periodSeparator: ' ',         // The character to use to separate the time from the time period.
        altField: '#alternate_input', // Define an alternate input to parse selected time to
        defaultTime: '12:34',         // Used as default time when input field is empty or for inline timePicker
                                      // (set to 'now' for the current time, '' for no highlighted time,
                                         default value: now)

        // trigger options
        showOn: 'focus',              // Define when the timepicker is shown.
                                      // 'focus': when the input gets focus, 'button' when the button trigger element is clicked,
                                      // 'both': when the input gets focus and when the button is clicked.
        button: null,                 // jQuery selector that acts as button trigger. ex: '#trigger_button'

        // Localization
        hourText: 'Hour',             // Define the locale text for "Hours"
        minuteText: 'Minute',         // Define the locale text for "Minute"
        amPmText: ['AM', 'PM'],       // Define the locale text for periods

        // Position
        myPosition: 'left top',       // Corner of the dialog to position, used with the jQuery UI Position utility if present.
        atPosition: 'left bottom',    // Corner of the input to position

        // Events
        beforeShow: beforeShowCallback, // Callback function executed before the timepicker is rendered and displayed.
        onSelect: onSelectCallback,   // Define a callback function when an hour / minutes is selected.
        onClose: onCloseCallback,     // Define a callback function when the timepicker is closed.
        onHourShow: onHourShow,       // Define a callback to enable / disable certain hours. ex: function onHourShow(hour)
        onMinuteShow: onMinuteShow,   // Define a callback to enable / disable certain minutes. ex: function onMinuteShow(hour, minute)

        // custom hours and minutes
        hours: {
            starts: 0,                // First displayed hour
            ends: 23                  // Last displayed hour
        },
        minutes: {
            starts: 0,                // First displayed minute
            ends: 55,                 // Last displayed minute
            interval: 5               // Interval of displayed minutes
        },
        rows: 4,                      // Number of rows for the input tables, minimum 2, makes more sense if you use multiple of 2
        showHours: true,              // Define if the hours section is displayed or not. Set to false to get a minute only dialog
        showMinutes: true,            // Define if the minutes section is displayed or not. Set to false to get an hour only dialog

        // buttons
        showCloseButton: false,       // shows an OK button to confirm the edit
        closeButtonText: 'Done',      // Text for the confirmation button (ok button)
        showNowButton: false,         // Shows the 'now' button
        nowButtonText: 'Now',         // Text for the now button
        showDeselectButton: false,    // Shows the deselect time button
        deselectButtonText: 'Deselect' // Text for the deselect button

    });

## Requirements :

- jQuery 1.5.1 (probably works with previous versions)
- jQuery UI Core (included in jquery-ui-x.x.x.custom.min.js)
- jQuery UI Position utility (optional for special position of the dialog)
- jQuery UI Theme.css (included in jquery-ui-x.x.x.custom.css)
- jquery.ui.timepicker.js
- jquery.ui.timepicker.css

## Releases :

Release 0.3.0 - 27 March 2012
  Fixed a zIndex problem in jQuery Dialog when the user clicked on the input while the timepicker was still visible.
  Added Czech translation, thanks David Spohr
  Added Swedish translation, thanks Björn Westlin
  Added Dutch translation, thanks Lowie Hulzinga
  Prevent showing the timepicker dialog with the button when disabled(Thanks ruhley. ref #38)
  Add ui-state-disabled class to button trigger when disabled.
  Fixed onClose function on first time passes the hours variable as string (Thanks Zanisimo, ref #39)
  Added refresh method. ex: $('selector').timepicker('refresh');
Release 0.2.9 - November 13, 2011
  Fixed the zIndex problem and removed the zIndex option (Thanks everyone who reported the problem)
  Fix a bug where repeatedly clicking on hour cells made the timepicker very slow.
  Added Italian translation, thanks to Serge Margarita.
Release 0.2.8 - October 28, 2011
  Updated defaultTime to allow for Date object (github issue #26)
  Fixed the now and deselect buttons in IE
Release 0.2.7 - October 19, 2011
  Added option to omit minutes in parsed time when user select 0 for minutes. (Thanks tribalvibes, Github issue #23)
  Added support for internationalisation (fr, de and ja, Thanks Bernd Plagge).
  Added an internationalisation page
0.2.6 - October 12, 2011
  Fixed a bug when input ID have more then one special char. (Thanks Jacqueline Krijnen)
  Fixed a bug when parsing hours only or minutes only time. (Thanks protron, github issue #20)
  Added 'Now', 'Deselect' and 'Close' buttons. (Thanks Christian Grobmeier for the close button code, github issue #22)
0.2.5 - September 13, 2011
  Added support for disable and enable. (Suggested by danielrex, github issue #17)
  Added an example for 2 timepicker to behave as a period selector (start time and end time). (Thanks Bill Pellowe)
  Renamed the stylesheet to jquery.ui.timepicker.css to be more consistent with jQuery UI file name convention.
0.2.4 - August 5, 2011
  Fixed the hand cursor in the css file. (Thanks Mike Neumegen)
  Added position option to use with the jquery ui position utility.
  Added option to display only hours or only minutes.
0.2.3 - July 11, 2011
  Fix github issue #3 : Bug when hours or minutes choices does not divide by number of rows (thanks wukimus).
  Changed default behavior of the defaultTime option, if set to '' and input is empty, there will be no highlighted time in the popup (Thanks Rasmus Schultz)
  Fix github issue #4 : Error when generating empty minute cell. (Thanks 123Haynes)
  Fix github issue #5 : Add functionality for "getTime" option. (Thanks edanuff)
  Added the periodSeparator option. (thanks jrchamp)
  Fixed "getTime" for inline timepickers. (thanks Mike Neumegen)
  Added "getHour" and "getMinute" to get individual values.
  New page interface, about time :)
0.2.2 - June 16, 2011
  Fixed a "console.log" line that I forgot to remove before release 0.2.1. (Thanks Derek Lavine)
0.2.1 - June 8, 2011
  Timepicker does not give the focus back to the input any more after time selection. This is similar to the datepicker behaviour and is more natural to the user because it shows the dialog again when the user click on the input again, as expected.
  Added options to customize the hours and minutes ranges and interval for more customization.
0.2 - May 28, 2011
  In the last release, I messed up versions and lost some changes so I'm fixing all this up with release 0.2
0.1.2 - May 26, 2011
  Fixed a bug with inline timepickers that would append a #timepickr hashtag when selecting hours and minutes.
  Fixed z-index problem with IE6 (Thanks Graham Bentley)
  Added selection of highlighted text when enter is pressed on the input field (Thanks Glen Chiacchieri)
  Adjusted some focus problems, now the input gets the focus back when the used click on hours / minutes.
0.1.something aka the lost release - around April 11
  Fixed a bug for when input Id had a dot in it, it was getting double escaped when it should not. (Thanks Zdenek Machac)
  So in 0.1.1 I created a bug that made timepicker changes the location hash, well now it's fixed. (Thanks Lucas Falk)
0.1.1 - April 6, 2011
  Changed the cells click and dblclick binding for faster rendering in IE6/7 (Thanks Blair Parsons)
  Fixed a class naming bug created in 0.1.0 (Thanks Morlion Peter)
0.1.0 - March 23, 2011
  Fixed some bugs with version 0.0.9
0.0.9 - March 22, 2011
  Added zIndex option (Thanks Frank Enderle)
  Added showPeriodLabels option (default: true) to show/hide AM/PM labels on the left (thanks Frank Enderle)
  Added showOn ['focus'|'button'|'both'] and button options for alternate trigger method
0.0.8 - February 17, 2011
  Fixed close event not triggered when switching to another input with time picker (thanks Stuart Gregg)
0.0.7 - February 10, 2011
  Added function to set time after initialisation :$('#timepicker').timepicker('setTime',newTime);
  Added support for disabled period of time : onHourShow and onMinuteShow (thanks Rene Felgenträger)
0.0.6 - January 19, 2011
  Replaced some div with tables to : fix some display bugs in IE7, fix inline display and fix my headhake.
  Added standard "change" event being triggered on the input when the content changes. (Thanks Rasmus Schultz)
  Added support for inline timePicker, attached to div or span.
  Added altField that receive the parsed time value when selected time changes.
  Added defaultTime value to use when input field is missing (inline) or input value is empty. If defaultTime is missing then current time is used.
0.0.5 - January 18, 2011
  Now updating time picker selected value when manually typing in the text field (thanks Rasmus Schultz)
  Another step toward inline time picker ?
  Fixed : with showPeriod: true and showLeadingZero: true, PM hours did not show leading zeros (thanks Chandler May)
  Fixed : with showPeriod: true and showLeadingZero: true, Selecting 12 AM shows as 00 AM in the input field, also parsing 12AM did not work correctly (thanks Rasmus Schultz)
0.0.4 - January 10, 2011
  Changed showLeadingZero to affect only hours, added showMinutesLeadingZero for minutes display.
  Changed the default value of timeSeparator from 'h' to ':'.
  Removed width:100% on tables in the css, caused a bug in some browsers.
0.0.3 - January 8, 2011
  Fixed a bug with the widget not displaying with some jQuery UI 1.8.7 css. (Thanks Alexander Fietz)
  Fixed a display bug on page load, a small empty div was visible at the bottom of pages. (Thanks Gertjan van Roekel)
  Modified the jquery-ui-timepicker.css to make the widget more dynamic to style and sizes changes.
0.0.2 - January 4, 2011
  Added showPeriod: period (AM/PM) in input and showLeadingZero: to control display of number < 10. (big thanks Steve Commisso)
0.0.1 - December 2010
  First release

## To Do :

- Possibility to use the timepicker for hours only, or minutes only.
- Change the code style to use the jQuery widget framework.
- Detect a second click on the same cell and close the picker (ie: the user selected hours and do not want to select different minutes or vice versa, and click twice on the same cell instead) This is already simulated with the handling of the double click.

## Download Timepicker

Current version : 0.3.0 - released 27 march 2012

Get it on github

Download from here (.zip)

I put a lot of time and effort in this project. If you like it, buy me a beer please donate

Instruction for legacy jQuery integration (jQuery 1.2.6 and jQuery UI 1.6)

- Get the legacy package here , built with jQuery Timepicker 0.2.4 but should work with newer versions
- Make sure to include jquery-1.2.6.js, jquery.fix.for.1.2.6.js and jquery.ui.1.6.all.js
- See the working example in index.html in the "legacy_1.2.6" folder.
- Support for previous versions of jquery is limited.