Configuration

An object defining configuration options for the dxLookup widget.

activeStateEnabled

A Boolean value specifying whether or not the widget changes its state when interacting with a user.

Type: Boolean
Default Value: true

This option is used when the widget is displayed on a platform whose guidelines include the active state change for widgets.

Show Example:
jQuery

animation

An object defining the animation options of the widget.

Type: animation configuration

The option takes on the following object by default.

JavaScript
animationOptions = { 
    show: { 
        type: "fade", 
        to: 1
    }, 
    hide: { 
        type: "fade", 
        to: 0
    } 
}

cancelButtonText

The text displayed on the Cancel button.

Type: String
Default Value: Globalize.localize("Cancel")

Show Example:
jQuery

clearButtonText

The text displayed on the Clear button.

Type: String
Default Value: Globalize.localize("Clear")

Show Example:
jQuery

clickAction

An action performed when a widget is clicked.

Type: Action
Default Value: null

Show Example:
jQuery

contentReadyAction

An action performed when the widget сontent is ready.

Type: Action
Default Value: null

dataSource

A data source used to fetch data to be displayed by the widget.

Default Value: null

You can assign an array directly to this option as well as use the Data Layer provided by the PhoneJS library.

If the dxLookup widget works with the data accessed via a DataSource instance wrapping a CustomStore, pay attention to the byKey option of the CustomStore instance, which is required for this widget. This option takes on a function used to get an item by key.

To display widget items, a default template can be used. This template is based on the data source fields that are listed below. Alternatively, you can implement a custom item template. For details, refer to the Customize Widget Item Appearance topic.

Show Example:
jQuery

disabled

A Boolean value specifying whether or not the widget can respond to user interaction.

Type: Boolean
Default Value: false

Create an observable variable and assign it to this option to specify the availability of the widget at runtime.

Show Example:
jQuery

displayExpr

Specifies the name of the data source item field whose value is displayed by the widget.

Type: String
Default Value: "this"

If the Lookup item is a simple object holding a value (string, numeric, Boolean, etc.), assign 'this' to the displayExpr option. If the item is a plain object item, assign the required field name or path to the option.

Show Example:
jQuery

displayValue

Returns the value currently displayed by the widget.

Type: String
Default Value: undefined

The value you pass to this option does not affect widget behavior. Pass an observable variable to this option to get the value currently displayed by the widget.

Show Example:
jQuery

doneButtonText

The text displayed on the Done button.

Type: String
Default Value: Globalize.localize("Done")

Show Example:
jQuery

fullScreen

A Boolean value specifying whether or not to display the lookup in full-screen mode.

Type: Boolean
Default Value: false
Default for windows phone 8: false
Default for iPhone: false

Show Example:
jQuery

height

Specifies the height of the widget.

Type: Number|String|function
Return Value: Number|String
The widget height.
Default Value: undefined

The option can hold the following types of values.

  • numeric - the height of the widget in pixels
  • string - a CSS measurement of the widget height (e.g., "55px", "80%", "auto" and "inherit")
  • function - a function returning the widget height (e.g., height:function(){ return baseHeight - 10 + "%"; })

hiddenAction

An action performed after the widget has been hidden.

Type: Action
Default Value: null

itemRender

A function used to render collection items in the lookup list.

Type: function
Function parameters:
itemData: Object
An object representing the item to be rendered.
itemIndex: Number
The index of the item to be rendered.
itemElement: Object
An HTML element containing the item to be rendered.
Return Value: String|DOM Node|jQuery
An HTML string, Element, or jQuery object representing the rendered item.
Default Value: null

As in all container widgets in PhoneJS, lookup items are displayed by a default HTML template. This template is based on certain fields of the data source. You can define a custom item template that will use specific fields of the data source. To learn more about item templates, refer to the Customize Widget Item Appearance topic.

Implement the itemRender function to provide a custom template for lookup items. This function is called each time a collection item of the widget is rendered. The following data is passed as function parameters.

  1. itemData - An object representing the rendered item
  2. itemIndex - An index of the rendered item
  3. itemElement - A container element containing the rendered item

Return an HTML string, Element, or jQuery object representing the rendered item.

Alternatively, you can define the dxTemplate markup component within the widget element and set its option name to item. In this case, the markup enclosed in the dxTemplate component will automatically be applied as an item template. In addition, you may need to define several item templates and apply each of these when required. In this instance, use the itemTemplate option to set the required template.

Refer to the Customize Widget Item Appearance topic to learn more about ways to render collection items.

Show Example:
jQuery

items

Specifies the array of items to be displayed by the widget.

Type: Array

Use this option instead of the dataSource option if you use a simple array as a data source.

itemTemplate

The template to be used for rendering items in the lookup list.

Type: String|function|DOM Node|jQuery
Return Value: String|jQuery
A template name or a template container.
Default Value: null

As in all container widgets in PhoneJS, lookup items are displayed by a default HTML template. This template is based on certain fields of the data source. You can define a custom item template that will use specific fields of the data source. To learn more about item templates, refer to the Customize Widget Item Appearance topic.

In a simple case, you can define a single custom template for lookup items using the dxTemplate markup component within the widget's container. Set the name option of this component to 'item'. In this instance, this template will automatically be used as an item template, and you do not have to specify the itemTemplate option.

However, in some cases you may need to have several custom item templates defined within the widget's container and apply each of them in different scenarios. In this instance, use one of the following ways to set the required template to the itemTemplate option.

  • Assign a string representing the name of the required template
  • Assign a function that returns the name of the template as a result of a certain logic

When you have several collection widgets, you may need to define a common template for them. For this purpose, factor out a template into a separate element as demonstrated below.

HTML
<script type="text/html" id="person-template">
    <h3 data-bind="text: name"></h3>
    <p>Address: <span data-bind="text: address"></span></p>
</script>

To set the common template as a lookup item template, assign one of the following values to the itemTemplate option.

  • Assign a jQuery object representing the template's container
  • Assign a DOM Node representing the template's container
  • Assign a function that returns the jQuery object or a DOM Node representing the template's container
Show Example:
jQuery

minFilterLength

The minimum number of characters that must be entered into the search box to start a search.

Type: Number
Default Value: 0

noDataText

The text displayed by the widget if there are no items satisfying the specified search condition.

Type: String
Default Value: "No data to display"

Show Example:
jQuery

placeholder

The text displayed by the widget when nothing is selected.

Type: String
Default Value: "Select..."

Show Example:
jQuery

popupHeight

The height of the widget popup element.

Type: Number|String|function
Return Value: Number|String
The required height of the widget popup element.
Default Value: function() { return $(window).height() * 0.8 }
Default for iPad: function() { return Math.min($(window).width(), $(window).height()) * 0.4; },

Note that the option affect the actual popup size only if the fullScreen option is set to false. Otherwise, the popup is shown in a full screen mode anyway.

Show Example:
jQuery

popupWidth

The width of the widget popup element.

Type: Number|String|function
Return Value: Number|String
The required width of the widget popup element.
Default Value: function() {return $(window).width() * 0.8 }
Default for iPad: function() { return Math.min($(window).width(), $(window).height()) * 0.4; }

Note that the option affects the actual popup size only if the fullScreen option is set to false. Otherwise, the popup is shown in a full screen mode anyway.

Show Example:
jQuery

searchEnabled

A Boolean value specifying whether or not the search bar is visible.

Type: Boolean
Default Value: true

To specify a field by which to search items, assign the required field name to the searchExpr configuration option of the DataSource object passed to the dataSource option of the widget.

JavaScript
var dataSource = new DevExpress.data.DataSource({
    store: myStore,
    searchExpr: "firstName"
});

If you need to search items by several field values, assign an array of field names to the searchExpr option of the DataSource.

JavaScript
var dataSource = new DevExpress.data.DataSource({
    store: myStore,
    searchExpr: ["firstName", "lastName"]
});

For more information on searching, refer to the Search Api section of the Data Layer article.

Show Example:
jQuery

searchPlaceholder

The text that is provided as a hint in the lookup's search bar.

Type: String
Default Value: "Search"

Show Example:
jQuery

searchTimeout

Specifies the time delay, in milliseconds, after the last character has been typed in, before a search is executed.

Type: Number
Default Value: 1000

showCancelButton

Specifies whether to display the Cancel button in the lookup window.

Type: Boolean
Default Value: true
Default for windows phone 8: false

The Cancel button cancels the attempt to change the lookup widget value.

Show Example:
jQuery

showClearButton

Specifies whether or not to display the Clear button in the lookup window.

Type: Boolean
Default Value: false

The Clear button clears the currently chosen lookup value. The lookup window closes and the text specified by the placeholder option is shown in the lookup editor.

Show Example:
jQuery

showDoneButton

Specifies whether to display the Done button in the lookup window.

Type: Boolean
Default Value: false

The Done button submits the selection in the lookup window.

Show Example:
jQuery

shownAction

An action performed after the widget is shown.

Type: Action
Default Value: null

title

The title of the lookup window.

Type: String
Default Value: ""

Show Example:
jQuery

usePopover

Specifies whether or not to show lookup contents in a dxPopover widget.

Type: Boolean
Default Value: false

Show Example:
jQuery

value

The currently selected value in the widget.

Type: Object
Default Value: undefined

This option returns a value of the specified field of the currently selected item object. The field whose value is returned by the value option is specified via the valueExpr option.

Show Example:
jQuery

valueChangeAction

An action performed after the value of the widget has been changed.

Type: Action
Default Value: null

Show Example:
jQuery

valueExpr

Specifies the name of a data source item field whose value is held in the value configuration option.

Type: String
Default Value: null

Show Example:
jQuery

visible

A Boolean value specifying whether or not the widget is visible.

Type: Boolean
Default Value: true

width

Specifies the width of the widget.

Type: Number|String|function
Return Value: Number|String
The widget width.
Default Value: undefined

The option can hold the following types of values.

  • numeric - the widget width in pixels
  • string - a CSS measurement of the widget width (e.g., "55px", "80%", "auto" and "inherit")
  • function - the function returning the widget width (e.g., width:function(){ return baseWidth - 10 + "%"; })