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
andonboxclose
- 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.
onbeforestatechange
-
onbeforestatechange
fires immediately before a group state changes, ie. just beforeonstatechange
.The return value controls whether the state change is allowed, and so by extension, whether the sort action occurs at all.
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, thestatechange
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.
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 particularID
orclass
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 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.
onboxclose
-
onboxclose
fires when a box is closed.The return value and useage guidelines are the same as for
onboxopen
.
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 than1
(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.
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.
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 ofdbxGroup
. 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 theclass
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
orfalse
for whether the move is allowed. Returning this property from anonruletest
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 ofdbxGroup
. this.group
[object]- An object reference to the group container.
this.gid
[string]-
The
ID
of this group, as defined in thedbxGroup
constructor. this.sourcebox
[object]-
An object reference to the box being moved. This value will be
null
whenonbeforestatechange
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 ofdbxGroup
. this.group
[object]- An object reference to the group container.
this.gid
[string]-
The
ID
of this group, as defined in thedbxGroup
constructor. this.sid
[string]-
The session
ID
defined in thedbxManager
constructor. The sessionID
and groupID
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 groupID
, 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 ofdbxGroup
. 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-initiatedboxdrag
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
tothis.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 ofdbxGroup
. 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 ofdbxGroup
. 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 ofdbxGroup
. 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 theID
attribute you specified for it, or the dynamically assignedclassid
that the script uses for boxes whereID
attributes are not used. Which it is will depend upon the value you set for enable box-ID based dynamic groups. -
Arguments:
-
A reference to the box for which you want the
internal
ID
[object]
-
A reference to the box for which you want the
internal
-
Return value:
-
The internal
ID
of the box [string] -
null
if the box reference was invalid [object]
-
The internal
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:
- A reference to the original box [object]
-
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:
- The object you want the position of [object]
-
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
andtop
properties [object]
-
An object of position values, with
manager.addEvent()
-
Add an encapsulated event listener to an object, using whichever method is supported by a particular browser.
-
Arguments:
- The element to which the listener should be bound [object]
-
The event name, such as
"click"
[string] - 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:
- The container node [object]
- The inner node [object]
-
Return value:
-
true
orfalse
for whether the container node contains the inner node [boolean]
-