Migrating to the new combo

Topic overview

This topic aims to help with migration from old combo to the new one. Different scenarios are viewed and how they were done before and how they can be done now.

In this topic

This topic contains the following sections:

1. General changes
2. Options changes
3. New options
4. API Methods changes
5. New API methods
6. Theming changes
7. Event changes
8. New events
9. Knockout Integration changes
10. Knockout Backwards compitability
11. Requirements

General changes

Options changes

*We tried hard to ensure behavioral parity between the old and new combo, but some things we could not complete for 15.1. If these behaviors are crucial to your solution, and you want to upgrade to 15.1, please contact us.

New options

See all options

API Methods changes

New API Methods

See all API methods

Theming changes

<style>
      input#combo::-webkit-input-placeholder {
        color: red;
      }
</style>

Note: Depending on the browser (:-moz-placeholder, :-ms-input-placeholder);

Event changes

New events

See all events

Knockout Integration changes

One of the changes, introduced with the new igCombo control, is the one that the combo is considered as control that accepts values only from its list. There isn't an option to allow custom values in the igCombo, as it was in the old one, which leads to a need for a different work process in the Knockout extension. This means that the only time, when the igCombo can notify the View-Model about a change, is when an item is selected/deselected and the selected items collection is changed. In such cases, some of the old Knockout extension options are not necessary anymore and some other need to be introduced. The following changes have been made to integrate the igCombo with its Knockout extension.

New options

Removed options

Before

<script type="text/javascript">
var model = [
    { name: "Adam Sandler", id: "nm0001191" },
    { name: "Brooke Shields", id: "nm0000222" },
    { name: "Charles Chaplin", id: "nm0000122" },
];
var viewModel = new ViewModel(model);
 function ViewModel(actorsList) {
    this.selectedActor = ko.observable(actorsList[0].name);
 }
</script>
<span id="comboActors" data-bind="igCombo: {
    text: selectedActor,
    textKey: 'name',
    valueKey: 'id'
}"></span>

Now

<script type="text/javascript">
var model = [
    { name: "Adam Sandler", id: "nm0001191" },
    { name: "Brooke Shields", id: "nm0000222" },
    { name: "Charles Chaplin", id: "nm0000122" },
];
var viewModel = new ViewModel(model);
 function ViewModel(actorsList) {
    this.selectedActor = ko.observable(actorsList[0].name);
    this.selectedActorNew = ko.observableArray([actorsList[0].id]);
    this.selectionChanged = function(e, args) {
        this.selectedActor(args.items[0].data.name);
    }
 }
</script>
<span id="comboActors" data-bind="igCombo: {
    selectedItems: selectedActorNew,
    textKey: 'name',
    valueKey: 'id',
    selectionChanged: selectionChanged
}"></span>

Note: This will only work, when there is a change from the igCombo to the View-Model.

Knockout Backwards compatibility

The new combo and its knockout extensions have been redesigned and therefore there are some changes in architecture. The combo selection collection was designed to only accept values that are available in its drop down items. The knockout extension follows that pattern and the observable item, which monitors the changes in the combo, is now an array of the selected items. In the previous version the extension was monitoring the combo filed. With the new implementation one can monitor multiple selected items and not only a single selection.

This architectural approach means that one cannot bind igCombo with an HTML input element for example, because the input observable cannot be defined as an observable array. Our igEditors and their extensions, in contrast, are designed to work with HTML inputs. If one needs a way to combine igCombo with HTML inputs, one can use the approach demonstrated in the previous section (Knockout Integration Changes). The code in this section demonstrates a custom solution, which allows the use of the new version of the igCombo and Knockout extension, but without the need to change the code in your ViewModel and View. This polyfill is suitable for situations when you want to upgrade to the latest version of IgniteUI but cannot change your current code to handle selection notifications.

The following binding handler should be defined after the igCombo knockout handlers are loaded:

<script type="text/javascript">
ko.bindingHandlers.igComboPolyfill = {
    init: function (element, valueAccessor) {
        var combo = $(element),
            isMultiple = valueAccessor().multiSelection ? valueAccessor().multiSelection.enabled : false;

        ko.utils.registerEventHandler(element, "igcomboselectionchanged", function (evt, ui) {
            var item = ui.items[0], dataItem, newText, newValue;

            if (isMultiple) {
                if (ko.isObservable(valueAccessor().text)) {
                    valueAccessor().text(combo.igCombo("text"));
                }
            } else {
                if (item !== undefined) {
                    dataItem = item.data;
                    if (ko.isObservable(dataItem)) {
                        dataItem = dataItem();
                    }
                    newText = dataItem[valueAccessor().textKey];
                    newValue = dataItem[valueAccessor().valueKey];

                    if (ko.isObservable(valueAccessor().text)) {
                        if (ko.isObservable(newText)) {
                            newText = newText();
                        }
                        valueAccessor().text(newText);
                    }
                    if (ko.isObservable(valueAccessor().value)) {
                        if (ko.isObservable(newValue)) {
                            newValue = newValue();
                        }
                        valueAccessor().value(newValue);
                    }
                }
            }
        });

        ko.utils.registerEventHandler(element, "igcombodropdownclosed", function (evt, ui) {
            if (isMultiple) {
                if (ko.isObservable(valueAccessor().text)) {
                    valueAccessor().text(combo.igCombo("text"));
                }
            }
        });

        ko.applyBindingsToNode(element, { igCombo: valueAccessor() });
    },
    update: function (element, valueAccessor) {
        var combo = $(element),
            value = valueAccessor().text();

        if (combo.igCombo("text") !== value) {
            $(element).igCombo("text", value);
        }
    }
};
</script>

Then you can use the same logic as before and define the observable item as a string:

Before

<script type="text/javascript">
var model = [
    { name: "Adam Sandler", id: "nm0001191" },
    { name: "Brooke Shields", id: "nm0000222" },
    { name: "Charles Chaplin", id: "nm0000122" },
];
var viewModel = new ViewModel(model);
 function ViewModel(actorsList) {
    this.selectedActor = ko.observable(actorsList[0].name);
 }
</script>
<span id="comboActors" data-bind="igCombo: {
    text: selectedActor,
    textKey: 'name',
    valueKey: 'id'
}"></span>
<input type="text" data-bind="value: selectedActor"/><br />

jQuery requirements