myapp.ScreenName.EntityName_render = function (element, contentItem) {

    var label = $("<label class='c1ls-label-text msls-label-text'/>");
    label.text(contentItem.displayName);
    label.appendTo($(element));

    var select = $("<select data-role='listview' class='msls-listview'/>");
    select.appendTo($(element));

    $(element).addClass("msls-leaf");

    contentItem.value.oncollectionchange = function () {
        var items = c1ls.getDropDownContent(select, contentItem);
        select.html(items.join("\r\n"));
        select.val(0);
        select.trigger("change");
    };

    c1ls.renderControl(contentItem);
};

Remarks

The list portion of this widget will not render until the screen collection to which it is bound is loaded (that is, when the oncollectionchange event fires). If the underlying query is re-executed with different sort or filter criteria, then the widget will re-render accordingly. The final line of code calls the c1ls.renderControl method to ensure proper rendering in tabs and popups, and to handle collections that have already been loaded.

The utility method c1ls.getDropDownContent parses the child properties defined in the screen designer and returns an array of strings containing <option> tags for each item in the collection.

When viewed on a mobile device, tapping the drop down button opens the collection items in a native choice list.

You can use multiple Drop Down widgets to implement cascading selectors for related tables. For example, if the first widget is bound to the Categories collection, and the second widget is bound to the Products collection, then selecting a category in the first widget would fill the list portion of the second widget with products that belong to the selected category.

The generated code for the Drop Down widget automatically adds an attached label on top of the combo box. The text of the label is taken from the Display Name property specified in the designer.

If desired, you can add a default item to the list in order to set the initial selection to null and force the user to make a “real” selection. Otherwise, the first item in the list will be selected automatically. To implement a default item, replace the generated code with the following code.

contentItem.value.oncollectionchange = function () {
    var options = {
        defaultValue: 0,
        defaultText: "(Select...)"
    };
    var items = c1ls.getDropDownContent(select, contentItem, options);

The defaultValue corresponds to the collection’s primary key field. It is typicallyzero for numeric fields and an empty string for string fields. The defaultText is displayed in the text portion of the combo box when the widget is first rendered. If omitted, an empty string is used.

Copyright (c) GrapeCity, inc. All rights reserved.