diff --git a/en/components/date_time_editor.md b/en/components/date_time_editor.md new file mode 100644 index 0000000000..d58d5b3b53 --- /dev/null +++ b/en/components/date_time_editor.md @@ -0,0 +1,163 @@ +--- +title: Date Time Editor Directive - Native Angular | Ignite UI for Angular +_description: The Ignite UI for Angular Date Time Editor Directive allows the user to handle date and time using a Date Object. +_keywords: Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI widgets, Angular, Native Angular Components Suite, Native Angular Controls, Native Angular Components Library, Native Angular Components, Angular Date Time Editor Directive, Angular Date Time Directive control, Date Time Editor, Angular Date Time Directive +--- + + +## Date Time Editor Directive +

Ignite UI for Angular Date Time Editor Directive allows the user to set and edit date and time in a chosen input element. The user can edit date or time portion, using an editable masked input. Additionally, can specify a desired display and input format, as well as min and max values to help validation

+
+ + +```html + + + + +``` + +
+ +
+
+ +
+
+ + +### Usage +To get started with the Ignite UI for Angular Date Time Directive, let's first import the `IgxDateTimeEditorModule` in the **app.module.ts** file: + +```typescript +// app.module.ts + +... +import { IgxDateTimeEditorModule } from 'igniteui-angular'; + +@NgModule({ + ... + imports: [..., IgxDateTimeEditorModule ], + ... +}) +export class AppModule {} +``` + + +To use an input as a date time editor, set an igxDateTimeEditor directive and a valid date object as value. In order to have complete editor look and feel, wrap the input in an [input group](input_group.md). This will allow you to not only take advantage of the following directives [`igxInput`]({environment:angularApiUrl}/classes/igxinputdirective.html), [`igxLabel`]({environment:angularApiUrl}/classes/igxlabeldirective.html), `igx-prefix`, `igx-suffix`, [`igx-hint`]({environment:angularApiUrl}/classes/igxhintdirective.html), but cover common scenarios when dealing with form inputs as well. + +#### Binding +A basic configuration scenario setting a Date object as a [`value`]({environment:angularApiUrl}/classes/igxdatetimeeditordirective.html#value): +```typescript +public date = new Date(); +``` + +```html + + + +``` + +To create a two-way data-binding, set an ngModel: +```html + + + +``` +
+ + +#### Keyboard Navigation +Date Time Editor Directive has intuitive keyboard navigation that makes it easy to jump through different DateParts, increment, decrement, etc. without having to touch the mouse. + +- Ctrl / Cmd + Arrow Left / Right - navigates between date sections. On Ctrl / Cmd + Right it goes to the end of the section. If at the end of the section it goes to the end of next section if any. Same in opposite direction. + +- Arrow Up / Down - increment/decrement date portions. See related [`isSpinLoop`]({environment:angularApiUrl}/classes/igxdatetimeeditordirective.html#isspinloop) + +- Ctrl / Cmd + ; - set the current day and time in the editor via a shortcut. + + +### Examples + +#### Display and input format +IgxDateTimeEditor support different display and input formats. + +For display, it uses Angular's [DatePipe](https://angular.io/api/common/DatePipe) which allows it to support pre-defined format options, such as `shortDate` and `longDate`. It can also accept a constructed format string using characters supported by DatePipe, e.g. `EE/MM/yyyy`. Notice formats like shortDate, longDate, etc., can be used as `displayFormat` only. + +To set specific input format, pass it as string to the IgxDateTimeEditor directive. This will set both the expected user input format and [mask](mask.md) for the editor. + + +```html + + + +``` + +#### Min max value +You can specify [`minValue`]({environment:angularApiUrl}/classes/igxdatetimeeditordirective.html#minvalue) and [`maxValue`]({environment:angularApiUrl}/classes/igxdatetimeeditordirective.html#maxvalue) properties to restrict input and control the validity of the ngModel. +```typescript +public minDate = new Date(2020, 1, 15); +public maxDate = new Date(2020, 12, 1); +``` + +```html + + + + +``` + +#### Increment and decrement +`igxDateTimeEditor` directive exposes public `increment` and `decrement` methods. These increment/decrement a specific `DatePart` of the currently set date and time and can be used in a couple of ways. + +In the first scenario, if no specific DatePart is passed to the method, a default DatePart will increment/decrement, based on the specified `inputFormat` and the internal directive implementation. +In the second scenario, you can explicitly specify what DatePart to manipulate as it may suite different requirements. +You may compare both in the following sample: +
+ +
+
+ +
+
+ + +#### In Angular Forms +The Date Time Editor Directive supports all of the form directives from the core FormsModule [NgModel](https://angular.io/api/forms/NgModel) and [ReactiveFormsModule](https://angular.io/api/forms/ReactiveFormsModule) (FormControl, FormGroup, etc.). This also includes the [Forms Validators](https://angular.io/api/forms/Validators) functions. The following example illustrates the use of the `required` validator in a Template-driven Form. + +Template-driven form example: +```html +
+ + + +
+
+``` + +### Styling +For details check out the [`Input Group styling guide`](input_group.md#styling). +
+ +### API References +* [IgxDateTimeEditorDirective]({environment:angularApiUrl}/classes/igxdatetimeeditordirective.html) +* [IgxHintDirective]({environment:angularApiUrl}/classes/igxhintdirective.html) +* [IgxInputDirective]({environment:angularApiUrl}/classes/igxinputdirective.html) +* [IgxInputGroupComponent]({environment:angularApiUrl}/classes/igxinputgroupcomponent.html) +* [IgxInputGroupComponent Styles]({environment:sassApiUrl}/index.html#function-igx-input-group-theme) + +
+ + +### Additional Resources +Related topics: +* [Mask](mask.md) +* [Label & Input](label_input.md) +* [Reactive Forms Integration](input_group_reactive_forms.md) + + +Our community is active and always welcoming to new ideas. +* [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular) +* [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular) \ No newline at end of file diff --git a/en/components/toc.yml b/en/components/toc.yml index 20767880f9..b363c4e451 100644 --- a/en/components/toc.yml +++ b/en/components/toc.yml @@ -1022,6 +1022,9 @@ href: toast.md - name: Scheduling header: true +- name: Date Time Editor + href: date_time_editor.md + new: true - name: Calendar href: calendar.md - name: Date Picker