igniteui-angular

# igxCalendar Component The **igxCalendar** provides a way for the user to select date(s). A walkthrough of how to get started can be found [here](https://www.infragistics.com/products/ignite-ui-angular/angular/components/calendar.html) ## Dependencies In order to be able to use **igxCalendar** you should keep in mind that it is dependent on **BrowserAnimationsModule**, which must be imported **only once** in your application's AppModule, for example: ```typescript import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; @NgModule({ imports: [ BrowserAnimationsModule, ... ] }) export class AppModule { } ``` Also the **igxCalendar** uses the [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) WebAPI for localization and formatting of dates. Consider using the [appropriate polyfills](https://github.com/andyearnshaw/Intl.js/) if your target platform does not support them. ## Usage Be sure to consult the API below for additional information. ### Importing the calendar in your application ```typescript import { IgxCalendarComponent } from "igniteui-angular/main"; ``` or ```typescript import { IgxCalendarComponent } from "igniteui-angular/calendar"; ``` Instantiate a calendar component in single selection mode displaying the current month. ```html <igx-calendar></igx-calendar> ``` A range selection calendar with first day of week set to Monday and an event handler when selection is done. ```html <igx-calendar [weekStart]="1" selection="range" (selected)="eventHandler($event)"></igx-calendar> ``` A multiple selection calendar with different locale and templating for the subheader. ```html <igx-calendar locale="ja-JP" selection="multi"> <ng-template igxCalendarSubheader let-format> {{ format.year.combined }} {{ format.month.combined | titlecase }} </ng-template> </igx-calendar> ``` A calendar displaying more than one month in the view and hiding the days that are outside of the current month ```html <igx-calendar monthsViewNumber="2" [hideOutsideDays]="'true'"> </igx-calendar> ``` The **igxCalendar** implements the `ControlValueAccessor` interface, providing two-way data-binding and the expected behavior when used both in Template-driven or Reactive Forms. ### Keyboard navigation When the **igxCalendar** component is focused: - `PageUp` will move to the previous month. - `PageDown` will move to the next month. - `Shift + PageUp` will move to the previous year. - `Shift + PageDown` will move to the next year. - `Home` will focus the first day of the current month (or first month if more months are displayed) hat is into view. - `End` will focus the last day of the current month ((or last month if more months are displayed)) that is into view. - `Tab` will navigate through the subheader buttons; When `prev` or `next` month buttons (in the subheader) are focused: - `Space` or `Enter` will scroll into view the next or previous month. When `months` button (in the subheader) is focused: - `Space` or `Enter` will open the months view. When `year` button (in the subheader) is focused: - `Space` or `Enter` will open the decade view. When a day inside the current month is focused: - Arrow keys will navigate through the days. - Arrow keys will allow navigation to previous/next month as well. - `Enter` will select the currently focused day. - When more than one month view is displayed, navigating with the arrow keys should move to next/previous month after navigating from first/last day in current month. When a month inside the months view is focused: - Arrow keys will navigate through the months. - `Home` will focus the first month inside the months view. - `End` will focus the last month inside the months view. - `Enter` will select the currently focused month and close the view. When an year inside the decade view is focused: - Arrow keys will navigate through the years. - `Enter` will select the currently focused year and close the view. ## API Summary ### Inputs - `id: string` Unique identifier of the component. If not provided it will be automatically generated. - `vertical: boolean` Controls the layout of the calendar component. When vertical is set to `true` the calendar header will be rendered to the side of the calendar body. Defaults to `false`. - `weekStart: WEEKDAYS | number` Controls the starting day of the weeek for the calendar. Defaults to Sunday. - `locale: string` Controls the locale used for formatting and displaying the dates in the calendar. The expected string should be a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646). The default value is `en`. - `selection: CalendarSelection | string` Controls the type of selection in the calendar. Defaults to `CalendarSelection.SINGLE` which is equivalent to the string `single`. Changing the selection type during 'runtime' will clear the previously selected values in the calendar. The calendar header will not be rendered when the selection is either `multi` or `range`. - `viewDate: Date` Controls the year/month that will be presented in the default view when the calendar renders. By default it is the first day of the current year/month. - `value: Date | Date[]` Gets and sets the selected date(s) in the calendar component. Both `multi` and `range` selection accepts single date values but they always return an array of date objects. - `formatOptions: Object` Controls the date-time components to use in formatted output, and their desired representations. Consult [this](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) for additional information on the available options. The defaul values are listed below. ```typescript { day: 'numeric', month: 'short', weekday: 'short', year: 'numeric' } ``` - `formatViews: Object` Controls whether the date parts in the different calendar views should be formatted according to the provided `locale` and `formatOptions`. The default values are listed below. ```typescript { day: false, month: true, year: false } ``` - `monthViewsNumber: number` Controls the number of month views displayed. Default is 1. - `hideOusideDays: boolean` Controls the visibility of the dates that do not belong to the current month. ### Outputs - `selected(): Date | Date[]` Event fired when a value is selected through UI interaction. Emits the selected value (depending on the type of selection). - `viewDateChanged(): IViewDateChangeEventArgs` Event fired after the month/year presented in the view is changed. Emits an object containing the previous and current value of the `viewDate` property. - `activeViewChanged(): CalendarView` Event fired after the active view is changed. Emits an CalendarView enum, indicating the `activeView` property value. ### Methods - `selectedDate(value: Date | Date[]): void` Sets a new value for the calendar component. **Does not** trigger `selected` event. ### Templating The **igxCalendar** supports templating of its header and subheader parts. Just decorate a ng-template inside the calendar with `igxCalendarHeader` or `igxCalendarSubheader` directive and use the context returned to customize the way the date is displayed. The template decorated with the `igxCalendarHeader` directive is rendered only when the calendar selection is set to `single`. The `igxCalendarSubheader` is available in all selection modes. Example: ```html <igx-calendar> <ng-template igxCalendarHeader let-parts> ... </ng-template> <ng-template igxCalendarSubheader let-parts>  {{ parts.month.combined }} {{ parts.year.combined }} </ng-template> </igx-calendar> ``` #### Template context | Name | Type | Description | | :-------- | :------: | :--------------------------------------------------------------------------- | | date | Date | The date object in the context of the template. See * below for details. | | full | string | The full date representation returned after applying the `formatOptions`. | | monthView | Function | A function which when called puts the calendar in month view. | | yearView | Function | A function which when called puts the calendar in year view. | | era | Object | The era date component (if applicable) formatted to the supplied locale. | | year | Object | The year date component (if applicable) formatted to the supplied locale. | | month | Object | The month date component (if applicable) formatted to the supplied locale. | | day | Object | The day date component (if applicable) formatted to the supplied locale. | | weekday | Object | The weekday date component (if applicable) formatted to the supplied locale. | \* In the `igxCalendarHeader` context this is either the current date or the current selection of the calendar. In the `igxCalendarSubheaderContext` this is the same as the `viewDate` **NOTE:** All of the date components (year, month, etc.) are objects with the structure ```typescript { value: string; literal: string; combined: string; } ``` where `value` is the locale string representation of the date component, `literal` is the locale string separator (if any), and `combined` is as the name suggests the combined output of the two. **NOTE 2:** Mind that both in Internet Explorer and Edge all of the date parts will be empty strings as both browsers don't implement the Intl API providing this functionality.