dbx manual

1. Setting up the HTML

Before you can do anything with this script, you need to setup the basic HTML.

The core structure
Ungrabbable boxes
Adding toggles manually

The core structure

The script does not create the stuctures, it attaches behaviors to existing HTML elements, identified by their class name. There are four basic classes:

"dbx-group"

The vertical or horizontal container elements around each group of docking boxes (groups)

"dbx-box"

The docking box elements themselves (boxes)

"dbx-handle"

The element within each box which can be grabbed with the mouse in order to move it (handles); this is also where the buttons which control the open/close behavior(toggles) are inserted, and if used, these toggles are the event-anchor for keyboard navigation.

If toggles are not used, the script will attempt to use the handle itself as the anchor for keyboard navigation; so if you're doing that, the handle should be a focussable element, such as a link or form-element.

"dbx-content"

The optional content area within each box (content) which is controlled by the show/hide behavior.

Each group container must also have a unique ID, so the overall structure would look something like this:

<element class="dbx-group" id="something">

    <element class="dbx-box">
        <element class="dbx-handle">...</element>
        <element class="dbx-content">
            ...
        </element>
    </element>

    <element class="dbx-box">
        <element class="dbx-handle">...</element>
        <element class="dbx-content">
            ...
        </element>
    </element>

</element>

And so on. You can have any number of groups, and any number of boxes within each group (except none). The content area is optional, and may not be required for many uses.

There are no restrictions on what core elements you can use here, except: all core elements must be block-level (or have block display). The script will enforce this by applying the correct style properties as each group is initialised, so you don't need to worry about it, merely be aware of it.

But if you need any of these elements to have inline display in IE6, for the sake of a CSS hack to avoid the double-margin float bug, then you can, but only in IE6. To make it apply you will need to use !important so that it overrides the script's setting of block display. Let me re-inforce that you can ONLY DO THIS IN IE6, not in any other browser, because only in IE6 can inline elements behave and be styled like block elements.

Ungrabbable boxes

If you wish, you can specify that individual boxes should be ungrabbable, which means that they can be targets for swap or insertion, but they cannot be grabbed or moved directly. To specify that a box is ungrabbable, add the additional class name "dbx-nograb":

<element class="dbx-box dbx-nograb">

This is intended to be used where a layout requires blank target boxes, to allow you to move objects into apparently empty space. The best elements to use for such targets are links with no href, so that they can't receive the focus, and therefore the user won't even know that anyting's there. For an example of this, please see the Bookshelves demo

Adding toggles manually

The script normally creates the toggles itself (if this feature is enabled). However if you prefer, you can add these elements manually, and the script will bind the necessary event listeners to the toggles that it finds — when a group initializes, it will look for elements inside the handles that have the class name "dbx-toggle", and if found, will defer to these instead of creating its own, for example:

<h3 class="dbx-handle">
    Portfolio
    <button class="dbx-toggle"></button>
</h3>

But you should think carefully before doing this, because toggles have no purpose if scripting is not supported, and are therefore redundent for users who don't have scripting. Nevertheless, you might need to do this to gain more control over the toggles' markup, for example if you need to add additional attributes.

If you want to do this, all you have to remember is the following:

they must have the class name "dbx-toggle"
they must be children of the "dbx-handle" elements
they must be elements which can accept the keyboard focus, such as links or buttons. If they are links, remember that they must have an href value — even if it's a junk value like "#" or "javascript:void(null)" — because links that have no href are not accessible to the keyboard