dbx manual

Implementing the script

The script is configured using two object constructors. The first is a control function called dbxManager, which looks after cookie persistence and controls the API; the second is a group constructor called dbxGroup, which defines behaviors and properties for each group of docking boxes. For a given page or application you would have a single instance of the manager, controlling any number of groups.

The examples in the download zipfile use a window.onload wrapper around the constructors, but you can arrange that however you like - they can go within an existing onload handler, or you could use a scaleable solution such as my domFunction helper or generic onload script.

dbxManager

The dbxManager function takes a single argument:

• Skip code example

//initialise the docking boxes manager
var manager = new dbxManager('main');     //session ID [/-_a-zA-Z0-9/]

session ID

The session ID is used to differentiate groups of docking boxes from each other; the value is used as part of the cookie name, and is so that you can use the script in multiple places within the same site, for completely different things, without those instances interfering with each other.

This value can only contain letters, numbers, dash or underscore.

dbxGroup

The dbxGroup constructor takes fourteen arguments in total - seven for controlling the layout and behaviors, and seven which define the language for informational tooltips:

• Skip code example

//create new docking boxes group
var purple = new dbxGroup(
	'purple',       // container ID [/-_a-zA-Z0-9/]
	'vertical',     // orientation ['vertical'|'horizontal']
	'7',            // drag threshold ['n' pixels]
	'no',           // restrict drag movement to container axis ['yes'|'no']
	'10',           // animate re-ordering ['n' frames per transition]
	'yes',          // include open/close toggle buttons ['yes'|'no']
	'open',         // default state ['open'|'closed']

	'open',         // word for "open", as in "open this box"
	'close',        // word for "close", as in "close this box"
	'click-down and drag to move this box', // sentence for "move this box" by mouse
	'click to %toggle% this box', // pattern-match sentence for "(open|close) this box" by mouse
	'use the arrow keys to move this box', // sentence for "move this box" by keyboard
	', or press the enter key to %toggle% it', // pattern-match sentence-fragment for "(open|close) this box" by keyboard
	'%mytitle%  [%dbxtitle%]' // pattern-match syntax for title-attribute conflicts
	);

Layout and behaviors

container ID

Specify the ID of the main group container element (the "dbx-group"). This value can only contain letters, numbers, dash or underscore.

orientation

Specify a "vertical" column or a "horizontal" row.

drag threshold

The drag threshold is the amount by which you have to move your mouse after clicking down, before a drag action is initiated. This is so that handle elements can also be links without a conflict - nobody keeps the mouse perfectly still when clicking a link, and without this discrimination it would not be possible to combine both functions in a single element.

restrict drag movement to container axis

If this is set to "yes" then the draggable element's position will only be updated in the direction of its container orientation: horizontal boxes only go left and right, vertical boxes only up and down - giving the impression that movement is restricted to that direction. If set to "no" then draggable elements can move freely.

animate re-ordering

This value defines how many frames of movement occur with each box animation.

An animation is either a re-ordering of the boxes from mouse dragging, or a re-positioning of the boxes from keyboard navigation. A frame is a setTimeout loop. So for each animation the timeout will loop n times, moving the object by its own dimension over n each time.

Lower values give a faster but jerkier effect; higher values look smoother but are more CPU intensive, therefore slower. As with all such things, there's a good balance to be found somewhere between the two.

If you specify a value of "0" there will be no animation, just snap movement.

include open/close toggle buttons

If this is set to "yes" then each handle will have a link (an <a> element) appended to it, and these will be used as open/close toggles, and as the focus-anchors for keyboard navigation. They can be styled to create the appearance of buttons, as described in the chapter Writing the CSS framework.

If this is set to "no" then toggles are not included, and therefore the content area will not be controllable; the "no" setting is primarily intended for applications like the picture-matching game, where there is no content area.

In that situation the script will attempt to bind onfocus functions to the handle elements themselves, and use those as the anchors for keyboard navigation. Therefore if you're not including toggles, the handles should be focusable elements (such as links or form controls), otherwise the interface will not be accessible to the keyboard.

default state

Specify whether the boxes in the group should be "open" or "closed" by default. A value of "closed" will only be honoured if you've included toggle buttons.

Language for informational tooltips

The script creates informational tooltips for both mouse and keyboard users, with summary instructions for using the interface. The tooltips are created from the language and grammar you define in these arguments:

word for "open", as in "open this box"

Define a word that means to open the box, used in conjunction with the pattern-match sentences below.

word for "close", as in "close this box"

Define a word that means to close the box, used in conjunction with the pattern-match sentences below.

sentence for "move this box" by mouse

Specify a plain sentence for the text of mouseover tooltips on handle elements, which describe how the drag action works.

pattern-match sentence for "(open|close) this box" by mouse

Specify a pattern-match sentence for the text of mouseover tooltips on toggle buttons, describing how the open/close action works.

The %toggle% token refers to the word for "open" or "close", so you can move that token around within the sentence to acheive the appropriate grammar.

sentence for "move this box" by keyboard

Specify a plain sentence for the text of focus-activated tooltips on keyboard anchors, describing how the move action works.

If toggle buttons are not in use, this sentence will be the whole tooltip.

pattern-match sentence-fragment for "(open|close) this box" by keyboard

When toggle buttons are in use, define a sentence-fragment used to supplement the text of focus-activated tooltips, describing how the open/close action works. This text will be added immediately after the "move this box" text, so that the two fragments can be structured together to form a single sentence.

The %toggle% token refers to the word for "open" or "close", so you can move that token around within the sentence-fragment to acheive the appropriate grammar.

pattern-match syntax for title-attribute conflicts

If an element which requires an informational tooltips already contains title attribute text, this pattern-match determines how the conflict is handled.

The token %mytitle% refers to the existing title attribute; the token %dbxtitle% refers to the informational text generated by the script; the other formatting determines the overall construct.

So you could, for example, set a value of "%mytitle%" to specify that the original title should be preserved unchanged; or conversely you could specify "%dbxtitle%" to overwrite existing titles completely. But the best solution is probably a formatted mixture of both, as I've done in the demos.

API functions

The script provides four application events which can be used to call other scripting, read or modify dbx-element properties, or control the triggering actions directly - determining whether an action is allowed to proceed, and/or whether the outcome should be saved.

Here's a rundown of each method and its influence:

onstatechange

onstatechange fires when any group state changes.

The return value controls whether the new state is saved to a cookie, so if you're managing the persistence yourself through another mechanism, you can return false here to avoid conflict or inefficiency.

onboxdrag

onboxdrag fires while the mouse drags a box, or when the keyboard initiates a move.

The return value controls whether the action is allowed; so for example, you could have permissions for certain boxes that disallow them being moved, by returning false if the box has a particular ID or class name.

onboxopen

onboxopen fires when a box is opened.

The return value controls whether the action is allowed; so for example, you could configure the boxes to be closed by default and then return false to prevent them from being opened. But do note that since the open/close mechanism is purely style-based, there wouldn't nominally be any security or sessional control going on.

However... if a true permissions-based interface is what you want, it's easy enough to create: you can start with boxes where the content area is closed and empty by default, then use a technology such as XMLHttpRequest to retrieve user-specific data and populate the content area onboxopen; alternatively you could have an <iframe> or <object> in the content area, and load documents into that on some conditional basis.

There might be an accessibility issue there - if the static content is empty and a browser doesn't support the script - so ensure that you degrade back to equivalent server-side functionality, or restrict such applications to environments where browser and scripting support is predictable.

onboxclose

onboxclose fires when a box is closed.

The return value and useage guidelines are the same as for onboxopen.

All four events are properties of the dbxManager object; you can extend them as methods using anonymous functions:

• Skip code example

//initialise the docking boxes manager
var manager = new dbxManager('main');


//onstatechange fires when any group state changes
manager.onstatechange = function()
{
	return true;
};

//onboxdrag fires while the mouse drags a box,
//or when the keyboard initiates a move
manager.onboxdrag = function()
{
	return true;
};

//onboxopen fires when a box is opened
manager.onboxopen = function()
{
	return true;
};

//onboxclose fires when a box is closed
manager.onboxclose = function()
{
	return true;
};

Each method also has some properties available to it, which must be considered read-only values - they can't be destroyed or written over without undermining the core script; if you want to process a value, copy it into a local variable and use that.

Properties available onstatechange

this.state

a string containing the position and open-state of each box, formatted as a query string - for example: "purple=1+,2-,3+,0-"; where "purple" is the group ID, the numbers are the box idents, and the "+" and "-" symbols mean open and closed, respectively. If the page contains more than one group, each group's data is split with an ampersand ("&") as per the same format.

this.sid

a string containing the session ID defined in the dbxManager constructor. The session ID and group ID are used together to form the cookie name.

Properties available onboxdrag

this.group

an object reference to the group container.

this.box

an object reference to the applicable box.

This is a reference to the real box - the static element underlying, not the animated clone; a reference to the clone is not available, because it doesn't necessarily exist for all instances of the event.

this.event

a reference to the event itself, unified between models as far as the reference itself, but no further (so for example, you would still need to convert this.event.srcElement to this.event.target yourself). The event reference should allow you to extrapolate any other information you might need, such as the mouse position, key-code or target element.

Properties available onboxopen and onboxclose

this.group

an object reference to the group container.

this.box

an object reference to the applicable box.

this.toggle

an object reference to the toggle button.

Further scripting

You can bind any other scripting to the dbx elements, for entirely separate purposes and without reference to what's happening here, and they shouldn't interfere. Encapsulation is my middle name

← Writing the CSS framework | Accessibility notes →