dxLookup

The Lookup widget allows an end-user to select predefined values from a lookup window.

View Demo

Common Tasks

The Lookup widget supports the core functionality available to all Collection Container widgets, Editor widgets, and Overlay widgets.

Lookup as an Editor

The Lookup widget is an editor widget and supports the following common principles of working with editor widgets.

Lookup as an Overlay Widget

The Lookup widget consists of an input element, which displays the current value and a list of available values. The value list is displayed within an overlay window. The Lookup widget supports options common for all overlay widgets, which enables you to adjust the overlay window parameters. Thus, the widget enables you to perform the following overlay specific tasks.

Lookup as a Collection Container

The Lookup widget operates the collection of items. Thus, it provides an ability to perform the following tasks common for collection container widgets.

NOTE
The Lookup widget does not support handling item events.

Adjust Inner List Parameters

The Lookup widget displays the collection of available values within the inner List widget. Some options of this list are mapped to the Lookup widget options, which enables you to adjust the list parameters. The inner list can display items in a grouped list and load them by pages.

  • Grouping

    To display items by groups, set the grouped option to true. The default group template supports the following array structure.

    JavaScript
    var lookupData = [
        {
            key: "group1 caption",
            items: [
                { text: "item1" },
                { text: "item2" },
                { text: "item3" }
            ]
        },
        {
            key: "group2 caption",
            items: [
                { text: "item1" },
                { text: "item2" },
                { text: "item3" }
            ]
        },
        {
            key: "group3 caption",
            items: [
                { text: "item1" },
                { text: "item2" },
                { text: "item3" }
            ]
        }
    ];
    var lookupOptions = {
        dataSource: new DevExpress.data.DataSource(lookupData),
        grouped: true
    }

    For more information on list grouping options, refer to the List description.

  • Paging

    To display the Lookup items by pages, modify paging options of the DataSource instance associated with the widget. Set the paginate option to true and specify the number of items per page using the pageSize option.

    JavaScript
    var lookupData = new DevExpress.data.DataSource({
        store: [ . . . ], //Specifies data associated with the DataSource instance
        paginate: true, //Specifies whether or not DataSource loads data by pages
        pageSize: 10 //Specifies the number of items contained in a single page
    });
    var lookupOptions = {
        dataSource: lookupData
    };

Similarly to the List widget, Lookup can load the next page automatically when the list is scrolled to the bottom, or when a user clicks the Next button located at the bottom of the list. Use the pageLoadMode option to specify the page loading mode. You can also specify the text displayed on the "next" button using the nextButtonText option.

For more information on paging, refer to the List description.

Specific Tasks

In addition to tasks that are common for editors, overlays and collection containers, the Lookup widget enables you to perform the following lookup specific tasks.

Tweak for an Item Structure

If a lookup item is a string value, this value is displayed in the lookup input element and held in the value option. In most cases, a lookup item is an object containing various properties. In this case, you should specify which property value is displayed in the lookup input element and which one should be accessed using the value option.

The displayExpr option specifies the property of an item object whose value is displayed in the lookup input element. You can access the displayed value using the displayValue option.

JavaScript
var lookupOptions = {
    dataSource: lookupData,
    displayExpr: "text"
}

If a list item template is not specified, each list item displays a value of the property specified by the displayExpr option.

The valueExpr option specifies the item object property whose value is accessed using the value option. You can pass "this" to the valueExpr option to access the entire item object.

JavaScript
var lookupOptions = {
    dataSource: lookupData,
    displayExpr: "text",
    valueExpr: "population"
}
See Also

Use Search

An end-user can use the incremental search to quickly find the required item within the list of available values. The searchEnabled option specifies the availability of the search field.

JavaScript
var lookupOptions = {
    dataSource: lookupData,
    displayExpr: "name",
    searchEnabled: true
}

The widget searches the required items by the value of the property specified using the displayExpr option. For example, if the displayExpr option is set to "name", the widget displays items whose name property value satisfies the search criterion.

The widget starts searching after the specified timeout that occurs after an end-user has modified the search box value has expired, provided that the length of the string typed in the search field is more than or equal to the minimum length specified using the minSearchLength option. You can specify the timeout using the searchTimeout option.

Use the Additional Controls

The Lookup widget provides an ability to use additional buttons to apply and cancel the current choice and clear widget value. Specify the availability of these buttons using the showCancelButton and showClearButton options respectively.

JavaScript
var lookupOptions = {
    dataSource: lookupData,
    displayExpr: "name",
    searchEnabled: true,
    showCancelButton: true,
    showClearButton: true
}

You can also use the cancelButtonText and clearButtonText options to specify the text displayed by each button.

Specify The Popup Window Appearance

The Lookup widget can display the popup window as a standard overlay window (by default) or a popover pointing at the lookup input element. To display the popup window as a popover, set the usePopover option to true. The popover mode is available if the full-screen mode is disabled.

JavaScript
var lookupOptions = {
    dataSource: lookupData,
    fullScreen: false,
    usePopover: true
}

The widget enables you to specify the title text for the popup window using the title option.

JavaScript
var lookupOptions = {
    dataSource: lookupData,
    title: "Available values"
}

You can also specify a custom template for the popup window title using the titleTemplate option. For detailed information on using templates, refer to the Customize Widget Element Appearance topic.

See Also

Keyboard Support

An end-user can use the Enter key to show the popup window. When the window is displayed, a user can move focus from the text field to the list and back using Tab and Shift+Tab shortcuts.