Merge branch 'master' into astaev/5671-master

Author: kdinev

CHANGELOG.md

@@ -14,6 +14,26 @@ All notable changes for each version of this project will be documented in this
     - **Breaking Change** `igxExcelStyleMovingTemplate` directive is renamed to `igxExcelStyleMoving`.
     - **Breaking Change** `igxExcelStyleHidingTemplate` directive is renamed to `igxExcelStyleHiding`.
     - **Breaking Change** `igxExcelStylePinningTemplate` directive is renamed to `igxExcelStylePinning`.
+- `IgxCombo`
+    - Combo selection is now consistent when `valueKey` is defined. When `valueKey` is specified, selection is based on the value keys of the items. For example:
+    ```html
+    <igx-combo [data]="myCustomData" valueKey="id" displayKey="text"></igx-combo>
+    ```
+    ```typescript
+    export class MyCombo {
+        ...
+        public combo: IgxComboComponent;
+        public myCustomData: { id: number, text: string } = [{ id: 0, name: "One" }, ...];
+        ...
+        ngOnInit() {
+            // Selection is done only by valueKey property value
+            this.combo.selectItems([0, 1]);
+        }
+    }
+    ```
+   - **Breaking Change** When using `[valueKey]`, combo methods, events and outputs **cannot** be handled with *data item references*.
+   - For more information, visit the component's [readme](https://github.com/IgniteUI/igniteui-angular/tree/master/projects/igniteui-angular/src/lib/combo/README.md)
+
 ## 8.1.4
 - `IgxDialog` new @Input `positionSettings` is now available. It provides the ability to get/set both position and animation settings of the Dialog component. 
 

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

@@ -53,20 +53,68 @@ The service, should inform the combo for the total items that are on the server
 
 ## Features
 
+### Selection
+
+Combo selection depends on the `[valueKey]` input property:
+
+- If a `[valueKey]` is specified, **all** methods and events tied to the selection operate w/ the value key property of the combo's `[data]` items:
+```html
+    <igx-combo [data]="myCustomData" valueKey="id" displayKey="text"></igx-combo>
+```
+```typescript
+export class MyCombo {
+    ...
+    public combo: IgxComboComponent;
+    public myCustomData: { id: number, text: string } = [{ id: 0, name: "One" }, ...];
+    ...
+    ngOnInit() {
+        // Selection is done only by valueKey property value
+        this.combo.selectItems([0, 1]);
+    }
+}
+```
+
+- When **no** `valueKey` is specified, selection is handled by **equality (===)**. To select items by object reference, the `valueKey` property should be removed:
+```html
+    <igx-combo [data]="myCustomData" displayKey="text"></igx-combo>
+```
+```typescript
+export class MyCombo {
+    ngOnInit() {
+        this.combo.selectItems(this.data[0], this.data[1]);
+    }
+}
+```
+
 ### Value Binding
 
 If we want to use a two-way data-binding, we could just use `ngModel` like this:
 
 ```html
-<igx-combo #combo [data]="data" [(ngModel)]="values"></igx-combo>
+<igx-combo #combo [data]="data" valueKey="id" displayKey="text" [(ngModel)]="values"></igx-combo>
+```
+```typescript
+export class MyExampleComponent {
+    ...
+    public data: {text: string, id: number, ... }[] = ...;
+    ...
+    public values: number[] = ...;
+}
 ```
 
+When the `data` input is made up of complex types (i.e. objects), it is advised to bind the selected data via `valueKey` (as in the above code snippet). Specify a property that is unique for each data entry and pass an array with values for those properties, corresponding to the items you want selected.
+
+If you want to bind the selected data by reference, **do not** specify a `valueKey`:
+
+```html
+<igx-combo #combo [data]="data" displayKey="text" [(ngModel)]="values"></igx-combo>
+```
 ```typescript
 export class MyExampleComponent {
     ...
-    public data: ExampleType[] = ...;
+    public data: {text: string, id: number, ... }[] = ...;
     ...
-    public values: ExampleType[] = ...;
+    public values: {text: string, id: number, ...} [] = [this.items[0], this.items[5]];
 }
 ```
 

projects/igniteui-angular/src/lib/combo/combo-item.component.ts

@@ -32,7 +32,8 @@ export class IgxComboItemComponent extends IgxDropDownItemComponent implements D
      * @hidden
      */
     public get itemID() {
-        return this.comboAPI.isRemote ? JSON.stringify(this.value) : this.value;
+        const valueKey = this.comboAPI.valueKey;
+        return valueKey !== null ? this.value[valueKey] : this.value;
     }
 
     /**

projects/igniteui-angular/src/lib/combo/combo.api.ts

@@ -17,6 +17,9 @@ export class IgxComboAPIService {
         this.combo = null;
     }
 
+    public get valueKey() {
+        return this.combo.valueKey !== null && this.combo.valueKey !== undefined ? this.combo.valueKey : null;
+    }
 
     public get item_focusable(): boolean {
         return false;