Skip to content

Commit b482e38

Browse files
kdinevkdinev
authored
Merge pull request #1480 from IgniteUI/combo-master
Combo master
2 parents 5a6c420 + 779686b commit b482e38

29 files changed

+5709
-188
lines changed

‎CHANGELOG.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,28 @@ export class IgxCustomFilteringOperand extends IgxFilteringOperand {
6262
- **Breaking change** filteringExpressions property is removed.
6363

6464
- `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)
65+
- `igxCombo` component added
66+
67+
```html
68+
<igx-combo #combo [data]="towns" [displayKey]="'townName'" [valueKey]="'postCode'" [groupKey]="'province'"
69+
[allowCustomValues]="true" placeholder="Town(s)" searchPlaceholder="Search town..." [width]="'100%'"></igx-combo>
70+
```
71+
72+
igxCombo features:
73+
74+
- Data Binding
75+
- Value Binding
76+
- Virtualized list
77+
- Multiple Selection
78+
- Filtering
79+
- Grouping
80+
- Custom values
81+
- Templates
82+
- Integration with Template Driven and Reactive Forms
83+
- Keayboard Navigation
84+
- Accessibility compliance
85+
86+
For more detailed information see the [official igxCombo documentation](https://www.infragistics.com/products/ignite-ui-angular/angular/components/combo.html).
6587

6688
- `igxToggle` changes
6789
- `onOpening` event added.

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

Lines changed: 228 additions & 0 deletions
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)