ComboBox

Extend from $.fn.combo.defaults. Override defaults with $.fn.combobox.defaults.

The combobox display an editable text box and drop-down list, from which the user can select one or multiple values. The user can type text directly into the top of list, or select one or more of present values from the list.

Dependencies

  • combo

Usage Example

Create combobox from <select> element with a pre-defined structure.

Create combobox from <input> markup.

Create combobox using javascript.

Create two dependent comboboxes.

The json data format sample:

Properties

The properties extend from combo, below is the added properties for combobox.

Name Type Description Default
valueField string The underlying data value name to bind to this ComboBox. value
textField string The underlying data field name to bind to this ComboBox. text
groupField string Indicate what field to be grouped. Available since version 1.3.4. null
groupFormatter function(group) return group text to display on group item. Available since version 1.3.4.

Code example:

$('#cc').combobox({
	groupFormatter: function(group){
		return '<span style="color:red">' + group + '</span>';
	}
});
mode string Defines how to load list data when text changed. Set to 'remote' if the combobox loads from server. When set to 'remote' mode, what the user types will be sent as the http request parameter named 'q' to server to retrieve the new data. local
url string A URL to load list data from remote. null
method string The http method to retrieve data. post
data array The list data to be loaded.

Code example:

<input class="easyui-combobox" data-options="
		valueField: 'label',
		textField: 'value',
		data: [{
			label: 'java',
			value: 'Java'
		},{
			label: 'perl',
			value: 'Perl'
		},{
			label: 'ruby',
			value: 'Ruby'
		}]" />
null
queryParams object The additional parameters that will be sent to server when requesting remote data. Available since version 1.4.2. {}
limitToList boolean True to limit the inputed values to the listed items. Available since version 1.5. false
showItemIcon boolean True to display icon of the selected item on the textbox. Available since version 1.4.5. false
groupPosition string The item group position, possible values are: 'static' and 'sticky'. Set this property to 'sticky' to stick the item group to the top of drop-down panel. Available since version 1.4.5. static
filter function Defines how to filter the local data when 'mode' is set to 'local'. The function takes two parameters:
q: the user typed text.
row: the list row data.
Return true to allow the row to be displayed.

Code example:

$('#cc').combobox({
	filter: function(q, row){
		var opts = $(this).combobox('options');
		return row[opts.textField].indexOf(q) == 0;
	}
});
formatter function Defineds how to render the row. The function takes one parameter: row.

Code example:

$('#cc').combobox({
	formatter: function(row){
		var opts = $(this).combobox('options');
		return row[opts.textField];
	}
});
loader function(param,success,error) Defines how to load data from remote server. Return false can abort this action. This function takes following parameters:
param: the parameter object to pass to remote server.
success(data): the callback function that will be called when retrieve data successfully.
error(): the callback function that will be called when failed to retrieve data. 		json loader
loadFilter function(data) Return the filtered data to display. Available since version 1.3.3.

Events

The events extend from combo, below is the added events for combobox.

Name Parameters Description
onBeforeLoad param Fires before a request is made to load data, return false to cancel this load action.

Code example:

// change the http request parameters before load data from server
$('#cc').combobox({
	onBeforeLoad: function(param){
		param.id = 2;
		param.language = 'js';
	}
});
onLoadSuccess none Fires when remote data is loaded successfully.
onLoadError none Fires when an error occurs during loading remote data.
onChange newValue,oldValue Fires when the field value is changed.
onClick record Fires when the user clicks a list item. Available since version 1.5.1.
onSelect record Fires when the user selects a list item.
onUnselect record Fires when the user unselects a list item.

Methods

The methods extend from combo, below is the added or overridden methods for combobox.

Name Parameter Description
options none Return the options object.
getData none Return the loaded data.
loadData data Load the locale list data.
reload url Request the remote list data. Pass the 'url' parameter to override the original URL value.

Code example:

$('#cc').combobox('reload');  // reload list data using old URL
$('#cc').combobox('reload','get_data.php');  // reload list data using new URL
setValues values Set the combobox value array.

Code example:

$('#cc').combobox('setValues', ['001','002']);
setValue value Set the combobox value.

Code example:

$('#cc').combobox('setValue', '001');
clear none Clear the combobox value.
select value Select the specified item.
unselect value Unselect the specified item.
scrollTo value Scroll to the specified item in the drop-down list.

Copyright © 2010-2024 www.jeasyui.com