Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/adopted-ember-addons/ember-pikaday

A datepicker component for Ember CLI projects.
https://github.com/adopted-ember-addons/ember-pikaday

addon ember ember-pikaday pikaday

Last synced: 2 days ago
JSON representation

A datepicker component for Ember CLI projects.

Awesome Lists containing this project

README 

        
# ember-pikaday



[![Ember Observer Score](https://emberobserver.com/badges/ember-pikaday.svg)](https://emberobserver.com/addons/ember-pikaday)

[![NPM](https://badgen.net/npm/v/ember-pikaday)](https://www.npmjs.com/package/ember-pikaday)



ember-pikaday provides a datepicker modifier & components for Ember using the Pikaday library.



**This addon is fully integration tested, and it provides test helpers to interact with the datepicker in your own tests.**



## Installation



Prerequisites:



- Ember.js v3.28 or above

- ember-auto-import 2.0 or above



Optional prerequisites:



- If you use the backward-compatible `` or `` components, your app must depend on either `moment` or `moment-timezone` and you should remember to configure your locale and timezone requirements. See [Using Moment.js in Ember Apps & Addons](https://github.com/adopted-ember-addons/ember-moment#using-momentjs-in-ember-apps--addons).

- But if you only use the new `` modifier, `moment` or `moment-timezone` are optional. Pikaday itself uses them if they present, but doesn't require them.



Anti-prerequisites:



- Remove ember-cli-moment-shim from your app. Earlier versions of this addon required it, but now it will only give you a redundant copy with the one provided by ember-auto-import.



## Styles



In order to give apps control over styling, the default CSS does not load unless you tell it to. The recommended way to load the CSS is to create this file:



```js

// app/modifiers/pikaday.js



/* Opt-in to using pikaday's default CSS */

import 'ember-pikaday/pikaday.css';

export { default } from 'ember-pikaday/modifiers/pikaday';

```



This guarantees that the CSS will load whenever your app uses the `{{pikaday}}` modifier (and the `{{pikaday}}` modifier is used internally by all the other provided components, so this covers them too).



## Usage



### {{pikaday}} modifier



The `{{pikaday}}` modifier invokes `new Pikaday()` with your element as Pikaday's `field` option:



```hbs



```



The optional `value` argument can be used to synchronize external changes into Pikaday. Internally, we do this using Pikaday's `setDate`.



All other named arguments are passed directly to Pikaday, so see [Pikaday's configuration docs](https://github.com/Pikaday/Pikaday#configuration).



The only behaviors this modifier adds to the stock Pikaday are:



- if you set your `` element's `disabled` attribute we will close Pikaday if it had been open.



### <PikadayInput> Component



While the input shows a formatted date to the user, the `value` attribute can be any valid JavaScript date including `Date` object. If the application sets the attribute without a user interaction the datepicker updates accordingly.



```handlebars



  Start date:

  



```



You can also pass in other closure actions to handle `onOpen`, `onClose` and `onDraw` events.



```handlebars



  Start date:

  



```



You can also change the default format from `DD.MM.YYYY` to any format string supported by Moment.js.



```handlebars



  Start date:

  



```



You can define a theme which will be a CSS class that can be used as a hook for styling different themes.



```handlebars



  Start date:

  



```



You can change the `yearRange`. It defaults to 10. the `yearRange` can be a

single number or two comma separated years.



```handlebars



  Start date:

  



```



```handlebars



  Start date:

  



```



If the second year of the comma separated years is set to `currentYear`, it sets

the maximum selectable year to the current year.



```handlebars



  Start date:

  



```



The `readonly` attribute is supported as binding so you can make the input readonly for mobile or other use cases.



```handlebars



  Start date:

  



```



The `placeholder` attribute is supported as binding so you can improve the user experience of your interface.



```handlebars



  Due date:

  



```



The `disabled` attribute is supported as binding so you can disabled the datepicker entirely.

If the datepicker is shown to the user and it gets disabled it will close the datepicker itself.



```handlebars



  Due date:

  



```



The `firstDay` attribute is supported as a binding so you can set the first day of the calendar week.

Defaults to Monday.



- 0 = Sunday

- 1 = Monday

- etc...



```handlebars



  Due date:

  



```



The `minDate` attribute is supported as a binding so you can set the earliest date that can be selected.



```handlebars



  Due Date:

  



```



The `maxDate` attribute is supported as a binding so you can set the latest date that can be selected.



```handlebars



  Due Date:

  



```



#### Return dates in UTC time zone



The date returned by ember-pikaday is in your local time zone due to the JavaScript default behavior of `new Date()`. This can lead to problems when your application converts the date to UTC. In additive time zones (e.g. +0010) the resulting converted date could be yesterdays date. You can force the component to return a date with the UTC time zone by passing `useUTC=true` to it.



```handlebars



  Start date:

  



```



ember-pikaday will not automatically convert the date to UTC if your application is setting the datepicker value directly!



#### Using pikaday specific options



You can pass any custom pikaday option through the component like this



```handlebars



  



```



Please refer to [pikaday configuration](https://github.com/dbushell/Pikaday#configuration)



### <PikadayInputless>



If you don't want to show an input field, you can use the `` component instead of ``. It has the same API, but doesn't support `onOpen` and `onClose`. When `disabled=true` on a `pikaday-inputless`, the datepicker gets hidden.



## Localization



Localizing the datepicker is possible in two steps. To localize the output of the datepicker, this is the formatted string visible in the input field, you simply include all the locales by following the [ember-cli-moment-shim instructions](https://github.com/jasonmit/ember-cli-moment-shim#cherry-pick-locales-optimal) and include the following in your `ember-cli-build.js`



```js

app.import('node_modules/moment/locale/de.js');

```



To localize the datepicker itself, this is the popup you see after clicking the input, a little more work is necessary. The preferred way to do this is to implement a custom component that extends the `PikadayInput` component and customizes the `i18n` attribute. The following example uses the translations provided by Moment.js - naturally you can use your own localized strings instead.



```js

// app/components/pikaday-input.js



import PikadayInput from "ember-pikaday/components/pikaday-input";

import moment from "moment";



export default PikadayInput.extend({

  init(...args) {

    this._super(args);

    this.i18n = {

      previousMonth: 'Vorheriger Monat',

      nextMonth: 'Nächster Monat',

      months: moment.localeData()._months,

      weekdays: moment.localeData()._weekdays,

      weekdaysShort: moment.localeData()._weekdaysShort,

    };

  },

});

```



## Examples



### Show `ember-pikaday` when clicking on a button



```handlebars

Show Pika

{{#if showPika}}

  

{{/if}}

```



```js

// app/controller/index.js

import Ember from 'ember';

export default Ember.Controller.extend({

  actions: {

    togglePika() {

      this.toggleProperty('showPika');

    },

  },

});

```



### Show `ember-pikaday` when hovering over a div



```handlebars



  Hover me to pika

  {{#if showPika}}

    

  {{/if}}



```



```js

// app/controller/index.js



import Controller from '@ember/controller';

export default Controller.extend({

  actions: {

    showPika() {

      this.set('showPika', true);

    },

    hidePika() {

      this.set('showPika', false);

    },

  },

});

```



## Test Helpers



The test helpers provided by `ember-pikaday` allow you to interact with the datepicker in your integration and acceptance tests.



### Opening Pikaday



To open the datepicker use `click` from the `@ember/test-helpers` package:



```js

import { click } from '@ember/test-helpers';



await click('.my-pikaday-input');

```



### Closing Pikaday



Pikaday can be closed with the provided `close` helper:



```js

import { close as closePikaday } from 'ember-pikaday/test-support';



await closePikaday('.my-pikaday-input');

```



### Interacting with Pikaday



An `Interactor`, like a [page object](https://martinfowler.com/bliki/PageObject.html), provides helpers for getting and setting dates in a date picker:



```js

import { click } from '@ember/test-helpers';

import { Interactor as Pikaday } from 'ember-pikaday/test-support';



await click('#my-datepicker');

await Pikaday.selectDate(new Date(1989, 3, 28));

```



There are also methods available to check if a specific day, month or year is selected:



```js

await Interactor.selectDate(new Date(1989, 3, 28));



assert.equal(Interactor.selectedYear(), 1989);

assert.equal(Interactor.selectedMonth(), 3);

assert.equal(Interactor.selectedDay(), 28);

```



## Other Resources



- [Video introduction by EmberScreencasts](https://www.emberscreencasts.com/posts/56-ember-pikaday)