The Time Picker§

The basic setup requires targetting an `input` element and invoking the picker:

$('.timepicker').pickatime()

{%= timeDemoField({ klass: 'js__timepicker' }) %}

Options§

With the basic invocation above, these are the default settings:

// Translations and clear button
clear: 'Clear',

// Formats
format: 'h:i A',
formatLabel: undefined,
formatSubmit: undefined,
hiddenPrefix: undefined,
hiddenSuffix: '_submit',

// Editable input
editable: undefined,

// Time intervals
interval: 30,

// Time limits
min: undefined,
max: undefined,

// Disable times
disable: undefined,

// Root container
container: undefined,

// Events
onStart: undefined,
onRender: undefined,
onOpen: undefined,
onClose: undefined,
onSet: undefined,
onStop: undefined,

// Classes
klass: {

    // The element states
    input: 'picker__input',
    active: 'picker__input--active',

    // The root picker and states *
    picker: 'picker picker--time',
    opened: 'picker--opened',
    focused: 'picker--focused',

    // The picker holder
    holder: 'picker__holder',

    // The picker frame, wrapper, and box
    frame: 'picker__frame',
    wrap: 'picker__wrap',
    box: 'picker__box',

    // List of times
    list: 'picker__list',
    listItem: 'picker__list-item',

    // Time states
    disabled: 'picker__list-item--disabled',
    selected: 'picker__list-item--selected',
    highlighted: 'picker__list-item--highlighted',
    viewset: 'picker__list-item--viewset',
    now: 'picker__list-item--now',

    // Clear button
    buttonClear: 'picker__button--clear',
}

* It is important to not add any stylings to the picker’s root element. Instead, target the .picker__holder element (or any other within) based on the state of the root element.

Translations§

Coming soon...

Clear Button§

Change the text or hide the button completely by passing a false-y value:

$('.timepicker').pickatime({
    clear: ''
})

{%= timeDemoField({ id: 'time_demo__buttons' }) %}

Formats§

Display a human-friendly label and input format and use an alternate one to submit.

This is done by creating a new hidden input element with the same name attribute as the original and an optional prefix/suffix:

$('.timepicker').pickatime({
    // Escape any “rule” characters with an exclamation mark (!).
    format: 'T!ime selected: h:i a',
    formatLabel: '<b>h</b>:i <!i>a</!i>',
    formatSubmit: 'HH:i',
    hiddenPrefix: 'prefix__',
    hiddenSuffix: '__suffix'
})

{%= timeDemoField({ id: 'time_demo__formats--a' }).replace( 'type=text', 'name=time_input type=text' ) %}

The formatLabel option is unique. It can contain HTML and it can also be a function if you want to create the label during run-time:

$('.timepicker').pickatime({
    formatLabel: function(time) {
        var hours = ( time.pick - this.get('now').pick ) / 60,
            label = hours < 0 ? ' !hours to now' : hours > 0 ? ' !hours from now' : 'now'
        return  'h:i a <sm!all>' + ( hours ? Math.abs(hours) : '' ) + label + '</sm!all>'
    }
})

{%= timeDemoField({ id: 'time_demo__formats--b' }).replace( 'type=text', 'name=time_demo__formats type=text' ) %}

Send the hidden `value` only§

A majority of the time, the value that needs to be sent to the server is just the hidden value – and not the visible one. To make this happen, use the hiddenName option.

This essentially nullifies the hiddenPrefix and hiddenSuffix, strips the name attribute from the source input, and then sets it as the name of the hidden input:

$('.timepicker').pickatime({
    formatSubmit: 'HH:i',
    hiddenName: true
})

{%= timeDemoField({ id: 'time_demo__formats--c' }).replace( 'type=text', 'name=time_input type=text' ) %}

Formatting Rules§

The following rules can be used to format any time:

Rule	Description	Result
`h`	Hour in 12-hour format	1 – 12
`hh`	Hour in 12-hour format with a leading zero	01 – 12
`H`	Hour in 24-hour format	0 – 23
`HH`	Hour in 24-hour format with a leading zero	00 – 23
`i`	Minutes	00 – 59
`a`	Day time period	a.m. / p.m.
`A`	Day time period in uppercase	AM / PM

Editable input§

By default, typing into the input is disabled by giving it a readOnly attribute. Doing so ensures that virtual keyboards don’t pop open on touch devices. It is also a confirmation that values passed to the server will be of a consistent format.

However, this behavior can be changed using the editable option:

$('.timepicker').pickatime({
    editable: true
})

{%= timeDemoField({ id: 'time_demo__editable' }) %}

An important thing to note here is that this disables keyboard bindings on the input element, such as arrow keys opening the picker. You will have to add your own bindings as you see fit.

Using HTML5 attributes§

Because each input is readOnly by default, HTML5 attributes, such as required and pattern, do not get enforced.

To enable default browser behavior on these attributes, set the editable property to true.

Intervals§

Choose the minutes interval between each time in the list:

$('.timepicker').pickatime({
    interval: 150
})

{%= dateDemoField({ id: 'time_demo__interval' }) %}

Time Limits§

Set the minimum and maximum selectable times on the picker.

Using JavaScript dates§

$('.datepicker').pickadate({
    min: new Date(2013,3,20,7),
    max: new Date(2013,7,14,18,30)
})

{%= dateDemoField({ id: 'time_demo__limits--a' }) %}

Using arrays formatted as `[HOUR,MINUTE]`§

$('.timepicker').pickatime({
    min: [7,30],
    max: [14,0]
})

{%= timeDemoField({ id: 'time_demo__limits--b' }) %}

Using integers or a boolean§

$('.timepicker').pickatime({
    // An integer (positive/negative) sets it as intervals relative from now.
    min: -5,
    // `true` sets it to now. `false` removes any limits.
    max: true
})

{%= timeDemoField({ id: 'time_demo__limits--c' }) %}

Disable Times§

Disable a specific or arbitrary set of times selectable on the picker.

Using JavaScript dates§

$('.timepicker').pickatime({
    disable: [
        new Date(2014,3,20,4,30),
        new Date(2014,3,20,9)
    ]
})

{%= timeDemoField({ id: 'time_demo__disable-times--a' }) %}

Using arrays formatted as `[HOUR,MINUTE]`§

$('.timepicker').pickatime({
    disable: [
        [0,30],
        [2,0],
        [8,30],
        [9,0]
    ]
})

{%= timeDemoField({ id: 'time_demo__disable-times--b' }) %}

Using integers as hours (0 to 23)§

$('.timepicker').pickatime({
    disable: [
        3, 5, 7
    ]
})

{%= timeDemoField({ id: 'time_demo__disable-times--c' }) %}

Using objects as a range of times§

$('.timepicker').pickatime({
    disable: [
        { from: [2,0], to: [5,30] }
    ]
})

{%= dateDemoField({ id: 'date_demo__disable-times--d' }) %}

The values for from & to can be:

A JavaScript Date object,
An array formatted as [HOUR,MINUTE],
And true to set it as “now”.

The values can also be integers representing time intervals relative to the other:

to can only be positive:
```
{ from: [3,0], to: 10 }
```
from can only be negative:
```
{ from: -10, to: true }
```

Disabling all with a set of exceptions§

Enable only a specific or arbitrary set of times by setting true as the first item in the collection:

$('.timepicker').pickatime({
    disable: [
        true,
        3, 5, 7,
        [0,30],
        [2,0],
        [8,30],
        [9,0]
    ]
})

{%= timeDemoField({ id: 'time_demo__disable-times--e' }) %}

Disabling ranges with exceptions§

Enable times that fall within a range of disabled times by adding the inverted parameter to the item within the collection:

$('.timepicker').pickatime({
    disable: [
        1,
        [1, 30, 'inverted'],
        { from: [4, 30], to: [10, 30] },
        [6, 30, 'inverted'],
        { from: [8, 0], to: [9, 0], inverted: true }
    ]
})

{%= timeDemoField({ id: 'time_demo__disable-times--f' }) %}

container§

By default, the picker’s root element is inserted right after the input element. Specify where to insert the root element by passing any valid CSS selector to this option:

$('.timepicker').pickatime({
    container: '#root-outlet'
})

{%= timeDemoField({ id: 'time_demo__container' }) %}

This is especially important when the input falls within a label element because click events bubble up to the label element and re-open the picker.

events§

Fire off events as the user interacts with the picker:

$('.timepicker').pickatime({
    onStart: function() {
        console.log('Hello there :)')
    },
    onRender: function() {
        console.log('Whoa.. rendered anew')
    },
    onOpen: function() {
        console.log('Opened up')
    },
    onClose: function() {
        console.log('Closed now')
    },
    onStop: function() {
        console.log('See ya.')
    },
    onSet: function(context) {
        console.log('Just set stuff:', context)
    }
})

{%= timeDemoField({ id: 'time_demo__events' }).replace( 'Try me', 'Open your console and try me' ) %}

The onSet event is the only callback that is passed a context argument that provides details as to which properties are being “set”.

Within scope of all six of these events, this refers to the picker.

To learn more on how to use the picker object, read the API documentation.

The Time Picker§

The basic setup requires targetting an input element and invoking the picker:

Options§

Translations§

Clear Button§

Formats§

Send the hidden value only§

Formatting Rules§

Editable input§

Using HTML5 attributes§

Intervals§

Time Limits§

Using JavaScript dates§

Using arrays formatted as [HOUR,MINUTE]§

Using integers or a boolean§

Disable Times§

Using JavaScript dates§

Using arrays formatted as [HOUR,MINUTE]§

Using integers as hours (0 to 23)§

Using objects as a range of times§

Disabling all with a set of exceptions§

Disabling ranges with exceptions§

container§

events§

The basic setup requires targetting an `input` element and invoking the picker:

Send the hidden `value` only§

Using arrays formatted as `[HOUR,MINUTE]`§

Using arrays formatted as `[HOUR,MINUTE]`§