285 lines
11 KiB
HTML
285 lines
11 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<title>DHTML Combobox guide and samples</title><link rel="STYLESHEET" type="text/css" href="common/styles.css">
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body>
|
||
|
|
<a name="combo_"><h2 onclick="openFull(this)">dhtmlxCombo Guide and Samples</h2>
|
||
|
|
</a><div class="block">
|
||
|
|
<!--- --->
|
||
|
|
|
||
|
|
<a name="combo_mf"><h3>Main features</h3>
|
||
|
|
</a><div class="block">
|
||
|
|
<li>Multibrowser/Multiplatform support </li>
|
||
|
|
<li>Full controll with JavaScript API</li>
|
||
|
|
<li>Dynamic loading</li>
|
||
|
|
<li>XML support</li>
|
||
|
|
<li>Filtering mode</li>
|
||
|
|
<li>Autocomplete mode</li>
|
||
|
|
<li>Editable mode</li>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<a name="combo_browser"><a name="combo_"><h3>Supported browsers</h3
|
||
|
|
></a></a><div class="block">
|
||
|
|
<li>IE 5.5 and above</li>
|
||
|
|
<li>Mac OS X Safari</li>
|
||
|
|
<li>Mozilla 1.4 and above</li>
|
||
|
|
<li>FireFox 0.9 and above</li>
|
||
|
|
<li>Opera (Xml loading depends on browser version)</li>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<a name="combo_guide"><h3>Working with dhtmlxCombo</h3
|
||
|
|
></a><div class="block">
|
||
|
|
|
||
|
|
<a name="combo_init"><h4>Initializing object</h4
|
||
|
|
></a><div class="block">
|
||
|
|
dhtmlxcombo can be initialized in a plenty of ways. The most simple is initialization from
|
||
|
|
existing selectbox control. All what need to be done
|
||
|
|
<ol>
|
||
|
|
<li>include necessary files</li>
|
||
|
|
<xmp>
|
||
|
|
<script src="../codebase/dhtmlxcommon.js"></script>
|
||
|
|
<script src="../codebase/dhtmlxcombo.js"></script>
|
||
|
|
<link rel="STYLESHEET" type="text/css" href="../codebase/dhtmlxcombo.css">
|
||
|
|
</xmp>
|
||
|
|
<li>set path to image folder ( or just copy image files to your app folder)</li>
|
||
|
|
<xmp>
|
||
|
|
<script>
|
||
|
|
window.dhx_globalImgPath="../codebase/imgs/";
|
||
|
|
</script>
|
||
|
|
</xmp>
|
||
|
|
<li>write native select box code</li>
|
||
|
|
<xmp>
|
||
|
|
<select style='width:200px;' id="combo_zone1" name="alfa1">
|
||
|
|
<option value="1">a00</option>
|
||
|
|
<option value="2">a01</option>
|
||
|
|
</select>
|
||
|
|
</xmp>
|
||
|
|
<li>create dhtmlxcombo from select control</li>
|
||
|
|
<xmp>
|
||
|
|
<script>
|
||
|
|
var z=dhtmlXComboFromSelect("combo_zone1");
|
||
|
|
</script>
|
||
|
|
</xmp>
|
||
|
|
<ul>
|
||
|
|
<li type="square">combo_zone1 - id of select which need to be converted</li>
|
||
|
|
</ul>
|
||
|
|
</ol>
|
||
|
|
<!--- <a href="../samples/combo_init.html">Related sample</a> --->
|
||
|
|
<br/><br/>
|
||
|
|
|
||
|
|
The second approach is to create a new combobox inside some html container.
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>include necessary files</li>
|
||
|
|
<xmp>
|
||
|
|
<script src="../codebase/dhtmlxcommon.js"></script>
|
||
|
|
<script src="../codebase/dhtmlxcombo.js"></script>
|
||
|
|
<link rel="STYLESHEET" type="text/css" href="../codebase/dhtmlxcombo.css">
|
||
|
|
</xmp>
|
||
|
|
<li>write any container code (DIV is most common) </li>
|
||
|
|
<xmp>
|
||
|
|
<div id="combo_zone2" style="width:200px; height:30px;"></div>
|
||
|
|
</xmp>
|
||
|
|
<li>create dhtmlxcombo in HTML container</li>
|
||
|
|
<xmp>
|
||
|
|
<script>
|
||
|
|
var z=new dhtmlXCombo("combo_zone2","alfa2",200);
|
||
|
|
</script>
|
||
|
|
</xmp>
|
||
|
|
<ul>
|
||
|
|
<li type="square">combo_zone2 - id of HTML container</li>
|
||
|
|
<li type="square">alfa2 - named used in form integration</li>
|
||
|
|
<li type="square">200 - width of combobox</li>
|
||
|
|
<li type="square">use 4th parameter in constructor if you need to include images in Combo ("image")</li>
|
||
|
|
</ul>
|
||
|
|
</ol>
|
||
|
|
<!--- <a href="../samples/combo_init.html">Related sample</a> --->
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<a name="combo_adding_options"><h4>Adding options</h4
|
||
|
|
></a><div class="block">
|
||
|
|
Option can be added in next ways
|
||
|
|
<ol>
|
||
|
|
<li>By addOption command</li>
|
||
|
|
<xmp>
|
||
|
|
var z=new dhtmlXCombo("combo_zone3","alfa3",200);
|
||
|
|
z.addOption(value,label,css);
|
||
|
|
</xmp>
|
||
|
|
<ul>
|
||
|
|
<li type="square">value - value of option</li>
|
||
|
|
<li type="square">label - label of option</li>
|
||
|
|
<li type="square">css - css string attached to option, optional</li>
|
||
|
|
</ul>
|
||
|
|
It is possible to add few options at once
|
||
|
|
<xmp>
|
||
|
|
var z=new dhtmlXCombo("combo_zone3","alfa3",200);
|
||
|
|
z.addOption([[value,label,css],[value2,label2,css3],[value3,label3,css3]]);
|
||
|
|
</xmp>
|
||
|
|
<li>From XML file</li>
|
||
|
|
<xmp>
|
||
|
|
var z=new dhtmlXCombo("combo_zone3","alfa3",200);
|
||
|
|
z.loadXML("xml/data.xml");
|
||
|
|
</xmp>
|
||
|
|
Where XML is have next format
|
||
|
|
<xmp>
|
||
|
|
<?php 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>
|
||
|
|
</xmp>
|
||
|
|
Possible attributes of <option> tag:<br>
|
||
|
|
<ul>
|
||
|
|
<li type="square">value - option value</li>
|
||
|
|
<li type="square">selected - if option selected</li>
|
||
|
|
<li type="square">img_src - icon url (also add 4th parameter to combobox constructor - "image")</li>
|
||
|
|
</ul>
|
||
|
|
<!--- <a href="../samples/xml/data.xml">Sample of XML file</a> ||
|
||
|
|
<a href="../samples/xml/dhtmlxcombo.xsd">XML definition file</a> --->
|
||
|
|
<li>From autocomplete xml file</li>
|
||
|
|
<br/>
|
||
|
|
<a href="guide.html#filtering">Plese check "filtration" section for more details</a>
|
||
|
|
<li>From HTML in case of converting from existing select box</li>
|
||
|
|
<br/>
|
||
|
|
</ol>
|
||
|
|
<!--- <a href="../samples/combo_init.html">Related sample</a> --->
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<a name="combo_form"><h4>Integrating with FORM tag</h4
|
||
|
|
></a><div class="block">
|
||
|
|
dhtmlxcombo automatically integrates in surrounding FORM tag.
|
||
|
|
While submitting such form, there are two form wields will be sent to server side
|
||
|
|
<ul>
|
||
|
|
<li type="square">COMBONAME - value of combobox</li>
|
||
|
|
<li type="square">COMBONAME_new_value - true if value is text entered in combobox, false if value one of items from predefined list. of combobox</li>
|
||
|
|
<br/>
|
||
|
|
If combo will be initialized by next command
|
||
|
|
<xmp>
|
||
|
|
var z=new dhtmlXCombo("combo_zone3","alfa3",200);
|
||
|
|
</xmp>
|
||
|
|
server side script will receive fields with names "alfa3" and "alfa3_new_value"
|
||
|
|
</ul>
|
||
|
|
<!--- <a href="../samples/combo_save.html">Related sample (PHP required for showing server side results)</a> --->
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
<a name="combo_filtering"><h4>Filtering</h4
|
||
|
|
></a><div class="block">
|
||
|
|
dhtmlxcombo can work in filtering mode. In such mode the values in list filtered by current entered text in edit control.
|
||
|
|
<ul>
|
||
|
|
To enable filtration next command can be called
|
||
|
|
<xmp>
|
||
|
|
z.enableFilteringMode(true);
|
||
|
|
</xmp>
|
||
|
|
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.
|
||
|
|
<xmp>
|
||
|
|
z.enableFilteringMode(true,"php/complete.php",cache);
|
||
|
|
</xmp>
|
||
|
|
<ul>
|
||
|
|
<li type="square">php/complete.php - path to script</li>
|
||
|
|
<li type="square">cache - true/false - enable/disable caching of script responses ( using "true" recommended )</li>
|
||
|
|
</ul>
|
||
|
|
In described situation, for each change of text in edit control the next url will be called
|
||
|
|
<div class="url">
|
||
|
|
php/complete.php?pos=0&mask=TEXT
|
||
|
|
</div>
|
||
|
|
<ul>
|
||
|
|
<li type="square">TEXT - current text in edit control</li>
|
||
|
|
</ul>
|
||
|
|
The combobox awaits that script response will be a XML in same format which used for initialization.<br/>
|
||
|
|
If you prefer - you can return only part of suggestion, combobox can automatically send additional request and add more data to list of options.
|
||
|
|
<xmp>
|
||
|
|
z.enableFilteringMode(true,"php/complete.php",cache,true);
|
||
|
|
</xmp>
|
||
|
|
The server side script will be called by url
|
||
|
|
<div class="url">
|
||
|
|
php/complete.php?pos=START&mask=TEXT
|
||
|
|
</div>
|
||
|
|
<ul>
|
||
|
|
<li type="square">START - position from which suggestion must be returned.</li>
|
||
|
|
</ul>
|
||
|
|
For all additional sub fetches returned XML must have "add" attribute of main tag
|
||
|
|
<xmp>
|
||
|
|
<?php xml version="1.0" ?>
|
||
|
|
<complete add="true">
|
||
|
|
...
|
||
|
|
</xmp>
|
||
|
|
</ul>
|
||
|
|
<!--- <a href="../samples/combo_filter.html">Related sample (PHP required for dynamic autocomplete)</a> --->
|
||
|
|
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<a name="combo_operation1"><h4>Operations with combobox</h4
|
||
|
|
></a><div class="block">
|
||
|
|
<ol>
|
||
|
|
<li>Show/Hide combo by <span class="command">combo.show(mode);</span></li>
|
||
|
|
<li>Enable/Disable <b><i>readonly</i></b> mode by <span class="command">combo.readonly(mode);</span></li>
|
||
|
|
<li>Enable/Disable <b><i>disabled</i></b> mode by <span class="command">combo.disable(mode);</span></li>
|
||
|
|
</ol>
|
||
|
|
<!--- <a href="../samples/combo_actions.html">Related sample</a> --->
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<a name="combo_operation2"><h4>Operations with comobobox's options</h4
|
||
|
|
></a><div class="block">
|
||
|
|
<ol>
|
||
|
|
<li>Add option - <span class="command">combo.addOption(...);</span></li>
|
||
|
|
<li>Delete option - <span class="command">combo.deleteOption(value);</span></li>
|
||
|
|
<li>Update option - <span class="command">combo.updateOption(oldvalue,value,text,css);</span></li>
|
||
|
|
<li>Get selected value option - <span class="command">combo.getSelectedValue();</span></li>
|
||
|
|
<li>Get selected text - <span class="command">combo.getSelectedText();</span></li>
|
||
|
|
<li>Get text in combo edit - <span class="command">combo.getComboText();</span></li>
|
||
|
|
<li>Set text in combo edit - <span class="command">combo.setComboText();</span></li>
|
||
|
|
<li>Set width of options list - <span class="command">combo.setOptionWidth(width);</span></li>
|
||
|
|
<li>Set height of options list - <span class="command">combo.setOptionHeight(height);</span></li>
|
||
|
|
<li>Enable/Disable <b><i>automatic width</i></b> of options list - <span class="command">combo.enableOptionAutoWidth(mode);</span></li>
|
||
|
|
<li>Enable/Disable <b><i>automatic height</i></b> of options list - <span class="command">combo.enableOptionAutoHeight(mode);</span></li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<!--- <a href="../samples/combo_api.html">Related sample</a> --->
|
||
|
|
</div>
|
||
|
|
<a name="combo_groups"><h4>Groups extension</h4></a><div class="block">
|
||
|
|
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.
|
||
|
|
<ul>
|
||
|
|
Method <b>attachChildCombo(child_combo,url)</b> defines a child combo and sets a path to a server-side script which generates a necessary xml.
|
||
|
|
<xmp>
|
||
|
|
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");
|
||
|
|
</xmp>
|
||
|
|
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 <b>"parent"</b>. Such a functionality allows to form xml stream depending on parent's value using any server-side language.
|
||
|
|
<xmp>
|
||
|
|
combo2.php?parent=PARENT_VALUE
|
||
|
|
</xmp>
|
||
|
|
Child combos can be set in the same container with their parent using <b>setAutoSubCombo(url,name)</b>. 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.
|
||
|
|
<xmp>
|
||
|
|
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")
|
||
|
|
</xmp>
|
||
|
|
</ul>
|
||
|
|
<!--- <a href="../samples/initialization/combo_groups.html">Related sample</a> --->
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div class="copyr">© DHTMLX LTD.</div>
|
||
|
|
</body>
|