turn-calendar | A calendar-like component for AngularJS (directive)

Turn-calendar

turn-calendar

Stars : 10

Forks : 10

Created by Tri

Demo Download GitHub

turn calendar

Introduction

Turn Angular is a calendar-like component for AngularJS. It behaviors are very similar to Google analytics calendar, with a few extra unique options.

Demo

Why Turn Calendar ?

Use Turn Calendar if you want a native AngularJS directive that:

  • Behaves like Google Analytics calendar
  • A calendar that is able to do date range selection
  • Configurable prior range preset buttons
  • API supports for start date and end date selection
  • Multiple selection mode
  • Timezone support (require timezoneJS)

Feature comparison

Comparison between Turn Calendar and Angular Strap datepicker, Angular Bootstrap Date picker

Feature Turn Calendar Angular Strap Datepicker Angular Bootstrap Datepicker
Single date selection Yes Yes Yes
Date range selection Yes No No
Multiple month instances Yes No No
Min/Max date selection Yes Yes Yes
Restrict month movement Yes No No
CSS Custom Bootstrap Boostrap
Arbitrary start day of week Yes Yes Yes
Date format customization No Yes Yes
Weekly/Monthly Mode Yes No No
Customizable starting month Yes No No
Prior range preset Yes No No
Settable start/end date Yes Yes Yes
Multiple selection mode Yes No No
Timezone support Yes No No

Dependencies

  • angular (1.0.8)
  • jQuery (2.1.1)

Usage

html

...
<link rel="stylesheet" href="turnCalendar.css">

</head>
<body>

<div ng-controller="fooCtrl">
    <turn-calendar calendar-options="calendarOptions"></turn-calendar>
</div>
...
<script src="turnCalendar.js"></script>

js

angular
.module('foo', ['turn/calendar'])
.controller('fooCtrl', function ($scope) {

    $scope.calendarOptions = {
                        startDayOfWeek: 1,
                        backwardMonths: 2,
                        minSelectDate: '9/13/2013',
                        weeklySelectRange: 60,
                        monthlySelectRange: 90,
                        minBackwardMonth: '08/2013',
                        priorRangePresets: [{value: 7}, {value: 30, isDefault: true}, {value : 45}],
                        maxForwardMonth: $scope.maxMonthAllowed()
                    };

});

Run the demo

bower install
npm install
grunt build
grunt serve

then pop open index.html in a browser. Address is http://localhost:9000/index.html

Run the tests

bower install
npm install
grunt test

Documentation

An AngularJS directive that allows a calendar to be display when embedded.

Allow the following options :

| Option | Type | Required/Optional | Description | |--------------------|---------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | startingMonth | number | Optional | The STARTING month of the calendar, if not specify will use the current month. January is count as 0, February is 1, and so on. | | startingYear | number | Optional | The STARTING year of the calendar, if not specify will use the current year. | | backwardMonths | number | Optional | The number of calendar instances of previous months count from the STARTING month instance, notice the s. For example, if the STARTING month is September, and you want to display July and August in your calendar pop up, set backwardMonths=2. Maximum allowed value is 6. Minimum allowed is 1. If you don't set anything or setting values not in allowed range, there won't be any backward months to display (i.e default value is 0). | | forwardMonths | number | Optional | The number of calendar instances of next months count from the STARTING instance, notice the s at the end. For example: STARTING month is September, and you want to display October and November, set forwardMonths=2. Maximum allowed value is 6. Minimum allowed is 1. If you don't set anything or setting values not in allowed range, there won't be any forward months to display (i.e default value is 0). | | startDayOfWeek | number | Optional | Allow the ability to set any day of the week as the first day of week. Use 0 for Sunday, 1 for Monday, so on. Default is 0. | | minSelectDate | string/number | Optional | The minimum date which any dates which are earlier than that date will not be able to be selected, accept a string in MM-DD-YYYY or MM/DD/YYYY format, or a Unix timestamp. | | maxSelectDate | string/number | Optional | The maximum date which any dates which are later than that date will not be able to be selected, accept a string in MM-DD-YYYY or MM/DD/YYYY format, or a Unix timestamp. | | weeklySelectRange | number | Optional | A number in which if the hovered (or selected) CURRENT date is beyond the LAST selected date, the mouse pointer will change to WEEKLY hover/selected mode. If this or monthlySelectChange is not specified, the default mode is daily. | | monthlySelectRange | number | Optional | A number in which if the hovered (or selected) CURRENT date is beyond the LAST selected date, the mouse pointer will change to MONTHLY hover/selected mode. If this or weeklySelectRange is not specified, the default mode is daily. | | priorRangePresets | array | Optional | An array of object that specify the range buttons to appear for user to select prior range from the CURRENT date. If you want a pre-selected range add a property called isDefault: true. The object MUST have a property called 'value' to display it. 'value' is a number. 'value' is a range that will allow the user to select date range from CURRENT date once clicked. The range will conform with minSelectDate, maxSelectDate, weeklySelectDate, monthlySelectDate parameters if these parameters are set. If you currently in a different month view, clicking on any of the prior button will reset your current view back to the CURRENT month. If your selection mode is 'singleDate', this option will NOT come into effect. Example : [{value: 20, isDefault: true}, {value: 45}, {value : 90}] | | maxForwardMonth | string | Optional | Setting the max month which the NEXT button allowed to work. Format is MM/YYYY. January starts as 0. This setting will override the setting in forwardMonths. For example, you set the starting month as August 2013, with forwardMonths is 3, maxForwardMonth is 10/2013, your calendar will miss the month November 2013, because it exceeds the maxForwardMonth. | | minBackwardMonth | string | Optional | Setting the min month which the PREVIOUS button allowed to work. Format is MM/YYYY . January start as 0. This setting will override the setting in backwardMonths. For example, you set the base month to be March 2014, with backwardMonths to be 3. You also set minBackwardMonths to be 1/2014. The calendar will not display January 2014, and Dec 2013, since minBackwardMonths override backwardMonths. Attempt to press PREVIOUS button won't work either. | | startDate | string/number | Optional | Set the start date to be selected on the calendar. Accept dateString or Unix timestamp. Set this as a directive attribute if you want to be able to set this value in real time. This is the directive to use if you want to read the current selected start date. If minSelectDate is set, and startDate falls into a date that is earlier than minSelectDate, the startDate will be pumped up until it reaches a day that is not conflicted with minSelectDate. | | endDate | string/number | Optional | Set the end date to be selected on the calendar. Accept dateString or Unix timestamp. Set this value as directive attribute if you want to be able to set this value in real time. This is the directive to use if you want to read the current selected end date. If maxSelectDate is set, and this endDate falls into a date that is later than maxSelectDate, endDate will be going backward till it reaches a date that is not conflicted with maxSelectDate. | | applyCallback | function | Optional | A callback function to call when the "Apply" button is pressed. | | selectionMode | string | Optional | The selection behavior of the calendar. Support four options : 'twoClick', 'lastSelectedDate', 'singleDate', and 'disableDayClick'. Default selection mode is 'twoClick', where the selected start date and end date is cleared out every time the user try a new selection. For the mode 'lastSelectedDate', the cursor will jump based on the previous selected date. For the mode 'singleDate', you can only select one date at a time. For the mode 'disableDayClick', you cannot click on the calendar to select dates. | | disabled | boolean | Optional | The boolean variable to dynamically disable toggle button of turn-calendar. The default is false | | timezone | string | Optional | Allow to set and read calendar date according to a specified timezone. Note: you have to include timezoneJS(github.com/mde/timezone-js), with the proper setup in order to use this feature. If you decide to use timestamp to set the start date and end date, the result will be converted to the timezone date. The format will always be MM/dd/yyyy instead of regular locale format | | range-side-mode | boolean | Optional | Show the prior range preset on the right side instead of on top. For this to work you have to supply a string through scope. See examples in index.html | Example:

<turn-calendar start-day-of-week="1" starting-month="11" starting-year="2013"
                 forward-months="3" backward-months="3" min-select-date="'09/13/2013'"
                 weekly-select-range="30" monthly-select-range="60"
                 prior-range-presets="[{value: 20, isDefault: true}, {value: 45}, {value : 90}]"
                 max-forward-month="'10/2014'">
<turn-calendar>

All of the above options can be set through an option object. Pass in the option object through attribute calendarOptions. If you set the same setting in attribute and in option object, the value set in attribute will used over the value in option object.

Real time update for following options are supported : startDate, endDate, minSelectDate, maxSelectDate, minBackwardMonth, maxForwardMonth, forwardMonths, backwardMonths. These options have to set through attributes for real time tracking to work. Setting through options object will not work.

The above code snippet will display 7 months instance, starting from Sep 2013 to March 2014, with Monday as the starting day of the week, the base month is Dec 2013, it will change to weekly select mode if the cursor is 30 days beyond the last selected date, monthly select mode if cursor is 60 days beyond the last selected date. It will display 3 prior buttons: 20, 45, 90, with 25 is pre-selected from the CURRENT date. Anything before 09/13/2013 is not available for selection. Any month above Nov of the year 2014 is not allowed.

Todo list

  • Write more specs
  • Support i18n for month name, day abbreviations, or day names
  • Support date formatting

Contribute

Contributes from everyone are welcomed. A few ways you can contribute immediately:

  • Write more specs
  • Feature suggestions
  • Code feedback

Author

Tri Pham tri.pham@turn.com

License

Apache2

Javscript

Javascript plugin

Angular-js