dbx manual
6. Remote controls
The script provides five remote functions that can be used to control the boxes independently of manual interaction. These allow you to extend the native behaviors of the boxes, by scripting for additional actions that occur in response to in-built actions (for example, automatically closing one box in response to another opening). They also allow you to implement brand new control mechanisms from different modalities, such as voice-controlled browsing.
And I'm sure there are plenty of other things that can be done
with these remotes, that haven't even occured to me.
As William Gibson said,
the street finds its own uses for things
.
For some basic demos of the remotes in action, please have a look at the grid-controls demo and the column-controls demo.
- Pre-requisites
- Refreshing a group
- Opening or closing boxes
- Moving boxes
- Swapping boxes
- Inserting boxes
- A few ideas for suggested uses
Pre-requisites
For all the remotes apart from refresh()
,
you must have the dbx.remotes.js
codebase
included on your page:
<!-- dbx remote controls -->
<script type="text/javascript" src="dbx.remotes.js"></script>
It can go anywhere after the main dbx script, but before your configuration script.
Most of the remote controls require box references, and are easiest
to use if the references are box ID
s (although they
can accept box object references as well). So it's best to add ID
attributes to the boxes, and to
enable box-id based groups.
Remote control actions are not affected by confirm dialogs — calling a remote action
will initiate the specified action immediately, irrespective of whether a
confirm mode is in use.
They are however affected by the return value of relevant
API event handlers;
for example, moving boxes will be affected by
onboxdrag
.
All the remote controls are methods of dbxGroup
. You can call
them from with an API event handler
using the property this.dbxgroup
Refreshing a group
group.refresh()
-
The
refresh
method re-initializes a group, and is essential when populating or modifying group contents mid-session (such as loading new boxes using Ajax). See the Ajax-controlled group demo for an example of this in action.Unlike all the other remote methods, this one is built into the core codebase and does not require
dbx.remotes.js
-
Arguments:
-
true
orfalse
for whether to recover a cookie state for this group. The default value if undefined isfalse
, but you will need it to betrue
if you're re-initializing a group after modifying it from an external process (such as in the Ajax demo).
-
-
Return value:
- No return value
Opening or closing boxes
group.toggle()
-
The
toggle
method allows you to open or close a box. -
Arguments:
-
A reference to the box you wish to open. This can either
be a string specifying the box
ID
, or an object reference to the box itself. You can also specify the string value"*"
to control every box in the group. -
The toggle command. This can be one of:
"open"
ortrue
to open the box;"close"
orfalse
to close the box;"toggle"
ornull
to invert the current state.
-
A reference to the box you wish to open. This can either
be a string specifying the box
-
Return value:
-
true
if the operation was successful, orfalse
if the operation was unsuccesful. The operation will be unsuccessful if: no box reference is specified; the script is not supported; a box is specified that doesn't exist;"*"
is specified but the group contains no boxes; the command is"open"
or"close"
and the box already has the specified state; an otherwise-unspecified internal script error occurs.
-
Moving boxes
group.move()
-
The
move
method allows you to move a box in a specific compass direction. -
Arguments:
-
A reference to the box you wish to move. This can either
be a string specifying the box
ID
, or an object reference to the box itself. -
The direction of movement. This can be any of a number of possible
syntaxes: a compass direction letter such as
"N"
or"Se"
; a compass direction word such as"north"
or"south-east"
; an orientation word such as"up"
or"down-right"
(for which the vertical axis must be specified first). For linear orientations (a horizontal row of boxes, or a vertical column of boxes) you can also specifytrue
for positive movement (south or east) orfalse
for negative movement (north or west).
-
A reference to the box you wish to move. This can either
be a string specifying the box
-
Return value:
-
true
if the operation was successful, orfalse
if the operation was unsuccesful. The operation will be unsuccessful if: no box reference is specified; the script is not supported; the specified box does not exist; the rules engine disallows the specified movement; an otherwise-unspecified internal script error occurs.
-
Swapping boxes
group.swap()
-
The
swap
allows you to swap the position of two boxes. -
Arguments:
-
A reference to the first box you wish to swap. This can either
be a string specifying the box
ID
, or an object reference to the box itself. -
A reference to the second box you wish to swap. This can either
be a string specifying the box
ID
, or an object reference to the box itself.
-
A reference to the first box you wish to swap. This can either
be a string specifying the box
-
Return value:
-
true
if the operation was successful, orfalse
if the operation was unsuccesful. The operation will be unsuccessful if: either box reference is unspecified; the script is not supported; either of the specified boxes does not exist; the two box references are the same; the action is blocked by the return value ofonboxdrag
; the orientation is not"freeform"
or"confirm"
(theswap
method is not supported for linear orientations); an otherwise-unspecified internal script error occurs.
-
Inserting boxes
group.insert()
-
The
insert
method allows you to insert a box, either before or after another box, or at the beginning or end of the group. -
Arguments:
-
The original box you wish to move. This can either
be a string specifying the box
ID
, or an object reference to the box itself. -
A string value specifying whether the box you wish to move
should be inserted
"before"
or"after"
the insertion target. -
The insertion target. This can be a string specifying a box
ID
, or an object reference to the box itself; the box you wish to move will then be inserted before or after this target, depending on the value of the second argument. If this argument is omitted ornull
then the original box will be inserted either at the very beginning or very end of the group, depending on the value of the second argument ("before"
inserts at the beginning of the group;"after"
inserts at the end of the group).
-
The original box you wish to move. This can either
be a string specifying the box
-
Return value:
-
An object reference to the group that was inserted into
if the operation was successful, or
null
if the operation was unsuccesful. The operation will be unsuccessful if: no original box reference is specified; the script is not supported; a target box is specified that does not exist; the action is blocked by the return value ofonboxdrag
; an otherwise-unspecified internal script error occurs.
-
An object reference to the group that was inserted into
if the operation was successful, or
A few ideas for suggested uses
Here's a handful of simple ideas for things you can do using the remote controls. You can see a more complex example of the remotes in action in the Photo-swap puzzle.
1. Groups where only one box can be open at a time
An idea I alluded to at the start of this page, is to use the
toggle()
method in combination with the
onboxopen event,
to create groups in which only one box can be open at a time. Thanks to Oliver Busta,
who sent me this idea:
//onboxopen fires when a box is opened
manager.onboxopen = function()
{
//close all boxes in this group
this.dbxobject.toggle('*', false);
//alow this one to open
return true;
};
For this to work coherently, you would also need to configure the group so that its boxes are closed by default.
2. Animation cross-fade
If we hook into the onanimate
event, we can use it to
fade-in the opacity of the source-box, while fading-out the opacity
of the animation clone. The overall effect is of a cross-fade
between items as they move:
//onanimate fires during movement animation
manager.onanimate = function()
{
//make the sourcebox visible
this.sourcebox.style.visibility = 'visible';
//set the opacity for this iteration, based on the length and count
var opacity = (1 / this.anilength) * this.anicount;
//apply opacity to the source-box and inverse opacity to the clone-box
this.sourcebox.style.opacity = opacity;
this.clonebox.style.opacity = 1 - opacity;
};
You can see this in action in the Sortable list demo.
← API events | The rules engine →