perso-hebdo/js/pickadate.js-3.5.3/_docs/time.htm

{% timeDemoField = function( props ) {
    props = props || {}
    return '<fieldset class="fieldset fieldset--demo js__fieldset"><div class="fieldset__wrapper">' +
        ( props.pre || '' ) +
        '<input id="' + ( props.id || '' ) + '" class="fieldset__input ' + ( props.klass || '' ) + '" type=text placeholder="Try me&hellip;">' +
    '</div></fieldset>'
} %}


<section class="section">


    <div class="section__block section__block--scoped">

        <h1 class="heading heading--divide-center heading--divide-first"><span class="heading__text">The Time Picker<a class="heading__anchor" name="picker" href="#picker">&sect;</a></span></h1>

        <h3 class="heading heading--thin">The basic setup requires targetting an <code class="tag-name">input</code> element and invoking the&nbsp;picker:</h3>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime()</code></pre>
        {%= timeDemoField({ klass: 'js__timepicker' }) %}

    </div> <!-- .section__block -->


    <div class="section__block section__block--scoped">

        <h2 class="heading heading--divide"><span class="heading__text">Options<a class="heading__anchor" name="options" href="#options">&sect;</a></span></h2>
        <p>With the basic invocation above, these are the default settings:</p>

        <pre><code data-language="javascript">// <a href="#translations">Translations</a> and <a href="#buttons">clear button</a>
clear: 'Clear',

// <a href="#formats">Formats</a>
format: 'h:i A',
formatLabel: undefined,
formatSubmit: undefined,
hiddenPrefix: undefined,
hiddenSuffix: '_submit',

// <a href="#editable">Editable input</a>
editable: undefined,

// <a href="#intervals">Time intervals</a>
interval: 30,

// <a href="#limits">Time limits</a>
min: undefined,
max: undefined,

// <a href="#disable-times">Disable times</a>
disable: undefined,

// <a href="#container">Root container</a>
container: undefined,

// <a href="#events">Events</a>
onStart: undefined,
onRender: undefined,
onOpen: undefined,
onClose: undefined,
onSet: undefined,
onStop: undefined,

// <a href="#classes">Classes</a>
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',
}</code></pre>

    <div class="section__block section__block--notification">
        <p><b>*</b> It is important to not add any stylings to the picker’s root element. Instead, target the <code>.picker__holder</code> element (or any other within) based on the state of the root element.</p>
    </div>

    </div> <!-- .section__block -->


</section> <!-- .section -->


<section class="section">

    <div class="section__block section__block--scoped">

        <h2 class="heading heading--divide"><span class="heading__text">Translations<a class="heading__anchor" name="translations" href="#translations">&sect;</a></span></h2>
        <p>Coming soon...</p>

    </div> <!-- .section__block -->

</section> <!-- .section -->


<section class="section">

    <div class="section__block section__block--scoped">

        <h2 class="heading heading--divide"><span class="heading__text">Clear Button<a class="heading__anchor" name="buttons" href="#buttons">&sect;</a></span></h2>
        <p>Change the text or hide the button completely by passing a false-y value:</p>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    clear: ''
})</code></pre>

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

    </div> <!-- .section__block -->

</section> <!-- .section -->


<section class="section">

    <div class="section__block section__block--scoped">

        <h2 class="heading heading--divide"><span class="heading__text">Formats<a class="heading__anchor" name="formats" href="#formats">&sect;</a></span></h2>
        <p>Display a human-friendly label and input format and use an alternate one to submit.</p>
        <p>This is done by creating a new hidden <code class="tag-name">input</code> element with the same <code class="attribute">name</code> attribute as the original and an optional prefix/suffix:</p>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    // Escape any “<a href="#formatting-rules">rule</a>” characters with an exclamation mark (!).
    format: 'T!ime selected: h:i a',
    formatLabel: '&lt;b>h&lt;/b>:i &lt;!i>a&lt;/!i>',
    formatSubmit: 'HH:i',
    hiddenPrefix: 'prefix__',
    hiddenSuffix: '__suffix'
})</code></pre>

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

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

        <style>
            .picker__list small {
                color: #999;
                float: right;
                line-height: 1.5;
            }
            .picker__list .picker__list-item--highlighted small {
                color: #fff;
            }
        </style>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    formatLabel: function(time) {
        var hours = ( time.pick - this.get('now').pick ) / 60,
            label = hours &lt; 0 ? ' !hours to now' : hours > 0 ? ' !hours from now' : 'now'
        return&nbsp; 'h:i a &lt;sm!all>' + ( hours ? Math.abs(hours) : '' ) + label + '&lt;/sm!all>'
    }
})</code></pre>

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

        <h3 class="heading heading--divide"><span class="heading__text">Send the hidden <code class="attribute">value</code> only<a class="heading__anchor" name="formats_use_hidden_only" href="#formats_use_hidden_only">&sect;</a></span></h3>
        <p>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 <code>hiddenName</code> option.</p>
        <p>This essentially nullifies the <code>hiddenPrefix</code> and <code>hiddenSuffix</code>, strips the <code class="attribute">name</code> attribute from the source <code class="tag-name">input</code>, and then sets it as the <code class="attribute">name</code> of the hidden <code class="tag-name">input</code>:</p>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    formatSubmit: 'HH:i',
    hiddenName: true
})</code></pre>

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

        <h3 class="heading heading--divide"><span class="heading__text">Formatting Rules<a class="heading__anchor--bigger" name="formatting-rules" href="#formatting-rules">&sect;</a></span></h3>
        <p>The following rules can be used to format any time:</p>

        <table class="table">
            <thead>
                <tr>
                    <th>Rule</th>
                    <th>Description</th>
                    <th>Result</th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td><code>h</code></td>
                    <td>Hour in 12-hour format</td>
                    <td>1 &ndash; 12</td>
                </tr>
                <tr>
                    <td><code>hh</code></td>
                    <td>Hour in 12-hour format with a leading zero</td>
                    <td>01 &ndash; 12</td>
                </tr>
                <tr>
                    <td><code>H</code></td>
                    <td>Hour in 24-hour format</td>
                    <td>0 &ndash; 23</td>
                </tr>
                <tr>
                    <td><code>HH</code></td>
                    <td>Hour in 24-hour format with a leading zero</td>
                    <td>00 &ndash; 23</td>
                </tr>
            </tbody>
            <tbody>
                <tr>
                    <td><code>i</code></td>
                    <td>Minutes</td>
                    <td>00 &ndash; 59</td>
                </tr>
            </tbody>
            <tbody>
                <tr>
                    <td><code>a</code></td>
                    <td>Day time period</td>
                    <td>a.m. / p.m.</td>
                </tr>
                <tr>
                    <td><code>A</code></td>
                    <td>Day time period in uppercase</td>
                    <td>AM / PM</td>
                </tr>
            </tbody>
        </table>

    </div> <!-- .section__block -->

</section> <!-- .section -->


<section class="section">

    <div class="section__block section__block--scoped">

        <h2 class="heading heading--divide"><span class="heading__text">Editable input<a class="heading__anchor" name="editable" href="#editable">&sect;</a></span></h2>
        <p>By default, typing into the input is disabled by giving it a <code class="attribute">readOnly</code> 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.</p>
        <p>However, this behavior can be changed using the <code>editable</code> option:</p>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    editable: true
})</code></pre>

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

        <div class="section__block section__block--notification">
            <p>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.</p>
        </div>

        <h3 class="heading heading--divide"><span class="heading__text">Using HTML5 attributes<a class="heading__anchor--bigger" name="html5-attributes" href="#html5-attributes">&sect;</a></span></h3>
        <p>Because each <code class="tag-name">input</code> is <a href="#editable"><code class="attribute">readOnly</code> by default</a>, HTML5 attributes, such as <code class="attribute">required</code> and <code class="attribute">pattern</code>, do not get enforced.</p>
        <p>To enable default browser behavior on these attributes, set the <a href="#editable"><code>editable</code> property to <code class="constant">true</code></a>.</p>

    </div> <!-- .section__block -->

</section> <!-- .section -->


<section class="section">

    <div class="section__block section__block--scoped">

        <h2 class="heading heading--divide"><span class="heading__text">Intervals<a class="heading__anchor" name="intervals" href="#intervals">&sect;</a></span></h2>
        <p>Choose the minutes interval between each time in the list:</p>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    interval: 150
})</code></pre>

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

    </div> <!-- .section__block -->

</section> <!-- .section -->


<section class="section">

    <div class="section__block section__block--scoped">

        <h2 class="heading heading--divide"><span class="heading__text">Time Limits<a class="heading__anchor" name="limits" href="#limits">&sect;</a></span></h2>
        <p>Set the minimum and maximum selectable times on the picker.</p>

        <h3 class="heading heading--divide"><span class="heading__text">Using JavaScript dates<a class="heading__anchor--bigger" name="limits-use-dates" href="#limits-use-dates">&sect;</a></span></h3>

        <pre class="pre--demo"><code data-language="javascript">$('.datepicker').pickadate({
    min: new Date(2013,3,20,7),
    max: new Date(2013,7,14,18,30)
})</code></pre>

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

        <h3 class="heading heading--divide"><span class="heading__text">Using arrays formatted as <code>[HOUR,MINUTE]</code><a class="heading__anchor--bigger" name="limits-use-arrays" href="#limits-use-arrays">&sect;</a></span></h3>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    min: [7,30],
    max: [14,0]
})</code></pre>

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

        <h3 class="heading heading--divide"><span class="heading__text">Using integers or a boolean<a class="heading__anchor--bigger" name="limits-relative" href="#limits-relative">&sect;</a></span></h3>

        <pre class="pre--demo"><code data-language="javascript">$('.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
})</code></pre>

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

    </div> <!-- .section__block -->

</section> <!-- .section -->


<section class="section">

    <div class="section__block section__block--scoped">

        <h2 class="heading heading--divide"><span class="heading__text">Disable Times<a class="heading__anchor" name="disable-times" href="#disable-times">&sect;</a></span></h2>
        <p>Disable a specific or arbitrary set of times selectable on the picker.</p>

        <h3 class="heading heading--divide"><span class="heading__text">Using JavaScript dates<a class="heading__anchor--bigger" name="disable-times-use-dates" href="#disable-times-use-dates">&sect;</a></span></h3>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    disable: [
        new Date(2014,3,20,4,30),
        new Date(2014,3,20,9)
    ]
})</code></pre>

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

        <h3 class="heading heading--divide"><span class="heading__text">Using arrays formatted as <code>[HOUR,MINUTE]</code><a class="heading__anchor--bigger" name="disable-times-use-arrays" href="#disable-times-use-arrays">&sect;</a></span></h3>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    disable: [
        [0,30],
        [2,0],
        [8,30],
        [9,0]
    ]
})</code></pre>

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

        <h3 class="heading heading--divide"><span class="heading__text">Using integers as hours (0 to 23)<a class="heading__anchor--bigger" name="disable-times-use-arrays" href="#disable-times-use-arrays">&sect;</a></span></h3>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    disable: [
        3, 5, 7
    ]
})</code></pre>

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

        <h3 class="heading heading--divide"><span class="heading__text">Using objects as a range of times<a class="heading__anchor--bigger" name="disable-times-use-ranges" href="#disable-times-use-ranges">&sect;</a></span></h3>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    disable: [
        { from: [2,0], to: [5,30] }
    ]
})</code></pre>

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

        <p>The values for <code>from</code> &amp; <code>to</code> can be:</p>
        <ul>
            <li>A JavaScript Date object,</li>
            <li>An array formatted as <code>[HOUR,MINUTE]</code>,</li>
            <li>And <code class="constant">true</code> to set it as “now”.</li>
        </ul>
        <p>The values can also be integers representing time intervals relative to the other:</p>
        <ul>
            <li><code>to</code> can only be positive: <pre><code data-language="javascript">{ from: [3,0], to: 10 }</code></pre></li>
            <li><code>from</code> can only be negative: <pre><code data-language="javascript">{ from: -10, to: true }</code></pre></li>
        </ul>

        <h3 class="heading heading--divide"><span class="heading__text"><i><u>Disabling all</u></i> with a set of exceptions<a class="heading__anchor--bigger" name="disable-times-all" href="#disable-times-all">&sect;</a></span></h3>
        <p>Enable only a specific or arbitrary set of times by setting <code class="constant">true</code> as the first item in the collection:</p>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    disable: [
        true,
        3, 5, 7,
        [0,30],
        [2,0],
        [8,30],
        [9,0]
    ]
})</code></pre>

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

        <h3 class="heading heading--divide"><span class="heading__text">Disabling ranges with exceptions<a class="heading__anchor--bigger" name="disable-times-inverted" href="#disable-times-inverted">&sect;</a></span></h3>
        <p>Enable times that fall within a range of disabled times by adding the <code class="string">inverted</code> parameter to the item within the collection:</p>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    disable: [
        1,
        [1, 30, 'inverted'],
        { from: [4, 30], to: [10, 30] },
        [6, 30, 'inverted'],
        { from: [8, 0], to: [9, 0], inverted: true }
    ]
})</code></pre>

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

    </div> <!-- .section__block -->

</section> <!-- .section -->



<section class="section">

    <div class="section__block section__block--scoped">

        <h2 class="heading heading--divide"><span class="heading__text">container<a class="heading__anchor" name="container" href="#container">&sect;</a></span></h2>
        <p>By default, the picker’s root element is inserted right after the <code class="keyword">input</code> element. Specify where to insert the root element by passing any valid CSS selector to this option:</p>

        <div id="root-outlet" style="position:relative"></div>

        <pre class="pre--demo"><code data-language="javascript">$('.timepicker').pickatime({
    container: '#root-outlet'
})</code></pre>

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

        <div class="section__block section__block--notification">
            <p>This is especially important when the <code class="keyword">input</code> falls within a <code class="keyword">label</code> element because click events bubble up to the <code class="keyword">label</code> element and re-open the picker.</p>
        </div>

    </div> <!-- .section__block -->

</section> <!-- .section -->



<section class="section">

    <div class="section__block section__block--scoped">

        <h2 class="heading heading--divide"><span class="heading__text">events<a class="heading__anchor" name="events" href="#events">&sect;</a></span></h2>
        <p>Fire off events as the user interacts with the picker:</p>

        <pre class="pre--demo"><code data-language="javascript">$('.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)
    }
})</code></pre>

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

        <p>The <code class="function">onSet</code> event is the only callback that is passed a <code>context</code> argument that provides details as to which properties are being “set”.</p>
        <p>Within scope of all six of these events, <code class="keyword">this</code> refers to <a href="api.htm">the picker</a>.</p>
        <p>To learn more on how to use the picker object, read the <a href="api.htm">API</a> documentation.</p>

    </div> <!-- .section__block -->

</section> <!-- .section -->