Target readers are users (developers).
dhtmlxToolbar v.2.0 is a brand new product which has no
backward compatibility with dhtmlxToolbar v.1.0 either in API or in XML format.
The first steps that need to be taken for dhtmlxToolbar's initialization are the following:
<head>
<script src="[full path to this file]/dhtmlxcommon.js"></script>
<script src="[full path to this file]/dhtmlxtoolbar.js"></script>
<link rel="stylesheet" type="text/css" href="[full path to this file]/dhtmlxtoolbar_dhx_blue.css">
</head>
<div id="toolbar"></div>The next step is to create a new dhtmlXToolbarObject and place it after the <div> element (object) that we've just created:
<script>baseId defines an HTML object on page to which the toolbar is attached (the main toolbar container in the code mentioned above).
var toolbar = new dhtmlXToolbarObject(baseId, skin);
</script>
<script>
var toolbar = new dhtmlXToolbarObject("toolbar");
</script>
Method setIconsPath() should be used to set the full path to the directory, where toolbar image files are located. By means of this method the user is able to set path to the directory, where icons images are stored.
<script>
toolbar.setIconsPath("[full path to icons image files directory]");
</script>
The following predefined skins are available for dhtmlxToolbar users:
<script>
toolbar.loadXML("[path to this file]/file.xml", onLoadFunction);
onLoadFunction = function(){
// will be called if specified
}
</script>
The first parameter of loadXML() method is the path to the XML file, while the second parameter is an optional user-defined handler.
See here for XML Format Template.
<script>
toolbar.loadXMLString("<bar><item....>", onLoadFunction);
onLoadFunction = function(){
// will be called if specified
}
</script>
See here for XML Format Template.
See Items Adding and Removing section for more information.<script>
toolbar.addButton(id,text,imgEnabled,imgDisabled);
toolbar.setTooltip(id,tip);
toolbar.addButton(id,text,imgEnabled,imgDisabled);
toolbar.setTooltip(id,tip);
toolbar.addSeparator(id,pos);
</script>
On Load Function is a user-defined handler that is called after the data was loaded into the object:
toolbar.loadXML("file.xml", function(){
alert("the data is loaded"); // will be invoked after XML file loading (after onXLE if specified)
</script>
<script>Parameters that should be passed are:
toolbar.addButton(id,pos,text,imgEnabled,imgDisabled);
</script>
A Text Item can be added to the toolbar by calling addText() method:
<script>The following parameters should be passed to this method:
toolbar.addText(id,pos,text);
</scrip>
<script>
toolbar.addButtonSelect(id,pos,text,opts,imgEnabled,imgDisabled);
</script>
This line of code should be written before we invoke addButtonSelect() method. This code is very useful, as instead of writing all the arrays for the opts parameter in addButtonSelect() method, we can use opts variable, declared before.<script>
var opts = Array(Array('id1', 'obj', 'option1', 'img1'), Array('sep01', 'sep', '', ''), Array('id2', 'obj', 'option2', 'img2'));
</script>
toolbar.addButtonTwoState(id,pos,text,imgEnabled,imgDisabled);
</script>
The user should pass a number of parameters to this method:
Note: if the user wants the Two-State Button to be created text-free, it's necessary to write an empty string as text parameter.
toolbar.addSeparator(id,pos);
</script>
This method has two input parameters:
<script>
toolbar.addSlider(id,pos,len,valueMin,valueMax,valueNow,textMin,textMax,tip);
</script>
As for input parameters the user should set, they are as follows:
<script>This method has the following input parameters:
toolbar.addInput(id,pos,value,width);
</script>
Note: if the user wants the Input item to be created text-free, it's necessary to write an empty string as value parameter. For example:
<script>
toolbar.addInput("input_new",3,"",100);
</script>
<script>
toolbar.removeItem(itemId);
</script>
Method forEachItem() calls a user-defined function for every existing item in the toolbar passing item's id into it. Using iterator can be very useful in case the user wants all the items to be subjects for the same changes.
<script>
toolbar.forEachItem(function(itemId){});
</script>
For example, let's write the code that will be responsible for disabling all toolbar items:
<script>
function dis() {
toolbar.forEachItem(function(id){
toolbar.disableItem(id);
});
}dis();
</script>
Method forEachListOption() calls a user-defined function for every listed option of a certain Select Button in the toolbar passing listed option's id into it.
<script>
toolbar.forEachListOption(itemId, function doSmth(listOptionId){});
</script>
<script>
toolbar.setPosition(itemId, pos);
var position = toolbar.getPosition(itemId); // returns current item's position
var itemType = toolbar.getType(itemId); // returns item's type
</scriptA
7.3.1 Showing/Hiding Button
To hide/show any button the user should pass button's id to the following methods:
<script>The user has the possibility to check whether any button is visible. The method returns true if the button is visible:
toolbar.showItem(id);
toolbar.hideItem(id);
</script>
<script>
var isVisible = toolbar.isVisible(id); // returns true|false
</script>
7.3.2 Enabling/Disabling Button
Any button in the toolbar can be enabled/disabled by user:
<script>Also the user has the possibility to check whether any button is enabled. This can be done by calling the following method:
toolbar.enableItem(id);
toolbar.disableItem(id);
</script>
<script>The user should pass id of the button that will be checked. The method returns true if the button is enabled, and false if it's disabled.
var isEnabled = toolbar.isEnabled(id); // returns true|false
</scrip>
7.3.3 Setting Button's Text
<script>The user can get button's text using getItemText() method. The method returns the current title text of the button:
toolbar.setItemText(id, text);
</script>
<script>
var text = toolbar.getItemText(id); // returns current item's text
</script>
7.3.4 Setting Button's Image
<script>Button's image whether for the enabled or the disabled state can be easily removed/cleared by means of clearItemImage() and clearItemImageDis() methods to which the user should pass button's id:
toolbar.setItemImage(id,url);
toolbar.setItemImageDis(id,url);
</scrip>
<script>
toolbar.clearItemImage(id);
toolbar.clearItemImageDis(id);
</script>
7.3.5 Setting Buttons's Tooltip
The user can specify the supplementary information regarding any button in the toolbar. setItemToolTip() method takes the following parameters:
<script>The following method can return the current button's tooltip text:
toolbar.setItemToolTip(id,tip);
</script>
<script>
var tip = toolbar.getItemToolTip(id); // returns current button's tooltip text
</script>
All the parameters of the above mentioned methods are the same to those described in Button Settings Manipulations section.
7.4.1 Setting Select Button Width
<script>
toolbar.setWidth(id, width);
</script>
The parameters are:
7.4.2 Adding/Removing Listed Option
<script>Any Listed Option can be easily removed by calling the following method:
toolbar.addListOption(parentId, id, pos, type, text, img);
</script>
<script>
toolbar.removeListOption(parentId,id);
</script>
7.4.3 Showing/Hiding Listed Option
<script>The user has the possibility to check whether any Listed Option is visible. The method returns true if the item is visible:
toolbar.showListOption(parentId, id);
toolbar.hideListOption(parentId, id);
</script>
<script>
var isVisible = toolbar.isListOptionVisible(parentId,id); // returns true|false
</script>
7.4.4 Enabling/Disabling Listed Option
Any Listed Option in the toolbar can be enabled/disabled by user:
<script>Also the user has the possibility to check whether any Listed Option is enabled. This can be done by calling the following method:
toolbar.enableListOption(parentId, id);
toolbar.disableListOption(parentId, id);
</script>
<script>The user should pass parentId and id of the Listed Option that will be checked. The method returns true if the Listed Option is enabled.
var isEnabled = toolbar.isListOptionEnabled(parentId, id); // returns true|false
</script>
7.4.5 Setting Listed Option's Position (moving)
<script>
toolbar.setListOptionPosition(parentId, id, pos);
var pos = toolbar.getListOptionPosition(parentId, id);
</script>
7.4.6 Setting Listed Option's Text
<script>The user can get Listed Option's title using getListOptionText() method. The method returns the current title text of the item:
toolbar.setListOptionText(parentId, id, text);
</script>
<script>
var text = toolbar.getListOptionText(parentId, id); // returns current listed option's title text
</script>
7.4.7 Setting Listed Option's Image
<script>Path to current listed option image can be got like this:
toolbar.setListOptionImage(parentId, id, img);
</script>
<script>Listed Option's image can be easily removed/cleared by means of clearListOptionImage() method to which the user should pass item's parentId and id as parameters:
var listOptionImage = toolbar.getListOptionImage(parentId, id); // returns path to the current listed option image
</script>
<script>
toolbar.clearListOptionImage(parentId, id);
</script>
7.4.8 Setting Listed Option's Tooltip
The user can specify the supplementary information regarding any Listed Option in the toolbar. setListOptionToolTip() method takes the following parameters:
<script>The following method can return the current Listed Option's tooltip text:
toolbar.setListOptionToolTip(parentId, id, tip);
</scri>
<script>
var tip = toolbar.getListOptionToolTip(parentId, id); // returns current listed option's tooltip text
</scri>
7.4.9 Selecting Listed Option
<script>This method doesn't make the listed option selected forever. Another listed option can be easily selected by user from page.
toolbar.setListOptionSelected(parentId, id);
</script>
<script>The parameter the user should pass to this method is id of the Select Button, which listed option's id the user wants to get.
var listOptionId = toolbar.getListOptionSelected(parentId); //returns id of the selected listed option
</script>
7.4.10 Get All Listed Options
<script>
var allListOptions = toolbar.getAllListOptions(parentId); // returns array of all listed options ids
<script>
The following methods that are available for the Button item, can be applied to the Two-State Button item as well:
All the parameters of the above mentioned methods are the same to those described in Button Settings Manipulations section.
7.5.1 Setting Two-State Button State
The user can set one of two states for the Two-State Button with the help of the following method:
<script>The parameters for this method are the following:
toolbar.setItemState(id,state,callEvent);
</script>
<script>
var isPressed = toolbar.getItemState(id); // returns true|false
</script>
The method returns true in case the button is pressed, and false in case the button is released.
7.8.1 Setting Slider's Tooltip Template
Toltip template is applied only to Slider. The tooltip template can be represented in three ways:
setItemToolTipTemplate() method is used to set the tooltip template:
toolbar.setItemToolTipTemplate(id,template);
</script>
This method takes the following parameters:
For example, if the user wants his tooltip to show the text like this: "Current Value is:" plus the changeable text showing slider's values when the thumb is moved, the code must be the following:
toolbar.setItemToolTipTemplate("slider","Current Value is:+%v");
</script>
The following method can return current slider's tooltip template:
var template = toolbar.getItemToolTipTemplate(id); // returns current slider's tooltip text
</script>
7.8.2 Setting Slider's Value
<script>The parameters are as follows:
toolbar.setValue(id,value,callEvent);
</script>
<script>
var value = toolbar.getValue(id); // returns slider's current value
</script>
7.8.3 Setting Slider's Minimum Value
<script>The following parameters should be passed to this method:
toolbar.setMinValue(id,value,label);
</script>
<script>Slider's current minimum value can be got using getMinValue() method:
toolbar.setMinValue("slider",25,"");
</script>
<script>This method returns the following Array: value, label.
var data = toolbar.getMinValue(id); // returns slider's current minimum value
</script>
7.8.4 Setting Slider's Maximum Value
<script>The following parameters should be passed to this method:
toolbar.setMaxValue(id,value,label);
</script>
<script>Slider's current maximum value can be got using getMaxValue() method:
toolbar.setMaxValue("slider",25,"");
</script>
<script>This method returns the following Array: value, label.
var data = toolbar.getMaxValue(id); // returns current maximum value
</script>
7.9.1 Getting Input's Width
<script>
var width = toolbar.getWidth(id); // returns current input's width
</script>
To do this he can use attachEvent() method with the following parameters:
<script>Note: the names of the events are case-insensitive.
toolbar.attachEvent(evName, evHandler);
</script>
<script>
toolbar.attachEvent("onClick", function(id){});
</script>
Now let's attach an event handler for "onClick" event:
toolbar.attachEvent("onClick", function(id){
<script>
toolbar.attachEvent("onStateChange", function(id, state){});
</script>
<script>
toolbar.attachEvent("onStateChange", function(id, value){});
</script>
This event occurs before data loading from XML has started and just before onLoadFunction.
onXLS event can call user-defined handlers (if there are any):
<script>
toolbar.attachEvent("onXLS", function(){});
</script>
<script>
toolbar.attachEvent("onXLE", function(){});
</script>
<script>
toolbar.attachEvent("onEnter", function(id, value){});
</script>
This section is created in order to give the user the idea of XML Format Template. It aims at helping users in creating XML files for dhtmlxToolbar initialization.
<?xml version="1.0"?>
<toolbar> a top xml tag, mandatory
<item id="new" type="button" img="new.gif" imgdis="new_dis.gif"/> a button item with images for enabled/disabled states only;each item must have a unique ID
<item id="save" type="button" text="Save" img="save.gif" imgdis="save_dis.gif"/> a button item with text, images for enabled/disabled states
<item id="open" type="button" text="Open"/> a button item with text only
<item id="sep01" type="separator"/> a separator item
<item id="undo" type="button" img="undo.gif" imgdis="undo_dis.gif" title="Undo"/> a button item with tooltip
<item id="redo" type="button" img="redo.gif" imgdis="redo_dis.gif" title="Redo"/>
<item id="cut" type="button" img="cut.gif" imgdis="cut_dis.gif" title="Cut" enabled="false"/> a disabled button
<item id="copy" type="button" img="copy.gif" imgdis="copy_dis.gif" title="Copy"/>
<item id="paste" type="button" img="paste.gif" imgdis="paste_dis.gif" title="Paste"/>
<item id="sep02" type="separator"/>
<item id="form" type="buttonTwoState" img="form.gif" imgdis="form_dis.gif" title="Form"/> a two-state button with images for enabled/disabled states, tooltip
<item id="filter" type="buttonTwoState" img="filter.gif" imgdis="filter_dis.gif" text="Filter" title="Filter"/> a two-state button with images for enabled/disabled states, text, tooltip
<item id="any_word" type="buttonTwoState" text="Any Word" selected="true"/> a pressed two-state button with text only
<item id="txt_1" type="buttonInput"/> an input button
<item id="txt_2" type="buttonInput" value="Filter Text" width="60" title="type the text here"/> an input button with predifined initial value, width, and tooltip
<item id="sep1" type="separator"/>
<item id="history" type="buttonSelect" text="History"> a select button with text only
<item type="button" id="8_1" text="Today"/> a listed option with text only
<item type="button" id="8_2" text="Yesturday" selected="true"/> a preselected listed option
<item type="button" id="8_3" text="Last Week"/>
<item type="button" id="8_4" text="Last Month"/>
<item id="8_sep0" type="separator"/> a listed option - separator
<item type="button" id="8_5" img="icon_more.gif" text="More..."/> a listed option with image for the enabled state, text
</item>
<item id="sep2" type="separator"/>
<item id="page_setup" type="buttonSelect" img="page_setup.gif" imgdis="page_setup_dis.gif" text="Page"> a select button with text, images for enabled/disabled states
<item type="button" id="9_11" text="Layout"/>
<item type="button" id="9_12" text="Management"/>
</item>
<item id="print" type="buttonSelect" img="print.gif" imgdis="print_dis.gif" title="Print"> a select button with images for enabled/disabled states, tooltip
<item type="button" id="9_1" text="Page"/>
<item type="button" id="9_2" text="Selection"/>
<item id="9_sep0" type="separator"/>
<item type="button" id="9_3" text="Custom..."/>
</item>
<item id="sep3" type="separator"/>
<item id="slider" type="slider" length="70" valueMin="10" valueMax="100" valueNow="70" textMin="10 MBit" textMax="100 MBit" toolTip="%v MBit"/> a slider item
mandatory slider's parameters: length - length in px, minValue (int), maxValue (int), valueNow - current value (set by the default, int)
optional slider's parameters: textMin - label for minValue, textMax - lavel for maxValue, toolTip - tolltip template (%v will be replaced with the cureent value)
<item id="sep4" type="separator"/>
<item id="text" type="text" text="dhtmlxToolbar Demo"/> a text item
</toolbar>