# The Time Picker§

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

    $('.timepicker').pickatime()

## 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: ''
    })

## 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'
    })

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>'
        }
    })

### 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
    })

### 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
    })

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

## 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)
    })

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

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

### 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
    })

## 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)
        ]
    })

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

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

### Using integers as hours (0 to 23)§

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

### Using objects as a range of times§

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

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]
        ]
    })

### 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 }
        ]
    })

## 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'
    })

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

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.