search

fooloomanzoo / datetime-picker

A minimal picker for date and time for Polymer, that can use the native input
MIT License
78 stars 18 forks source link
calendar date datepicker datetimepicker overlay picker polyfill polymer time

readme

Published on NPM Published on webcomponents.org Published on Vaadin Directory

API & Demo

<datetime-picker>

What is it for?

datetime-picker is a picker for date and time for Polymer that can use the native input, too. If the native picker is choosen and is not supported, this element uses the polyfill date-picker. The <calendar-element> and the <time-element> will come in place if the native picker is not available or is not explicitly wanted. A range picker is provided by combining the min- and max-attributes. A codepen demo is available here.

<datetime-picker></datetime-picker>

If you like an overlay then use <overlay-datetime-picker>, what creates the polyfill in an <overlay-element>, that extends Polymer's IronOverlayBehavior and will create some of its attribute-bindings.

You can use other pickers and elements, too. In this collection are for:

Every Element has the same API, so that it would use the given date-properties or for the pickers the native or the polyfill picker. Please see the docs for the given attributes.

The picker-elements can use the auto-confirm-attribute, so that all values will be automatically confirmed when the polyfilled inputs are used. Else the attributes will update like the picker is used but will reset to the old attributes when being canceled and confirmed-value-attribute will be set if they are confirmed. datetime, date and time are the equivalent values of the native inputs. Be aware of timezone-attribute, when you sync datetime, because the Datetime-Object in the browser will use the local timezone.

If you are looking just for an input for date and/or time, please have a look at datetime-input.

Motivation

Internally it tests the browser, if native input-types datetime-local, date or time are supported. If it is not, a <calendar-element> or a <time-element> will be displayed instead, according to the kind of picker you choose. You can decide to use the native or the replacements during runtime. calendar-element and time-element can also be used separately. Internationalization of the view in the pickers is inplemented and the attributes remain in iso8061-format. You can set the timezone of your datetime-values.

It might be useful for you to use, if you like to keep the native approach of Browsers like in Chrome for Desktop or Mobile, you like to have a different look or you would like to have a guaranteed working datetime-picker.

Another use case could be for example, if you want on mobile devices use the native picker, when supported, and on desktop devices this polyfill. For that purpose the attribute native-on-mobile is also provided.

  <datetime-picker native-on-mobile></datetime-picker>

How?

The component page explains, which of the attributes you can use and how. You can see there a demo, too.

You can use it stand-alone, with overlay or as a range of dates. Examples:

Stand-alone calendar and date-input (preset by using its attributes)

<p><calendar-element date="{{date}}"></calendar-element></p>
<p>date: <date-input date="{{date}}"></date-input></p>
<p>datetime: <datetime-input default="2020-05-23" date="{{date}}" datetime="{{datetime}}" step="5"></datetime-input></p>

Use default or another attribute to preset the date. If step is set on a picker, the attribute defines the step a date should be incremented (in seconds). The input for the most inferior standing, that would create an integer step, is used to increment the value. For example, if the step is:

Stand-alone time-picker and time-input (preset by using its attributes)

<time-element time="{{time}}"></time-element>
<p> time: <time-input time="{{time}}" hour="8"></time-input></p>

Note: If you preset the date by the default-attribute and it contains a timezone, This timezone will also used by default.

Use the polyfill or the native picker

By default it checks if datetime-local, date or time is supported as input. Set the auto-confirm attribute to automatically confirm the input. If native is set, the native picker will be used instead of the polyfill:

  Autoconfirming Polyfill Picker <datetime-picker auto-confirm value="{{value}}" datetime="{{synchronized}}"></datetime-picker>

  Native Picker <datetime-picker native value="{{value}}"></datetime-picker>

Define date ranges

Set cross data bindings to limit the values of the inputs. Use the confirmed-value or the auto-confirm-attribute to prevent resetting. Please also visit the demos:

<p>
  <datetime-picker class="begin" auto-confirm datetime="{{min}}" max="{{max}}"></datetime-picker>
  <datetime-picker class="end" auto-confirm datetime="{{max}}" min="{{min}}"></datetime-picker>
</p>
<p>
  <div><code>start</code>: [[min]]</div>
  <div><code>end</code>: [[max]]</div>
</p>

Use it in an overlay

Choose the related elements:

<overlay-datetime-picker value="{{value}}" ></overlay-datetime-picker>
<p>value: [[value]]</p>

Use locale date formats

The properties date, time, datetime are always in iso8061 but the visualization will be localized. By default your locale date format from window.navigator.language will be used, but you can select another locale:

<p>
  hour12-format: <input type="checkbox" checked="{{hour12Format::change}}">
  <br>
  locale:
  <select value="{{locale::change}}">
    <option value=""></option>
    <option value="en">english</option>
    <option value="fr">français</option>
    <option value="de">deutsch</option>
    <option value="es">español</option>
    <option value="it">italiano</option>
    <option value="ru">русский</option>
    <option value="tr">Türkçe</option>
    <option value="ar">العربية</option>
    <option value="he">עברית</option>
    <option value="ja">日本語</option>
    <option value="zh">中文</option>
  </select>
</p>

<p>
  <calendar-element locale="{{locale}}" date="{{date}}" ></calendar-element>
  <time-element locale="{{locale}}" hour12-format="[[hour12Format]]" datetime="{{datetime}}" date="{{date}}"></time-element>
</p>

<p>datetime: [[datetime]]</p>

Styling

Have a look at input-picker-pattern#input-picker-shared-style and input-picker-pattern#input-shared-style to see how to style the picker and input-elements.

Installation

npm i --save @fooloomanzoo/datetime-picker

Notable Changes

Contribute?

Feel free to send a new issue, a commit, a pull request or just fork it!