dhtmlxAccordion Guide and Code Samples

1. Introduction

1.1 Scope of the Document

This document describes dhtmlxAccordion component, 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).


2. What is dhtmlxAccordion

dhtmlxAccordion is a component that provides an easy and effective way of placing different types of content on a single page. The component is a very flexible and easy to use content manager. It is compatible with other dhtmlx components that can be attached to dhtmlxAccordion without any difficulties.
dhtmlxAccordion supports only vertical layout. As other dhtmlx components, Accordion is intended to save users' time on coding and configuring.

2.1 Main Features

2.2 Supported browsers

3. Initializing dhtmlxAccordion

The first steps that need to be taken for dhtmlxAccordion's initialization are the following:


<head>
   
<!-- dhtmlxAccordion -->
    <script src="[full path to this file]/dhtmlxcommon.js"></script>
    <script src="[full path to this file]/dhtmlxaccordion.js"></script>
    <link rel="stylesheet" type="text/css" href="[full path to this file]/dhtmlxaccordion_dhx_blue.css">

    <!-- dhtmlxWindows -->
    <script src="[full path to this file]/dhtmlxwindows.js"></script>
    <link rel="stylesheet" type="text/css" href="[full path to this file]/dhtmlxwindows.css">
    <link rel="stylesheet" type="text/css" href="[full path to this file]/dhtmlxwindows_dhx_blue.css">
</head>

Note: dhx_blue is the default skin. If the user chooses to apply some other skin, he should indicate path to the appropriate dhtmlxaccordion_[name_of_the_skin].css file from dhtmlxAccordion package and to the appropriate dhtmlxwindows_[name_of_the_skin].css file from dhtmlxWindows package.

3.1 New Accordion Object Creation

The user needs to create an object where dhtmlxAccordion will be placed later. In this example the object is a <div> element on page, which is placed in the <body> tag:
<div id="accordObj"></div>
A new Accordion object can be created in the following way:
<script>
    var dhxAccord = new dhtmlXAccordion(parentId, skin);
</script>
parentId defines an HTML object on page to which the accordion is attached (the main accordion container in the code mentioned above).
The second argument is optional, and it indicates the name of the skin chosen for the Accordion. If this argument is not indicated, the component will be created with the default skin (dhx_blue).

So, in our case the code will look like this:
<script>
    var dhxAccord = new dhtmlXAccordion("
accordObj");
</script>

3.2 Attaching dhtmlxAccordion (Object) to Window

An Accordion object can be attached to any created window on page. First, the user needs to create a new base for a set of new windows, a new dhtmlxWindow object for it, and set paths for window's image files.
<script>
    var dhxWins = new dhtmlXWindows();
    dhxWins.setImagePath("[full path to this directory]/codebase/imgs/");
    var w1 = dhxWins.createWindow("w1", 10, 10, 320, 360);
</script>
The parameters of the createWindow() method are as follows:

Then the window will invoke the base for dhtmlxAccordion and will return the handler for the Accordion object itself. The user should write only the following line of code:
<script>
    var dhxAccord = w1.attachAccordion();
</script>

3.3 Attaching dhtmlxAccordion (Object) to Layout

First, the user should download dhtmlxLayout package from the server into the same folder where previously downloaded packages were put. Then, the full path to the following files is to be indicated in the <head> tag of html file:


    <!-- dhtmlxLayout -->

<script src="[full path to this file]/dhtmlxlayout.js"></script>

<link rel="stylesheet" type="text/css" href="[full path to this file]/dhtmlxlayout.css">

<link rel="stylesheet" type="text/css" href="[full path to this file]/dhtmlxlayout_dhx_blue.css">

We need to create an object where dhtmlxLayout will be placed later. In this example the object is a <div> element on page which is placed in the <body> tag:

<div id="parentId" style="position:absolute; width:600px; height:400px;"></div>

The next step is to create a new dhtmlXLayoutObject and place it after the <div> element (object) that we've just created:

<script>     

    var dhxLayout = new dhtmlXLayoutObject("parentId", "3L", "dhx_black");

</script>

The second argument in dhtmlXLayoutObject() is the code of the Layout's pattern.

The third argument is optional, and it indicates the name of the skin chosen for the Layout. If this argument is not indicated, the component will be created with the default skin (dhx_blue).


And only then the user should write the following line of code in order to attach an Accordion to the chosen layout's cell (let it be the first cell "a"):

<script>

    var dhxAccord = dhxLayout.cells("a").attachAccordion();

</script>

3.4 Available Skins

The following predefined skins are available for dhtmlxAccordion users:


4. dhtmlxAccordion Configuration

4.1 Setting Image Path

Method setIconsPath() should be used to set the full paths to the directory where Accordion image files are located. In this method the user should set path to the directory, where accordion icons images are stored.
<script>
    dhxAccrod
.setIconsPath("[full path to icons image files directory]");
</script>

4.2 Setting Sizes

As it was stated above, the accordion object can be attached to a window. Initially the accordion occupies all the window's space. In the case of window's resizing, it becomes responsible for accordion's resizing as well.

If the user intends to attach dhtmlxAccordion to some other place on page, the adjustment of Accordion object's size to the outer dimension of the container is done by means of

setSizes() method:

<script>
    dhxAccord.setSizes();
</script>
This method doesn't take any input parameters as the size of the object is adjusted automatically with the help of it.

4.3 Setting Effect

The effect in dhtmlxAccordion lies in noticeable smoothness of Accordion items expanding/collapsing. If it is set, this smoothness is clearly visible when the component's items are being expanded/collapsed. It can be defined by means of setEffect() method:
<script>
    dhxAccord.setEffect(true|false);
</script>

This method is set to false by default. This means that initially there is no any noticeable effect in the process of items expanding/collapsing. This method's parameter should be set to true if the user wants to switch this effect on.

5. Items Settings Manipulations

5.1 Adding Item

A new item can be added to dhtmlxAccordion in the following way:
<script>
    var item = dhxAccord.addItem(itemId, itemText);
</script>
The parameters of this method are:

It should be noted that a new item added to the accordion is always placed under already existing ones. The newly added item is always created expanded (collapsing the item that was expanded previously).

Let's add a new item with id "a1", and title text "a" to the Accordion:
<script>
    dhxAccord.addItem("a1", "a");
</script>

5.2 Item's Accessing

The following way of items accessing is used working with dhtmlxAccordion: through Accordion items' ids. All the items in the Accordion have ids that go in alphabetical succession starting with "a". Items are referred to as cells.
Thus, we can access any Accordion's item in the following way:
<script>
    var item = dhxAccord.cells(itemId);   
</script>
The method will return item's object. So, if the user wants to access the "a" item, the following code string should be written:
<script>
    var item = dhxAccord.cells("a");   
</script>

5.3 Setting/Getting Item's Text

The header text of an Accordion item can be set/changed this way:
<script>
   
dhxAccord.cells(itemId).setText(text);
</script>

setText() method takes one parameter: text - title text of the added item.


Item's header text can be easily got through method getText():

<script>
    var text = dhxAccord.cells(itemId).setText(); // returns current item's header text
</script>

5.4 Iterator

Method forEachItem() calls user-defined function for every existing item passing item's object into it. Using iterator can be very useful, in case the user wants all the items to be subjects of the same change.
For example, the user can use setText() method to set the same text for headers of all items in the Accordion:
<script>
    dhxAccord.forEachItem(function(item){
        // actions, for example:
        item.setText("newText");
    });
</script>

5.5 Setting/Removing Item's Icon

An icon can be set to any of Accordion items in the following way:

<script>

    dhxAccord.cells(itemId).setIcon(icon);   

</script>

The user should use the following method if he wants to remove any item's icon:

<script>

    dhxAccord.cells(itemId).clearIcon();   

</script>

5.4 Opening/Closing Items

Only one item can be held open (expanded) at a time in dhtmlxAccordion. The current active item becomes inactive/closed, when some another item is set active from the page, or from script with the help of the following method:

<script>

    dhxAccord.cells(itemId).open();

</script>


The method close() should be used to close (collapse) an Accordion's item:
<script>
    dhxAccord.cells(itemId).close();
</script>

5.5 Window's Docking/Item's Undocking

Any item in dhtmlxAccordion can be easily Undocked - extracted from the accordion in order to be displayed separately (in a window). The user should use the following method to undock an item:

<script>
    dhxAccord.cells(itemId).undock();
</script>

An undocked item can be Docked - made a part of the accordion again - in the following way:

<script>
    dhxAccord.cells(itemId).dock();
</script>

5.6 Showing/Hiding Items

Any item in dhtmlxAccordion can be easily shown/hidden by means of these two methods:

<script>

    dhxAccord.cells(itemId).show();

     dhxAccord.cells(itemId).hide();

</script>

5.7 Attaching Objects to Items

There is the possibility to add an object to any "objectless" accordion's item. To do this, the user should first create this object on page, and then write one line of code to attach this object to an item of the accordion.

For example, we create a <div> element with id "objId" and with some text inside it. Then we just use the following line of code to attach this object we've just created to an Accordion item:

<div id="objId">

    Some text

</div>


<script>
    dhxAccord.cells("a1").attachObject("objId");
</script>
Note: See here for information on attaching other dhtmlx components to dhtmlxAccordion.

5.7.1 Object Size Handling


By default, the items have overflow:hidden style.


In case the item is not able to display the whole object, the following style should be specified for the object:

<div id="objId" style="width:100%;height:100%;overflow:auto;...>

Now the item will display the scroll bar in case the object does not fit item's size.

5.8 Attaching URLs to Items

Sometimes the user needs to display a web page in an Accordion's item. attachURL() method is used for this purpose in the following way:
<script>
    dhxAccord.cells(itemId).attachURL(url);
</script>
5.8.1 Accessing Inner Content


Any object on the external page attached with attachURL() method can be accessed like this:


 

...
<div id = "A">...</div>
...

 

 

 <script>
            var dhxAccord = new dhtmlXAccordion(...);       
            ...
            dhxAccord.addItem("a1", "item_text");
            ...
            dhxAccord.cells("a1").attachURL("inner.html");
                // accessing <div id="A">
            if (_isIE) {
                dhxAccord.cells("a1").win._frame.contentWindow.document.getElementById("A")...
            } else {
                dhxAccord.cells("a1").win._frame.contentDocument.getElementById("A")...
            }
 </script>
5.8.2 Item Accessing from Attached URL

If the user needs to do some action with an item of the Accordion from the attached URL (for example, close it by clicking some button on page), he should write the following code lines in the attached external page:
    <input type="button" value="hide item" onclick="hideItem();"> // create a button

    <script>
         function hideItem() {
             parent.dhxAccord.cells(itemId).hide(); // hide item in question
         }
    </script>

It should be noted that variable dhxAccord should be created as a global one (in our main dhtmlxAccordion script) in order to be seen by the script in the attached external page.

6. Item's Behavior

This section describes items' behavior on page, when the end-user clicks Accordion items by mouse:

7. Events Handling

The following event is available in dhtmlxAccordion:


7.1 Attaching Event Handler

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

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

<script>
    dxhAccord.attachEvent(evName, evHandler);
</script>

Note: the names of the events are case-insensitive.

7.2 onActive Event

This event calls user-defined handlers (if there are any) and passes the following parameter:


<script>
    d
hxAccord.attachEvent("onActive", function(itemId){
        alert("Item "+itemId+" was activated.");
     });    
</script>      

7.3 onBeforeActive Event

This event calls user-defined handlers (if there are any) and passes the following parameter:


<script>
    d
hxAccord.attachEvent("onBeforeActive", function(itemId){
        alert("Item "+itemId+" will be opened.");

        return true; // item will be opened

        return false; // item will not be opened

     });    
</script>

8. Integration with Other dhtmlx Components

dhtmlxAccordion is compatible with the following dhtmlx Components:



Also a simple Status Bar can be attached to any Accordion's item.

In the first place the user needs to download the necessary packages from the server and set paths to necessary files from them into the <head> tag of our html. The files to which the paths need to be specified should be checked in the documentation describing work with the corresponding component.


Any of the above mentioned components can be easily attached to an Accordion item:
<script>
    var grid = dhxAccord.cells("a1").attachGrid();
        //OR
    var tree = dhxAccord.cells("a1").attachTree();
        //OR
    var treeGrid = dhxAccord.cells("a1").attachGrid();
        //OR
    var folders = dhxAccord.cells("a1").attachFolders();
        //OR
    var tabbar = dhxAccord.cells("a1").attachTabbar();
        //OR
    var layout = dhxAccord.cells("a1").attachLayout("3L");
        //OR
    var menu = dhxAccord.cells("a1").attachMenu();
        //OR
    var tollbar = dhxAccord.cells("a1").attachToolbar();  
        //OR
    var editor = dhxAccord.cells("a1").attachEditor();
        //OR
    var statusBar = dhxAccord.cells("a1").attachStatusBar();   

</script>

attach[Component]() method doesn't take any input parameters for each accordion compatible component except for dhtmlxLayout and dhtmlxTree.

Only one input parameter should be indicated for attachLayout() method, which is Layout's pattern type.
 
There is only one input parameter for attachTree() method. The parameter is the id of a virtual super item that is a parent to all the top level tree nodes of the added dhtmlxTree (see dhtmlxTree constructor description for details). If super root element id is 0, this parameter can be omitted.