## dhtmlxCombo Guide and Samples

### Main features

- Multibrowser/Multiplatform support
- Full controll with JavaScript API
- Dynamic loading
- XML support
- Filtering mode
- Autocomplete mode
- Editable mode

### Supported browsers

- IE 5.5 and above
- Mac OS X Safari
- Mozilla 1.4 and above
- FireFox 0.9 and above
- Opera (Xml loading depends on browser version)

### Working with dhtmlxCombo

#### Initializing object

dhtmlxcombo can be initialized in a plenty of ways. The most simple is initialization from existing selectbox control. All what need to be done

1. include necessary files

    		<script src="../codebase/dhtmlxcommon.js"></script>
    		<script src="../codebase/dhtmlxcombo.js"></script>
    		<link rel="STYLESHEET" type="text/css" href="../codebase/dhtmlxcombo.css">

2. set path to image folder ( or just copy image files to your app folder)

    		<script>
    			window.dhx_globalImgPath="../codebase/imgs/";
    		</script>

3. write native select box code

    		<select style='width:200px;'  id="combo_zone1" name="alfa1">
    				<option value="1">a00</option>
    				<option value="2">a01</option>
    		</select>

4. create dhtmlxcombo from select control

    		<script>
    			var z=dhtmlXComboFromSelect("combo_zone1");
    		</script>

- combo_zone1 - id of select which need to be converted

The second approach is to create a new combobox inside some html container.

1. include necessary files

    		<script src="../codebase/dhtmlxcommon.js"></script>
    		<script src="../codebase/dhtmlxcombo.js"></script>
    		<link rel="STYLESHEET" type="text/css" href="../codebase/dhtmlxcombo.css">

2. write any container code (DIV is most common)

    		<div id="combo_zone2" style="width:200px; height:30px;"></div>

3. create dhtmlxcombo in HTML container

    		<script>
    			var z=new dhtmlXCombo("combo_zone2","alfa2",200);
    		</script>

- combo_zone2 - id of HTML container
- alfa2 - named used in form integration
- 200 - width of combobox
- use 4th parameter in constructor if you need to include images in Combo ("image")

#### Adding options

Option can be added in next ways

1. By addOption command

    				var z=new dhtmlXCombo("combo_zone3","alfa3",200);
    				z.addOption(value,label,css);

- value - value of option
- label - label of option
- css - css string attached to option, optional

It is possible to add few options at once

    				var z=new dhtmlXCombo("combo_zone3","alfa3",200);
    				z.addOption([[value,label,css],[value2,label2,css3],[value3,label3,css3]]);

2. From XML file

    				var z=new dhtmlXCombo("combo_zone3","alfa3",200);
    				z.loadXML("xml/data.xml");

Where XML is have next format

    				<?xml version="1.0" ?>
    				<complete>
    					<option value="1">one</option>
    					<option value="2">two</option>
    					<option value="3">three</option>
    					<option value="4">four</option>
    					<option value="5">five</option>
    					<option value="6">six</option>
    					<option value="7">seven</option>
    					<option value="8">eight</option>
    					<option value="9">nine</option>
    					<option value="10">ten</option>
    				</complete>

Possible attributes of <option> tag:

- value - option value
- selected - if option selected
- img_src - icon url (also add 4th parameter to combobox constructor - "image")

3. From autocomplete xml file
Plese check "filtration" section for more details
4. From HTML in case of converting from existing select box

#### Integrating with FORM tag

dhtmlxcombo automatically integrates in surrounding FORM tag. While submitting such form, there are two form wields will be sent to server side

- COMBONAME - value of combobox
- COMBONAME_new_value - true if value is text entered in combobox, false if value one of items from predefined list. of combobox
If combo will be initialized by next command

    			var z=new dhtmlXCombo("combo_zone3","alfa3",200);

server side script will receive fields with names "alfa3" and "alfa3_new_value"

#### Filtering

dhtmlxcombo can work in filtering mode. In such mode the values in list filtered by current entered text in edit control.

To enable filtration next command can be called

    			z.enableFilteringMode(true);

By default combobox uses options which already loaded in it, but it is possible to define the external script which will be called for generating list of suggestion.

    			z.enableFilteringMode(true,"php/complete.php",cache);

- php/complete.php - path to script
- cache - true/false - enable/disable caching of script responses ( using "true" recommended )

In described situation, for each change of text in edit control the next url will be called
php/complete.php?pos=0&mask=TEXT

- TEXT - current text in edit control

The combobox awaits that script response will be a XML in same format which used for initialization.
If you prefer - you can return only part of suggestion, combobox can automatically send additional request and add more data to list of options.

    			z.enableFilteringMode(true,"php/complete.php",cache,true);

The server side script will be called by url
php/complete.php?pos=START&mask=TEXT

- START - position from which suggestion must be returned.

For all additional sub fetches returned XML must have "add" attribute of main tag

    			<?xml version="1.0" ?>
    			<complete add="true">
    				...

#### Operations with combobox

1. Show/Hide combo by combo.show(mode);
2. Enable/Disable readonly mode by combo.readonly(mode);
3. Enable/Disable disabled mode by combo.disable(mode);

#### Operations with comobobox's options

1. Add option - combo.addOption(...);
2. Delete option - combo.deleteOption(value);
3. Update option - combo.updateOption(oldvalue,value,text,css);
4. Get selected value option - combo.getSelectedValue();
5. Get selected text - combo.getSelectedText();
6. Get text in combo edit - combo.getComboText();
7. Set text in combo edit - combo.setComboText();
8. Set width of options list - combo.setOptionWidth(width);
9. Set height of options list - combo.setOptionHeight(height);
10. Enable/Disable automatic width of options list - combo.enableOptionAutoWidth(mode);
11. Enable/Disable automatic height of options list - combo.enableOptionAutoHeight(mode);

#### Groups extension

Groups extension allows to organize groups of combos with parent-child dependence, when options of child combos are determined by the value of selected option in its parent.

Method attachChildCombo(child_combo,url) defines a child combo and sets a path to a server-side script which generates a necessary xml.

    		var z2=new dhtmlXCombo("combo_zone2","alfa2",200);

    		var z=new dhtmlXCombo("combo_zone","alfa1",200);
    		z.enableFilteringMode(true);
    		z.attachChildCombo(z2,"combo2.php");
    		z.loadXML("combo1.xml");

When some option is selected in the parent combo. The server-side script ("combo2.php" in the example above) recieves the value of this option with the request; the name of this parameter is "parent". Such a functionality allows to form xml stream depending on parent's value using any server-side language.

    		combo2.php?parent=PARENT_VALUE

Child combos can be set in the same container with their parent using setAutoSubCombo(url,name). In this case, they inherit all methods and properties of the parent, except the server-side script and the name which are set in the setAutoSubCombo method.

    		var z1=new dhtmlXCombo("combo_zone1","alfa1",200);
    	  	z1.enableFilteringMode(true);
    		z1.loadXML("combo1.xml")
    		var z2 =  z1.setAutoSubCombo("combo2.php","alpha2")
    		var z3 =  z2.setAutoSubCombo("combo3.php","alpha3")

© DHTMLX LTD.