angular-datetime-input

angular-datetime
================


This module includes a datetime directive and a parser service.

Features
--------
* This module includes:
- A directive which can simulate datetime input within a text field.
- A service which can convert a string of date into a Date object, and vice versa.
* IE8 is supported by transpiling through babel and using polyfill.

Dependencies
------------

* Angular 1.2+
* custom-input 0.2.1 - https://github.com/eight04/custom-input

Date string format
------------------
Apart from the formats provided officially, angular-datetime support some new tokens:

* ZZ - represent timezone with colon (e.g. +08:00)

Demo
----
* With Angular 1.2.x:
* With Angular 1.5.x:

Installation
------------
Via npm:

``shell
npm install angular angular-datetime-input --save
`
`javascript
require("angular-datetime-input");
`

Or use pre-built dist:

`html

`

Example
-------


$3


`Javascript
// Setup dependency
angular.module("myApp", ["datetime"]);

// Use datetime parser
angular.controller("myController", function(datetime){
// Create a parser
var parser = datetime("yyyy-MM-dd");

// Set to current date
parser.setDate(new Date);
parser.getText(); // -> "2015-01-30"

// Parse a date string
parser.parse("2015-01-30");
parser.getDate(); // -> Date object

// Set working timezone. Changing timezone will not affect date object but
// date string (i.e. parser.getText()).
parser.setTimezone("+0800");

// Reset to default timezone.
parser.setTimezone();

// Catch the parsing error
try {
parser.parse("2015-123-456");
} catch (err) {
console.log(err); // -> {code: "...", message: "...", ...}
}
});
`

$3

Check out the demo page for details.

`html






`

API reference
-------------

This module exports:

* datetime service - a function to create DatetimeParser object.
* datetimePlaceholder constant - a map that define the placeholder of each element.

#### datetimePlaceholder object

Just a plain object. Edit it in config phase to specify different placeholder.

Default value:

`js
{
year: "(year)",
yearShort: "(year)",
month: "(month)",
date: "(date)",
day: "(day)",
hour: "(hour)",
hour12: "(hour12)",
minute: "(minute)",
second: "(second)",
millisecond: "(millisecond)",
ampm: "(AM/PM)",
week: "(week)"
}
`

#### datetime(format: String) => DatetimeParser

A function to construct a date parser. format is a string containing date definition tokens defined by Angular: https://docs.angularjs.org/api/ng/filter/date

#### DatetimeParser

A parser object which can convert String to Date and vice versa.

##### DatetimeParser.parse(text: String) => DatetimeParser

Parse text. This method might throw error.

##### DatetimeParser.getText() => String

Return formatted text.

##### DatetimeParser.setDate(date: Date) => DatetimeParser

Set date and conver date to text.

##### DatetimeParser.getDate() => Date

Return Date object.

These methods are usually used like:

`js
date = parser.parse(text).getDate();
text = parser.setDate(date).getText();
`

##### DatetimeParser.setTimezone([timezone: String]) => DatetimeParser

Set the timezone of the parser. timezone is a string matching /[+-]\d{2}:?\d{2}/.

If timezone is not provided, reset timezone to browser default.

Setting timezone doesn't affect model value but update text.

`js
time = parser.getDate().getTime();
parser.setTimezone(newTimezone);
time2 = parser.getDate().getTime();

console.assert(time == time2);
`

##### DatetimeParser.isEmpty() => boolean

Return true if there is any empty element.

##### DatetimeParser.isInit() => boolean

Return true if all elements are set.

##### DatetimeParser.unset() => DatetimeParser

Set all elements to empty.

Known issues
------------
* 2 digit year 'yy' is ambiguous when converting datestring back to date object (Ex. 14 -> 2014, 1914, ...). You should avoid it.

Notes
-----
* Some info about getting selection range across all browsers:
- https://github.com/acdvorak/jquery.caret
- http://stackoverflow.com/questions/19814465/is-it-possible-to-insert-text-in-textarea-and-update-undo-redo-queue

Changelog
---------
* 5.3.0 (Apr 19, 2018)
- Add: datetime-timezone attribute. Now you can customize the timezone in the directive. #60 @andreyjkee
* 5.2.1 (Sep 17, 2017)
- Fix: use unpkg field in package.json.
* 5.2.0 (Sep 17, 2017)
- Fix: use explicit DI annotation. #57
- Change: dist file is minimized. #14
- Change: pre-built dist now includes custom-input so there is no need to inject it manually.
- Update custom-input to 0.3.0 which uses event-lite for smaller file size.
* 5.1.3 (Jul 24, 2017)
- Fix overflowed day issue. #52
* 5.1.2 (Apr 16, 2017)
- Fix jQuery compat issue. #45
* 5.1.1 (Mar 30, 2017)
- Increase directive's priority. #46
* 5.1.0 (Mar 9, 2017)
- Switch to browserify.
- Drop karma, switch to mocha + jsdom.
- Update custom-input to 0.2.0.
- Now this package is requirable, perhaps it works better in different bundlers.
* 5.0.0 (Dec 23, 2016)
- Rewritten in ES6.
- The core part of the parser and the input mask are pulled out as custom-input
- Support IE8 by transpiling through babel and using polyfill for missing functions.
- Add constant datetimePlaceholder.
* 4.1.0 (Oct 5, 2016)
- Refactor.
- Fix day priority bug.
- Add parser.isEmpty. Fix required issue.
* 4.0.0 (Sep 1, 2016)
- Change how parser work. It can represent "undefined" node now.
- Use tab key to navigate between different parts.
* 3.2.2 (Jun 30, 2016)
- Return false if there is no ngModel.
* 3.2.1 (Jun 18, 2016)
- Fix a bug that empty min, max cause invalid date.
* 3.2.0 (May 17, 2016)
- Support dynamic datetime-utc. #29
* 3.1.1 (Apr 17, 2016)
- Deploy to npmjs/angular-datetime-input.
- Drop grunt.
* 3.1.0
- Jump on the next segment on pressing next separator key. (#26)
- Add datetime-separator option.
- Now it will try to fix NUMBER_TOOSHORT error when pressing left/right/separator key.
* 3.0.1 (Apr 9, 2016)
- Fix validator and datetime-model bug. #27
* 3.0.0 (Apr 1, 2016)
- Add token ZZ. #24
- Fix datetime-utc issue. #21
- Add parser.setTimezone. #22
- Use PhantomJS for testing.
- Change Angular dependency to ^1.2.0.
- Fix date overflow bug.
* 2.2.1 (Mar 31, 2016)
- Fix reference error with "Z" token. See #20
* 2.2.0 (Feb 23, 2016)
- Add new error type "LEADING_ZERO", "NUMBER_TOOSMALL".
- Use the behavior introduced in #18.
- Add default attribute.
* 2.1.0 (Jan 12, 2016)
- Add datetime-utc option.
* 2.0.1 (Jan 1, 2016)
- Add MIT License
* 2.0
- Add min, max, datetime-model directive.
- Support $validators in angular 1.3.x.
- Update Eslint to 1.x.
- Fix timezone token Z`.
* 1.0
- Added Karma test.
- Changed source structure.
- Now you can chain parser's methods.
- Parsing error won't mess up modelValue anymore.