Skip to content

Commit 6a9ae2f

Browse files
rkaraivanovrkaraivanov
committed
Merge branch 'rkaraivanov/multi-column-headers' of https://github.com/IgniteUI/igniteui-angular into rkaraivanov/multi-column-headers
2 parents 44e41f6 + 89d6ec5 commit 6a9ae2f

35 files changed

+6498
-201
lines changed

‎CHANGELOG.md

+23
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
All notable changes for each version of this project will be documented in this file.
44
## 6.1.0
55
- `igxOverlay` service added. **igxOverlayService** allows you to show any component above all elements in page. For more detailed information see the [official documentation](https://www.infragistics.com/products/ignite-ui-angular/angular/components/overlay.html)
6+
- Added **igxRadioGroup** directive. It allows better control over its child `igxRadio` components and support template-driven and reactive forms.
67
- Added `column moving` feature to `igxGrid`, enabled on a per-column level. **Column moving** allows you to reorder the `igxGrid` columns via standard drag/drop mouse or touch gestures.
78
For more detailed information see the [official documentation](https://www.infragistics.com/products/ignite-ui-angular/angular/components/grid_column_moving.html).
89
- `igxGrid` filtering operands
@@ -62,6 +63,28 @@ export class IgxCustomFilteringOperand extends IgxFilteringOperand {
6263
- **Breaking change** filteringExpressions property is removed.
6364

6465
- `igxCell` default editing template is changed according column data type. For more information you can read the [specification](https://github.com/IgniteUI/igniteui-angular/wiki/Cell-Editing) or the [official documentation](https://www.infragistics.com/products/ignite-ui-angular/angular/components/grid_editing.html)
66+
- `igxCombo` component added
67+
68+
```html
69+
<igx-combo #combo [data]="towns" [displayKey]="'townName'" [valueKey]="'postCode'" [groupKey]="'province'"
70+
[allowCustomValues]="true" placeholder="Town(s)" searchPlaceholder="Search town..." [width]="'100%'"></igx-combo>
71+
```
72+
73+
igxCombo features:
74+
75+
- Data Binding
76+
- Value Binding
77+
- Virtualized list
78+
- Multiple Selection
79+
- Filtering
80+
- Grouping
81+
- Custom values
82+
- Templates
83+
- Integration with Template Driven and Reactive Forms
84+
- Keayboard Navigation
85+
- Accessibility compliance
86+
87+
For more detailed information see the [official igxCombo documentation](https://www.infragistics.com/products/ignite-ui-angular/angular/components/combo.html).
6588

6689
- `igxToggle` changes
6790
- `onOpening` event added.

‎projects/igniteui-angular/src/lib/combo/README.md

+228
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
# igx-combo
2+
The igx-combo provides a powerful input, combining features of the basic HTML input, select and the IgniteUI for Angular igx-drop-down controls.
3+
Control provides easy filtering and selection of multiple items, grouping and adding custom values to the list.
4+
Templates for different parts of the control can be defined, including items, header and footer, etc.
5+
Control is integrated with Template Driven and Reactive Forms.
6+
The igx-combo exposes intiutive keyboard navigation and it is accessibility compliant.
7+
Drop Down items are virtualized, which guarantees smooth work, even combo is bound to data source with a lot of items.
8+
9+
10+
`igx-combo` is a component.
11+
A walkthrough of how to get started can be found [here](https://www.infragistics.com/products/ignite-ui-angular/angular/components/combo.html)
12+
13+
# Usage
14+
Basic usage of `igx-combo` bound to a local data source, defining `valueKey` and `displayKey`:
15+
16+
```html
17+
<igx-combo [data]="localData" [valueKey]="'ProductID'" [displayKey]="'ProductName'">
18+
</igx-combo>
19+
```
20+
21+
Remote binding, defining `valueKey` and `displayKey`, and exposing `onDataPreLoad` that allows to load new chunk of remote data to the combo:
22+
23+
```html
24+
<igx-combo [data]="remoteData | async" (onDataPreLoad)="dataLoading($event)" [valueKey]="'ProductID'" [displayKey]="'ProductName'" >
25+
</igx-combo>
26+
```
27+
28+
## Features
29+
30+
### Value Binding
31+
32+
If we want to use a two-way data-binding, we could just use `ngModule` like this:
33+
34+
```html
35+
<igx-combo #combo [(ngModel)]="values"></igx-combo>
36+
```
37+
38+
```typescript
39+
@ViewChild('combo', { read: IgxComboComponent }) public combo: IgxComboComponent;
40+
get values() {
41+
return this.combo.selectedItems();
42+
}
43+
set values(newValues: Array<any>) {
44+
this.combo.selectItems(newValues);
45+
}
46+
```
47+
48+
<div class="divider--half"></div>
49+
50+
### Filtering
51+
By default filtering in the combo is enabled. However you can disable it using the following code:
52+
53+
```html
54+
<igx-combo [filaterable]="false"></igx-combo>
55+
```
56+
57+
<div class="divider--half"></div>
58+
59+
<div class="divider--half"></div>
60+
61+
### Custom Values
62+
Enabling the custom values will add missing from the list, using the combo's interface.
63+
64+
```html
65+
<igx-combo [allowCustomValues]="true"></igx-combo>
66+
```
67+
68+
<div class="divider--half"></div>
69+
70+
### Disabled
71+
You can disable combo using the following code:
72+
73+
```html
74+
<igx-combo [disabled]="true"></igx-combo>
75+
```
76+
77+
<div class="divider--half"></div>
78+
79+
### Grouping
80+
Defining a combo's groupKey option will group the items, according to that key.
81+
82+
```html
83+
<igx-combo [groupKey]="'primaryKey'"></igx-combo>
84+
```
85+
86+
<div class="divider--half"></div>
87+
88+
### Templates
89+
Templates for different parts of the control can be defined, including items, header and footer, etc.
90+
When defining one of the them, you need to reference list of predifined names, as follows:
91+
92+
#### Defining item template:
93+
```html
94+
<igx-combo>
95+
<ng-template #itemTemplate let-display let-key="valueKey">
96+
<div class="item">
97+
<span class="state">State: {{ display[key] }}</span>
98+
<span class="region">Region: {{ display.region }}</span>
99+
</div>
100+
</ng-template>
101+
</igx-combo>
102+
```
103+
104+
#### Defining header template:
105+
106+
```html
107+
<igx-combo>
108+
<ng-template #headerTemplate>
109+
<div class="header-class">Custom header</div>
110+
<img src=""/>
111+
</ng-template>
112+
</igx-combo>
113+
```
114+
115+
#### Defining footer template:
116+
117+
```html
118+
<igx-combo>
119+
<ng-template #footerTemplate>
120+
<div class="footer-class">Custom footer</div>
121+
<img src=""/>
122+
</ng-template>
123+
</igx-combo>
124+
```
125+
126+
#### Defining empty template:
127+
128+
```html
129+
<igx-combo>
130+
<ng-template #emptyTemplate>
131+
<span>List is empty</div>
132+
</ng-template>
133+
</igx-combo>
134+
```
135+
136+
#### Defining add template:
137+
138+
```html
139+
<igx-combo>
140+
<ng-template #addItemTemplate>
141+
<span>Add town</span>
142+
</ng-template>
143+
</igx-combo>
144+
```
145+
<div class="divider--half"></div>
146+
147+
## Keyboard Navigation
148+
149+
When igxCombo is closed and focused:
150+
- `ArrowDown` or `Alt` + `ArrowDown` will open the combo drop down and will move focus to the search input.
151+
152+
When igxCombo is opened and search input is focused:
153+
- `ArrowUp` or `Alt` + `ArrowUp` will close the combo drop down and will move focus to the closed combo.
154+
- `ArrowDown` will move focus from the search input to the first list item.If list is empty and custom values are enabled will move it to the Add new item button.
155+
> Note: Any other key stroke will be handled by the input.
156+
157+
When igxCombo is opened and list item is focued:
158+
- `ArrowDown` will move to next list item. If the active item is the last one in hte list and custom values are enabled then focus will be moved to the Add item button.
159+
160+
- `ArrowUp` will move to previous list item. If the active item is the first one in the list then focus will be moved back to the search input.
161+
162+
- `End` will move to last list item.
163+
164+
- `Home` will move to first list item.
165+
166+
- `Space` will select/deselect active list item.
167+
168+
- `Enter` will confirm the already selected items and will close the list.
169+
170+
- `Esc` will close the list.
171+
172+
When igxCombo is opened allow custom values are enabled and add item button is focused:
173+
174+
- `Space` and `Enter` will add new item with valueKey and displayKey equal to the text in the search input and will select the new item.
175+
176+
- `ArrowUp` focus will be moved back to the last list item or if list is empty will be moved to the search input.
177+
178+
179+
## API
180+
181+
### Inputs
182+
183+
| Name | Description | Type |
184+
|--------------------------|---------------------------------------------------|-----------------------------|
185+
| `data` | combo data source | any |
186+
| `value` | combo value | string |
187+
| `allowCustomValue` | enable/disables combo custom value | boolean |
188+
| `valueKey` | combo value data source property | string |
189+
| `displayKey` | combo dispaly data source property | string |
190+
| `groupKey` | combo item group | string |
191+
| `virtualizationState` | defined he current state of the virtualized data. It contains `startIndex` and `chunkSize` | `IForOfState` |
192+
| `totalItemCount` | total count of the virtual data items, when using remote service | number |
193+
| `width ` | defines combo width | string |
194+
| `heigth` | defines combo height | string |
195+
| `itemsMaxHeight ` | defines drop down height | string |
196+
| `itemsMaxWidth ` | defines drop down width | string |
197+
| `itemHeight ` | defines drop down item height | string |
198+
| `placeholder ` | defines the "empty value" text | string |
199+
| `searchPlaceholder ` | defines the placeholder text for search input | string |
200+
| `collapsed` | gets drop down state | boolean |
201+
| `disabled` | defines whether the control is active or not | boolean |
202+
| `ariaLabelledBy` | defines label ID related to combo | boolean |
203+
204+
### Outputs
205+
206+
| Name | Description | Cancelable | Parameters |
207+
|------------------ |-------------------------------------------------------------------------|------------- |-----------------------------------------|
208+
| `onSelectionChange` | Emitted when item selection is changing, before the selection completes | true | { oldSelection: `Array<any>`, newSelection: `Array<any>`, event: Event } |
209+
| `onSearchInput` | Emitted when an the search input's input event is triggered | false | { searchValue: `string` } |
210+
| `onAddition` | Emitted when an item is being added to the data collection | false | { oldCollection: `Array<any>`, addedItem: `<any>`, newCollection: `Array<any>` }|
211+
| `onDataPreLoad` | Emitted when new chunk of data is loaded from the virtualization | false | { event: Event } |
212+
| `dropDownOpening` | Emitted before the dropdown is opened | false | { event: Event } |
213+
| `dropDownOpened` | Emitted after the dropdown is opened | false | { event: Event } |
214+
| `dropDownClosing` | Emitted before the dropdown is closed | false | { event: Event } |
215+
| `dropDownClosed` | Emitted after the dropdown is closed | false | { event: Event } |
216+
217+
### Methods
218+
219+
| Name | Description | Return type | Parameters |
220+
|----------------- |-----------------------------|----------------------|-----------------------------|
221+
| `open` | Opens drop down | `void` | `None` |
222+
| `close` | Closes drop down | `void` | `None` |
223+
| `toggle` | Toggles drop down | `void` | `None` |
224+
| `selectedItems` | Get current selection state | `Array<any>` | `None` |
225+
| `selectItems` | Select defined items | `void` | items: `Array<any>`, clearCurrentSelection: `boolean` |
226+
| `deselectItems` | Deselect defined items | `void` | items: `Array<any>` |
227+
| `selectAllItems` | Select all (filtered) items | `void` | ignoreFilter?: `boolean` - if `true` selects **all** values |
228+
| `deselectAllItems` | Deselect (filtered) all items | `void` | ignoreFilter?: `boolean` - if `true` deselects **all** values |

0 commit comments

Comments
 (0)