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

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 IDs (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:
  1. true or false for whether to recover a cookie state for this group. The default value if undefined is false, but you will need it to be true 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:
  1. 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.
  2. The toggle command. This can be one of: "open" or true to open the box; "close" or false to close the box; "toggle" or null to invert the current state.
Return value:
  • true if the operation was successful, or false 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:
  1. 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.
  2. 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 specify true for positive movement (south or east) or false for negative movement (north or west).
Return value:
  • true if the operation was successful, or false 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:
  1. 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.
  2. 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.
Return value:
  • true if the operation was successful, or false 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 of onboxdrag; the orientation is not "freeform" or "confirm" (the swap 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:
  1. 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.
  2. A string value specifying whether the box you wish to move should be inserted "before" or "after" the insertion target.
  3. 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 or null 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).
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 of onboxdrag; an otherwise-unspecified internal script error occurs.

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

Categories...

Website gadgets

Bits of site functionality:

Usability widgets

Local network apps

Web-applications for your home or office network:

Game and novelties

Our internal search engine is currently offline, undergoing some configuration changes in preparation for a major site overhaul. In the meantime, you can still search this site using Google Custom Search.


In this area

Main areas


[brothercake] a round peg in a square hole, that still fits