From aa3558eb9233946849c9f18a0e89be61f4580ae4 Mon Sep 17 00:00:00 2001 From: IvayloG Date: Fri, 27 Mar 2020 10:52:01 +0200 Subject: [PATCH 1/8] feat(datetime): Add date time editor topic #1823 --- en/components/date_time_editor.md | 187 ++++++++++++++++++++++++++++++ en/components/toc.yml | 3 + 2 files changed, 190 insertions(+) create mode 100644 en/components/date_time_editor.md diff --git a/en/components/date_time_editor.md b/en/components/date_time_editor.md new file mode 100644 index 0000000000..7d96f56e75 --- /dev/null +++ b/en/components/date_time_editor.md @@ -0,0 +1,187 @@ +--- +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 +--- + + + +2. A brief description of the component/feature (1-2 sentences) +## 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

+
+ +3. A basic sample(demo) showcasing the component. The introductory sample shouldn't jump to complex scenarios and edge cases. Those should be reserved for the Advanced Examples section. +### Basic sample + +```html + + + + +``` + +
+ +
+
+ +
+
+ +4. A section outlining the basic usage of the component, ideally describing how the component is used in the context of an application. This section should not list every single feature of the component. It might be divided into several smaller sections. + +### 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 really 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 trough different DateParts, increment, decrement, etc. without having to touch the mouse. + +- Ctrl/Cmd + Arrow Left/Right - navigates between date sections. Jumps from current section to the same caret position of the next/previous section. On start/end sections, first jump to the other end of the same section following the direction of the arrow. +- 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 (as it is in Excel). + + +5. An Examples section, which contains demos focusing on specific features/quirks. Each example should cover one feature only with supporting explanation / code samples as needed. + +### Examples + +#### Display and input format +Date Time Editor Directive support different display and input formats. Notice formats like shortDate, longDate, etc., can be used as displayFormat only: + +```html + + + +``` + +#### Min max value +What is more, 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 a Form +```html +
+ + + + + + + + + +
+
+``` + + +6. The examples section is followed by a brief section that showcases how theming is done via the Sass theming engine. The sample doesn't have to cover all properties of a theme, just a few to give a taste of what the user can expect. +### Styling +For details check out the [`Input Group styling guide`](input_group.md#styling). +
+ +7. An Advanced Samples section that includes practical samples. This section doesn't require exhaustive documentation or code samples, albeit they should provide a live editing link to a platform, like StackBlitz. The provided samples may show the component/feature in the context of other components/features. The section should also reference other Ignite UI for Angular components than the subject of the topic. +### Advanced Samples + +### 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) + +
+ +9. A section with additional resources that links to related topics, the forums and GitHub page of the product e.g. a grid topic may want to reference the tree and hierarchical grid topics as well + +### Additional Resources +Related topics: +* [Reactive Forms Integration](input_group_reactive_forms.md) +* [Label & Input](label_input.md) +* [Combo](combo.md) +* [Select](select.md) +* [Display Density](display_density.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 b3853b1e23..06a3120bde 100644 --- a/en/components/toc.yml +++ b/en/components/toc.yml @@ -1019,6 +1019,9 @@ href: toast.md - name: Scheduling header: true +- name: DateTimeEditor + href: date_time_editor.md + new: true - name: Calendar href: calendar.md - name: Date Picker From df24712deb725e169eb14db3be6852ebaa3db214 Mon Sep 17 00:00:00 2001 From: IvayloG Date: Fri, 27 Mar 2020 16:50:57 +0200 Subject: [PATCH 2/8] chore(datetime): Remove excess comments #1823 --- en/components/date_time_editor.md | 34 +++++++++---------------------- 1 file changed, 10 insertions(+), 24 deletions(-) diff --git a/en/components/date_time_editor.md b/en/components/date_time_editor.md index 7d96f56e75..483f5303b6 100644 --- a/en/components/date_time_editor.md +++ b/en/components/date_time_editor.md @@ -4,23 +4,12 @@ _description: The Ignite UI for Angular Date Time Editor Directive allows the us _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 --- - - -2. A brief description of the component/feature (1-2 sentences) + ## 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

-3. A basic sample(demo) showcasing the component. The introductory sample shouldn't jump to complex scenarios and edge cases. Those should be reserved for the Advanced Examples section. -### Basic sample + ```html @@ -37,7 +26,6 @@ _keywords: Ignite UI for Angular, UI controls, Angular widgets, web widgets, UI
-4. A section outlining the basic usage of the component, ideally describing how the component is used in the context of an application. This section should not list every single feature of the component. It might be divided into several smaller sections. ### 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: @@ -60,7 +48,7 @@ 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 really basic configuration scenario setting a Date object as a [`value`]({environment:angularApiUrl}/classes/igxdatetimeeditordirective.html#value): +A basic configuration scenario setting a Date object as a [`value`]({environment:angularApiUrl}/classes/igxdatetimeeditordirective.html#value): ```typescript public date = new Date(); ``` @@ -83,13 +71,12 @@ To create a two-way data-binding, set an ngModel: #### Keyboard Navigation Date Time Editor Directive has intuitive keyboard navigation that makes it easy to jump trough different DateParts, increment, decrement, etc. without having to touch the mouse. -- Ctrl/Cmd + Arrow Left/Right - navigates between date sections. Jumps from current section to the same caret position of the next/previous section. On start/end sections, first jump to the other end of the same section following the direction of the arrow. -- Arrow Up/Down - increment/decrement date portions. See related [`isSpinLoop`]({environment:angularApiUrl}/classes/igxdatetimeeditordirective.html#isspinloop) +- Ctrl / Cmd + Arrow Left / Right - navigates between date sections. Jumps from current section to the same caret position of the next/previous section. On start/end sections, first jump to the other end of the same section following the direction of the arrow. -- Ctrl/Cmd + ; - set the current day and time in the editor via a shortcut (as it is in Excel). +- 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 (as it is in Excel). -5. An Examples section, which contains demos focusing on specific features/quirks. Each example should cover one feature only with supporting explanation / code samples as needed. ### Examples @@ -131,7 +118,10 @@ You may compare both in the following sample:
-#### In a Form +#### 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
@@ -154,13 +144,10 @@ You may compare both in the following sample:
``` - -6. The examples section is followed by a brief section that showcases how theming is done via the Sass theming engine. The sample doesn't have to cover all properties of a theme, just a few to give a taste of what the user can expect. ### Styling For details check out the [`Input Group styling guide`](input_group.md#styling).
-7. An Advanced Samples section that includes practical samples. This section doesn't require exhaustive documentation or code samples, albeit they should provide a live editing link to a platform, like StackBlitz. The provided samples may show the component/feature in the context of other components/features. The section should also reference other Ignite UI for Angular components than the subject of the topic. ### Advanced Samples ### API References @@ -172,7 +159,6 @@ For details check out the [`Input Group styling guide`](input_group.md#styling).
-9. A section with additional resources that links to related topics, the forums and GitHub page of the product e.g. a grid topic may want to reference the tree and hierarchical grid topics as well ### Additional Resources Related topics: From 0aeb418719f36a1b224fe3b6fc54b9fd0e9b54d9 Mon Sep 17 00:00:00 2001 From: IvayloG Date: Mon, 30 Mar 2020 16:33:42 +0300 Subject: [PATCH 3/8] chore(datetime): Address comments #1823 --- en/components/date_time_editor.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/en/components/date_time_editor.md b/en/components/date_time_editor.md index 483f5303b6..e61f7a606b 100644 --- a/en/components/date_time_editor.md +++ b/en/components/date_time_editor.md @@ -69,19 +69,24 @@ To create a two-way data-binding, set an ngModel: #### Keyboard Navigation -Date Time Editor Directive has intuitive keyboard navigation that makes it easy to jump trough different DateParts, increment, decrement, etc. without having to touch the mouse. +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. Jumps from current section to the same caret position of the next/previous section. On start/end sections, first jump to the other end of the same section following the direction of the arrow. - 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 (as it is in Excel). +- Ctrl / Cmd + ; - set the current day and time in the editor via a shortcut. ### Examples #### Display and input format -Date Time Editor Directive support different display and input formats. Notice formats like shortDate, longDate, etc., can be used as displayFormat only: +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 @@ -90,7 +95,7 @@ Date Time Editor Directive support different display and input formats. Notice f ``` #### Min max value -What is more, 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. +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); From b901426e40c68814ed739e27ef54c980c9f528d8 Mon Sep 17 00:00:00 2001 From: IvayloG Date: Tue, 31 Mar 2020 13:06:33 +0300 Subject: [PATCH 4/8] chore(timeeditor): Adress comments #1823 --- en/components/date_time_editor.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/components/date_time_editor.md b/en/components/date_time_editor.md index e61f7a606b..b5e99c12ca 100644 --- a/en/components/date_time_editor.md +++ b/en/components/date_time_editor.md @@ -133,7 +133,7 @@ Template-driven form example: + [isSpinLoop]="false" /> @@ -114,7 +113,7 @@ public maxDate = new Date(2020, 12, 1); 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: -
+
@@ -153,8 +152,6 @@ Template-driven form example: For details check out the [`Input Group styling guide`](input_group.md#styling).
-### Advanced Samples - ### API References * [IgxDateTimeEditorDirective]({environment:angularApiUrl}/classes/igxdatetimeeditordirective.html) * [IgxHintDirective]({environment:angularApiUrl}/classes/igxhintdirective.html) diff --git a/en/components/toc.yml b/en/components/toc.yml index 06a3120bde..13af51bc5f 100644 --- a/en/components/toc.yml +++ b/en/components/toc.yml @@ -1019,7 +1019,7 @@ href: toast.md - name: Scheduling header: true -- name: DateTimeEditor +- name: Date Time Editor href: date_time_editor.md new: true - name: Calendar From b5e70c140ffacbbde25cce0efb2f94d981e4a502 Mon Sep 17 00:00:00 2001 From: IvayloG Date: Wed, 22 Apr 2020 15:36:30 +0300 Subject: [PATCH 6/8] chore(datetime): Address comments #1823 --- en/components/date_time_editor.md | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/en/components/date_time_editor.md b/en/components/date_time_editor.md index 41e0fcf1da..fe1738e948 100644 --- a/en/components/date_time_editor.md +++ b/en/components/date_time_editor.md @@ -102,7 +102,7 @@ public maxDate = new Date(2020, 12, 1); ```html - + ``` @@ -129,20 +129,9 @@ Template-driven form example: ```html - - - - - - - +
From 0b2904b5ca14a0e6449661aa26ee1bbffda925fc Mon Sep 17 00:00:00 2001 From: IvayloG Date: Thu, 23 Apr 2020 10:08:42 +0300 Subject: [PATCH 7/8] chore(datetime): Address comments #1823 --- en/components/date_time_editor.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/components/date_time_editor.md b/en/components/date_time_editor.md index fe1738e948..840a123f16 100644 --- a/en/components/date_time_editor.md +++ b/en/components/date_time_editor.md @@ -70,7 +70,7 @@ To create a two-way data-binding, set an ngModel: #### 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. Jumps from current section to the same caret position of the next/previous section. On start/end sections, first jump to the other end of the same section following the direction of the arrow. +- 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) From 5822708b2cb9964d4e1c3da9d3e12f48f6cd4acb Mon Sep 17 00:00:00 2001 From: IvayloG Date: Thu, 23 Apr 2020 16:31:53 +0300 Subject: [PATCH 8/8] chore(datetime):Update additional resources #1823 --- en/components/date_time_editor.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/en/components/date_time_editor.md b/en/components/date_time_editor.md index 840a123f16..d58d5b3b53 100644 --- a/en/components/date_time_editor.md +++ b/en/components/date_time_editor.md @@ -153,11 +153,10 @@ For details check out the [`Input Group styling guide`](input_group.md#styling). ### Additional Resources Related topics: -* [Reactive Forms Integration](input_group_reactive_forms.md) +* [Mask](mask.md) * [Label & Input](label_input.md) -* [Combo](combo.md) -* [Select](select.md) -* [Display Density](display_density.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)