dhtmlxToolbar 2.0 Guide and Code Samples

1. Introduction

1.1 Scope of the Document

This document describes dhtmlxToolbar component of v.2.x, defines its methods and global parameters. This documentation is created to give users full understanding of every feature of this component, and also to enable users to implement this component quickly and easily.

1.2 Target Readers

Target readers are users (developers).

1.3 Note for users of dhtmlxToolbar 1.0

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.

2. What is dhtmlxToolbar

dhtmlxToolbar 2.0 is a second version of dhtmlxToolbar component, which provides an easy way to add a professional toolbar to user's projects. A toolbar contains buttons/items for the most commonly-used commands in an application. This component is highly customizable and supports a wide range of features.

dhtmlxToolbar 2.0 component provides means for users to activate commands and tools contained in an application/website. To make the application/website user-friendly, a toolbar should be designed to expose the key functionality. This component will work well at any page and in any browser that supports JavaScript.

The component provides users with the possibility to:

2.1 Main Features

2.2 Supported browsers

3. Types of Items in dhtmlxToolbar

dhtmlxToolbar can operate the following types of items:

4. Initializing dhtmlxToolbar

4.1 New Toolbar Object Creation

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>
The user needs to create an object where dhtmlXToolbar will be placed later. In this example the object is a <div> element on page, which is placed in the <body> tag.
<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>
    var toolbar = new dhtmlXToolbarObject(
baseId, skin);
</script>

baseId defines an HTML object on page to which the toolbar is attached (the main toolbar container in the code mentioned above).
skin is the optional parameter which defines the skin, that will be applied to the toolbar.
If this argument is not set, the component will be created with the default skin (dhx_blue).
So, in our case the code will look like this:
<script>
    var toolbar = new dhtmlXToolbarObject("toolbar");
</script>

4.2 Setting Image Path

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.


The following code string should be placed before any of data loading methods:

<script>   
    toolbar.setIconsPath("[full path to icons image files directory]");
</script>

4.3 Available Skins

The following predefined skins are available for dhtmlxToolbar users:






Note: other skins that were available in older versions of Toolbar are currently being updated.

5. Data Loading

The next step of dhtmlxToolbar component initialization is Data Loading.

The user can choose one of 3 data loading possibilities:

5.1 Data Loading from XML File

loadXML() method loads we bar data from an XML file. When the data is loaded into the object, a user-defined handler is called (onLoadFunction), if it was indicated by user. All the data is loaded at once:
<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.


5.2 Data Loading from XML String

loadXMLString() method loads toolbar data from XML string. When the data is loaded into the object, a  user-defined handler is called (onLoadFunction).
All the data is loaded at once:
<script>
   
toolbar.loadXMLString("<bar><item....>", onLoadFunction);
    onLoadFunction = function(){
        // will be called if specified
    }
 </script>

See here for XML Format Template.

5.3 Data Loading from Script

The user can load data to the toolbar by adding various types of items from script. Loading data from script means that the user should write a code line for adding every toolbar item. In our example to add a new button and set its tooltip, add one more button with its tooltip, and add a separator we should write the following:

<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>
See Items Adding and Removing section for more information.

5.4 onLoadFunction

On Load Function is a user-defined handler that is called after the data was loaded into the object:

<script>

    toolbar.loadXML("file.xml", function(){

        alert("the data is loaded"); // will be invoked after XML file loading (after onXLE if specified)

    });

</script>

6. Adding and Removing Items

6.1 Button Adding

A Button item can be easily added to the toolbar with the help of the following method:
<script>
    toolbar
.addButton(id,pos,text,imgEnabled,imgDisabled);
</script>
Parameters that should be passed are:

6.2 Text Item Adding

A Text Item can be added to the toolbar by calling addText() method:

<script>
    toolbar
.addText(id,pos,text);
</scrip>
The following parameters should be passed to this method:

6.3 Select Button Adding

There is one simple method that adds a Select Button to the toolbar:
<script>
    toolbar
.addButtonSelect(id,pos,text,opts,imgEnabled,imgDisabled);
</script>
The following parameters should be passed to this method:


The
opts parameter requires more detailed description as the user should specify the following for each listed option:


Several options can be set at once as opts variable:

<script>

    var opts = Array(Array('id1', 'obj', 'option1', 'img1'), Array('sep01', 'sep', '', ''), Array('id2', 'obj', 'option2', 'img2'));

</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.

6.4 Two-State Button Adding

The following method should be used to add a new Two-State Button:

<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.

6.5 Separator Adding

A new Separator can be created by calling the following method:

<script>

    toolbar.addSeparator(id,pos);

</script>

This method has two input parameters:

 

6.6 Slider Adding

addSlider() method should be used to create a new Slider:
<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:



Note: if the user wants the Slider to be created tooltip text-free, it's necessary to write an empty string as tip parameter. 

6.7 Input Item Adding

The following syntax shows the user how an Input item can be easily added:
<script>
    toolbar
.addInput(id,pos,value,width);
</script>
This method has the following input parameters:


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>

6.8 Item's Removal

A simple tool for item's removal from the toolbar is removeItem() method:
<script>
    toolbar.
removeItem(itemId);
</script> 

7. Items Settings Manipulations

7.1 Iterator

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>

7.2 Applied to Any Item

The following methods can be applied to any item in the toolbar:

<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 Button

7.3.1  Showing/Hiding Button


To hide/show any button the user should pass button's id to the following methods:

<script>
    toolbar
.showItem(id);
    toolbar.hideItem(id);
</script>
The user has the possibility to check whether any button is visible. The method returns true if the button is visible:
<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>
    toolbar
.enableItem(id);
    toolbar.disableItem(id);
</script>
Also the user has the possibility to check whether any button is enabled. This can be done by calling the following method:
<script>
    var isEnabled =
toolbar.isEnabled(id); // returns true|false
</scrip>
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.

7.3.3 Setting Button's Text


The user can set any button's text/label. This button's id and text of button's label are passed as parameters to the following method:
<script>
    toolbar
.setItemText(id, text);
</script>
The user can get button's text using getItemText() method. The method returns the current title text of the button:
<script>
    var text =
toolbar.getItemText(id); // returns current item's text
</script>

7.3.4 Setting Button's Image


Any button in the toolbar can have its own image displayed in the button display area. setItemImage() and setItemImageDis() methods allow user to set image to a button by passing the following parameters:

<script>
    toolbar
.setItemImage(id,url);
    toolbar.setItemImageDis(id,url);
</scrip>
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:
<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>
    toolbar
.setItemToolTip(id,tip);
</script>
The following method can return the current button's tooltip text:
<script>
    var tip = 
toolbar.getItemToolTip(id); // returns current button's tooltip text
</script>

7.4. Select Button

The following methods that are available for the Button item, can be applied to the Select Button item as well:


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


A simple method is used to set this item's width:
<script>

toolbar.setWidth(id, width);

</script>

The parameters are:



7.4.2 Adding/Removing Listed Option


A new Listed Option can be added using addListOption() method that accepts the following parameters:

<script>
    toolbar.addListOption(parentId, id, pos, type, text, img);
</script>
Any Listed Option can be easily removed by calling the following method:
<script>
    toolbar.removeListOption(parentId,id);
</script>

7.4.3  Showing/Hiding Listed Option


Any of the Listed Options can be shown/hidden if one of the following methods is applied to it:
<script>
    toolbar.showListOption(parentId, id);
    toolbar.hideListOption(parentId, id);
</script>
The user has the possibility to check whether any Listed Option is visible. The method returns true if the item is visible:
<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>
    toolbar.enableListOption(parentId, id);
    toolbar.disableListOption(parentId, id);
</script>
Also the user has the possibility to check whether any Listed Option is enabled. This can be done by calling the following method:
<script>
    var isEnabled =
toolbar.isListOptionEnabled(parentId, id); // returns true|false
</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.

7.4.5  Setting Listed Option's Position (moving)


The following methods can be used to set new position for a Listed Option and to get the current position of it:
<script>
    toolbar.setListOptionPosition(parentId, id, pos);
    var pos = toolbar.getListOptionPosition(parentId, id);
</script>

7.4.6  Setting Listed Option's Text


The user can set any Listed Option's title. This item's parentId, id and title's text are passed as parameters to the following method:
<script>
    toolbar
.setListOptionText(parentId, id, text);
</script>
The user can get Listed Option's title using getListOptionText() method. The method returns the current title text of the item:
<script>
var text = 
toolbar.getListOptionText(parentId, id); // returns current listed option's title text
</script>

7.4.7  Setting Listed Option's Image


A Listed Option in the toolbar can have its own image displayed in the left part of item's display area. setListOptionImage() method allows the user to set image to a Listed Option by passing the following parameters:

<script>
    toolbar
.setListOptionImage(parentId, id, img);
</script>
Path to current listed option image can be got like this:
<script>
    var listOptionImage = toolbar.getListOptionImage(parentId, id); // returns path to the current listed option image
</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:
<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>
    toolbar
.setListOptionToolTip(parentId, id, tip);
</scri>
The following method can return the current Listed Option's tooltip text:
<script>
    var tip = toolbar.getListOptionToolTip(parentId, id); // returns current listed option's tooltip text
</scri>

7.4.9 Selecting Listed Option


The user can make any listed option selected by default from script. On startup, when the user first opens the list of options, this chosen listed option will be highlighted (selected). The method setListOptionSelected() takes the following parameters:

<script>
    toolbar.setListOptionSelected(parentId, id);
</script>
This method doesn't make the listed option selected forever. Another listed option can be easily selected by user from page.

There is also the possibility to get the id of the current selected listed option by method getListOptionSelected():
<script>
    var listOptionId = toolbar.getListOptionSelected(parentId); //returns id of the selected listed option
</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.

7.4.10 Get All Listed Options


Method getAllListOptions() allows the user to get all listed options ids of a certain Select Button. The only one parameter that the user should pass is the id of the chosen Select Button:
<script>
    var allListOptions = toolbar.getAllListOptions(parentId); // returns array of all listed options ids
<script>

7.5 Two-State Button

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>
    toolbar.
setItemState(id,state,callEvent);

</script>

The parameters for this method are the following:


There is also the possibility to get current item's state by calling getItemState() method:
<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.6 Text Item

The following methods that are available for the Button item, can be applied to the Text Item as well:


All the parameters of the above mentioned methods are the same to those described in Button Settings Manipulations section.

7.7 Separator

The following methods that are available for the Button item, can be applied to the Separator as well:


All the parameters of the above mentioned methods are the same to those described in Button Settings Manipulations section.

7.8 Slider

The following methods that are available for the Button item, can be applied to the Slider as well:


All the parameters of the above mentioned methods are the same to those described in Button Settings Manipulations section.
 

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:

<script>

    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:

<script>

    toolbar.setItemToolTipTemplate("slider","Current Value is:+%v");

</script>

The following method can return current slider's tooltip template:

<script>

    var template = toolbar.getItemToolTipTemplate(id); // returns current slider's tooltip text

</script>


7.8.2  Setting Slider's Value


The user can set the Slider to a certain value within the range of available values with the help of the following method:
<script>
    toolbar.
setValue(id,value,callEvent);
</script>
The parameters are as follows:


Note
: If the user has indicated the value that is not within the range of available values, the slider's thumb will be set either to the minimum or to the maximum value.

Slider's current value can be easily got by the following method:
<script>
    var value =
toolbar.
getValue(id); // returns slider's current value
</script>

7.8.3 Setting Slider's Minimum Value


There is a method to set slider's minimum value:
<script>
    toolbar.
setMinValue(id,value,label);
</script>
The following parameters should be passed to this method:


Note: if the user wants the slider's minimum value to be created text-free, it's necessary to write an empty string as label parameter. For example:
<script>
    toolbar.setMinValue("slider",25,"");
</script>
Slider's current minimum value can be got using getMinValue() method:
<script>
    var data = 
toolbar.
getMinValue(id); // returns slider's current minimum value
</script>
This method returns the following Array: value, label.

7.8.4  Setting Slider's Maximum Value


There is a method to set slider's maximum value:
<script>
    toolbar.
setMaxValue(id,value,label);
</script>
The following parameters should be passed to this method:


Note: if the user wants the slider's maximum value to be created text-free, it's necessary to write an empty string as label parameter. For example:
<script>
    toolbar.setMaxValue("slider",25,"");
</script>
Slider's current maximum value can be got using getMaxValue() method:
<script>
    var data =
toolbar.
getMaxValue(id); // returns current maximum value
</script>
This method returns the following Array: value, label.

7.9 Input Item

The following methods that are available for the Button item, can be applied to the Input Item as well:


All the parameters of the above mentioned methods are the same to those described in Button Settings Manipulations section.
The following methods that are available for the Slider item, can be applied to the Input Item as well:


All the parameters of the above mentioned methods are the same to those described in Slider Settings Manipulations section.
There's one more method applied to Select Button that can be applied to the Input Item as well:


All the parameters of the above mentioned method are the same to those described in Setting Select Button Width section.

7.9.1  Getting Input's Width


The current input's width can be got with the help of getWidth() method:
<script>
    var width =
toolbar.
getWidth(id); // returns current input's width
</script>

8. Event Handling

8.1 Available events

The following events are available in dhtmlxToolbar:

8.2 Attaching event handler

The user can add any user-defined handler to available events. 

To do this he can use attachEvent() method with the following parameters:


<script>
    toolbar.attachEvent(evName, evHandler);
</script>
Note: the names of the events are case-insensitive.

8.3 onClick event

onClick event can be applied to Button or Select Button items only.
This event calls user-defined handlers (if there are any) and passes item's id parameter:
<script>
    toolbar.attachEvent("onClick", function(id){});
</script>

Now let's attach an event handler for "onClick" event:

<script>

    toolbar.attachEvent("onClick", function(id){

        alert("Button "+id+" was clicked");

        });

</script>

8.3 onStateChange event

onStateChange event can be applied to Two State Button item only.
This event calls user-defined handlers (if there are any) and passes the following parameters:

<script>
    toolbar.attachEvent("onStateChange", function(id, state){});
</script>

8.4 onValueChange event

onValueChange event can be applied to Slider item only.
This event calls user-defined handlers (if there are any) and passes the following parameters:

<script>
    toolbar.attachEvent("onStateChange", function(id, value){});
</script>

8.5 onXLS event

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>

8.6 onXLE event

This event occurs when data loading from XML has already been ended and just before onLoadFunction.
onXLE event can call user-defined handlers (if there are any):
<script>
    toolbar.attachEvent("onXLE", function(){});
</script>

8.8 onEnter event

onEnter event can be applied to the Input item only.
This event calls user-defined handlers (if there are any) and passes the following parameters:

<script>
    toolbar.attachEvent("onEnter", function(id, value){});
</script>

9. XML Format Template

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>