dbx manual

5. API events

The script provides eight 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 how the result of that action should be handled. To see these events in action, have a look at the API Events demo.

• Available events
• Handling events
• Properties available onruletest
• Properties available onbeforestatechange
• Properties available onstatechange
• Properties available onboxdrag
• Properties available onboxopen and onboxclose
• Properties available onanimate
• Properties available onafteranimate
• Additional dbx methods

Available events

Here's a rundown of each event, and its handler's influence:

onruletest

onruletest fires whenever a rule is tested.

The return value controls whether the movement is allowed, ie. it allows you to override the result of the rule evaluation. One of the available properties (the allowed property) contains the result of the evaluation, and returning this effectively means that you concur with whatever would have happened anyway.

Properties available onruletest

onbeforestatechange

onbeforestatechange fires immediately before a group state changes, ie. just before onstatechange.

The return value controls whether the state change is allowed, and so by extension, whether the sort action occurs at all.

Properties available onbeforestatechange

onstatechange

onstatechange fires when any group state changes. Note that when dragging a box with the mouse, even though there may be continual movement of boxes as the group is re-ordered on the fly, the statechange itself doesn't occur until you let go of the original box.

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.

Properties available onstatechange

onboxdrag

onboxdrag fires continually while the mouse drags a box, or it fires once each time 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.

Properties available onboxdrag

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

Properties available onboxopen

onboxclose

onboxclose fires when a box is closed.

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

Properties available onboxclose

onanimate

onanimate fires continually during a box animation; the frequency of this event is determined by the value you set for the animation resolution. This event will only fire if the animation resolution is greater than 1 (because in practise, a value of one is effectively the same as a value of zero).

Since this is an asynchronous process, the return value has no effect.

Properties available onanimate

onafteranimate

onafteranimate fires immediately after a box animation has completed. If the animation resolution is zero, this event will still fire once for each box movement.

Since this is an asynchronous process, the return value has no effect.

Properties available onafteranimate

Handling events

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

manager.onstatechange = function()
{
    return true;
};

Or by function reference:

function handleStateChange()
{
    return true;
}


manager.onstatechange = handleStateChange;

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.

All of these properties are properties of dbxManager, and since all API methods are too, they can be referred to using this.

Properties available onruletest

this.dbxobject [object]

An object reference to this dbxGroup instance. This makes it easier to use the remote controls from within a dbx event handler. It may also be useful if, for any reason, you need to query other methods or properties of dbxGroup.

this.group [object]

An object reference to the group container.

this.sourcebox [object]

An object reference to the box being evaluated.

this.rule [string]

The current rule being tested. This value contains the complete rule, rather than the individual pattern currently being tested (please see Basic rule syntax for an explanation of the difference).

this.pattern [string]

The individual pattern being tested.

this.pointer [number]

A pointer that refers to the index of this pattern within its containing rule.

this.ruleset [string]

This will either be the value "global" if the global rule is being tested, or it will be the class name that this rule applies to (please see Creating rules for an explanation of the difference).

this.direction [string]

A compass value such as "N" or "Se" that indicates the direction of movement being tested.

this.blocks [array]

An array of two numbers which indicate the number of blocks' distance being tested, ordered as [x, y].

this.allowed [boolean]

The final decision of the rules engine for this move, either true or false for whether the move is allowed. Returning this property from an onruletest handler effectively means that you concur with the engine's decision, rather than overriding it with a decision of your own.

Properties available onbeforestatechange

this.dbxobject [object]

An object reference to this dbxGroup instance. This makes it easier to use the remote controls from within a dbx event handler. It may also be useful if, for any reason, you need to query other methods or properties of dbxGroup.

this.group [object]

An object reference to the group container.

this.gid [string]

The ID of this group, as defined in the dbxGroup constructor.

this.sourcebox [object]

An object reference to the box being moved. This value will be null when onbeforestatechange is fired in response to the initialisation of a group instance.

this.target [object]

An object reference to the target element, or to the element that was interacted with to initiate this state change. Depending on the circumstances, this will either be a target box (for state changes caused by box movement; it will be an insert-before reference for insertion actions, or a swap reference for swap actions), a toggle (for state changes caused by opening or closing a box), or null (for the state change caused by the initialisation of a group instance).

this.action [string]

A string value that denotes the action which initiated this state change; this will be one of the following values: "load", "swap", "insert", "move", "open", or "close".

Properties available onstatechange

this.dbxobject [object]

An object reference to this dbxGroup instance. This makes it easier to use the remote controls from within a dbx event handler. It may also be useful if, for any reason, you need to query other methods or properties of dbxGroup.

this.group [object]

An object reference to the group container.

this.gid [string]

The ID of this group, as defined in the dbxGroup constructor.

this.sid [string]

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

this.state [string]

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.

Properties available onboxdrag

this.dbxobject [object]

An object reference to this dbxGroup instance. This makes it easier to use the remote controls from within a dbx event handler. It may also be useful if, for any reason, you need to query other methods or properties of dbxGroup.

this.group [object]

An object reference to the group container.

this.sourcebox [object]

An object reference to the box being moved.

This is a reference to the real box — the static element underlying, not the clone that you actually see moving.

this.clonebox [object]

An object reference to the clone box that you're holding during mouse movement. This property will be null for keyboard-initiated boxdrag events.

this.event [event]

A reference to the event object, 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 will allow you to extrapolate any other information you might need, such as the mouse position or key code.

Properties available onboxopen and onboxclose

this.dbxobject [object]

An object reference to this dbxGroup instance. This makes it easier to use the remote controls from within a dbx event handler. It may also be useful if, for any reason, you need to query other methods or properties of dbxGroup.

this.group [object]

An object reference to the group container.

this.sourcebox [object]

An object reference to the box being opened or closed.

this.toggle [object]

An object reference to the toggle button that was clicked to initiate this action.

Properties available onanimate

this.dbxobject [object]

An object reference to this dbxGroup instance. This makes it easier to use the remote controls from within a dbx event handler. It may also be useful if, for any reason, you need to query other methods or properties of dbxGroup.

this.group [object]

An object reference to the group container.

this.sourcebox [object]

An object reference to the box being moved.

This is a reference to the real box — the static element underlying, not the clone that you actually see moving.

this.clonebox [object]

An object reference to the animated clone box that you actually see moving.

this.anicount [number]

A numerical pointer that refers to the index of this animation iteration.

this.anilength [number]

A numerical length that refers to the total number of iterations that will occur in this animation. This property and the anicount property can be used together to track the progress of a complete animation.

Properties available onafteranimate

this.dbxobject [object]

An object reference to this dbxGroup instance. This makes it easier to use the remote controls from within a dbx event handler. It may also be useful if, for any reason, you need to query other methods or properties of dbxGroup.

this.group [object]

An object reference to the group container.

this.sourcebox [object]

An object reference to the box being moved.

This is a reference to the real box — the static element underlying, not the clone that you actually see moving.

Additional dbx methods

There's a few methods available from dbxManager and dbxGroup, over and above what's avaialable from the API, which you might find useful when scripting with the API. These are internal utility methods that do specific things, and which can be safely used without worrying about undermining the script. As with the API properties, all of these methods must be considered read-only.

Some of these methods are properties of the dbxManager object, and are referred to in this documentation as manager.method, while some are properties of the dbxGroup object, referred to as group.method. To refer to a method in script you can use the manager or group reference assigned from your constructors, or, in the case of group methods called from with an API event handler, you can use the reference this.dbxgroup

manager.getID()

This method returns the internal ID of a specific box, which is either the ID attribute you specified for it, or the dynamically assigned classid that the script uses for boxes where ID attributes are not used. Which it is will depend upon the value you set for enable box-ID based dynamic groups.

Arguments:

0. A reference to the box for which you want the internal ID [object]

Return value:

• The internal ID of the box [string]
• null if the box reference was invalid [object]

manager.getSiblingBox()

This methods takes a dbx box as its input, and returns the next or previous sibling box (as specified). This allows you to find sibling box references without worrying about intermediate elements or text nodes.

Arguments:

0. A reference to the original box [object]
1. Which sibling to find, either "nextSibling" or "previousSibling" [string]

Return value:

• the sibling box [object]
• the original input box, if no sibling was found [object]

manager.getPosition()

Get the absolute position of any object with respect to the canvas.

Arguments:

0. The object you want the position of [object]
1. Whether to return the center point of the box [true] or the top-left corner [false] [boolean]

Return value:

• An object of position values, with left and top properties [object]

manager.addEvent()

Add an encapsulated event listener to an object, using whichever method is supported by a particular browser.

Arguments:

0. The element to which the listener should be bound [object]
1. The event name, such as "click" [string]
2. The handling function, which can be a function reference, or you can pass an anonymous function directly [function]

Return value:

• No return value

group.contains()

This method returns whether one node contains another. It's useful for evaluating event targets to determing whether they came from inside a particular element.

Arguments:

0. The container node [object]
1. The inner node [object]

Return value:

• true or false for whether the container node contains the inner node [boolean]

← Accessibility notes | Remote controls →