/
Advanced Reorderer API - v0.4

Documentation for a historical release of Infusion: 1.3
Please view the Infusion Documentation site for the latest documentation.
If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.

Advanced Reorderer API - v0.4

Owned by Anastasia Cheetham
Last updated: Jul 30, 2008Version comment

This documentation refers to the v0.4 released version of the Reorderer code. For documentation specific to the trunk, please see Advanced Reorderer API.

Advanced use of the Reorderer

For cases where more control over the configuration of the Reorderer instance is needed, there is a constructor function that allows you to specify the Layout Handler - v0.4 used by the Reorderer, and offers a means to specify your items using functions instead of jQuery selectors. To use this advanced constructor, you need to:

  1. Pass the container of the orderable elements itself to the Reorderer upon instantiation.
  2. Specify a Javascript function that returns a list of all the orderable elements within the container. This function is passed to the Reorderer upon instantiation.
  3. Specify a Layout Handler - v0.4 to deal with the spatial arrangement of orderable elements. The Reorderer includes several layout handlers to choose from out of the box, which will work with most types of markup supported by the Reorderer. The layout handler is passed to the Reorderer upon instantiation.

Optional:

  1. Provide the Layout Handler - v0.4 with a callback to communicate ordering changes to the server.
  2. Specify elements within the container which can be selected, i.e. which should be focused by the arrow keys, but which may or may not be movable.
  3. Specify valid drop targets within the container.
  4. Specify an element within the given movable that is to be used as a 'handle' for the mouse-based drag and drop of the movable.
  5. Configure the keystrokes to be used.
  6. Customize the avatar used with mouse-based drag and drop.
  7. Create CSS styles for desired appearance of orderable elements when selected and dragging.
On This Page
See Also
Still need help?

Join the fluid-talk mailing list and ask your questions there.

Constructors

Reorderer(container, findMovables, layoutHandler[, options]);

Reorderer(container, findItems, layoutHandler[, options]);

Parameters

container

The container parameter is a selector, single-element jQuery object, or DOM element specifying the root node of the Reorderer.

findMovables

The findMovables parameter is a function that returns all of the movable elements in the container.

findItems

The findItems parameter is an object containing a number of functions:

findItems {
    movables: function(),  // required
    selectables: function(),   // optional
    dropTargets: function(),   // optional
    grabHandle: function(movable)   // optional
};

movables: A function that returns all of the movable elements in the container. This is the only required item, but if it is the only function used, it can be passed directly to the constructor, as in the first form of the constructor above.

selectables: A function that returns all of the selectable elements in the container. This can be used if the container included elements that the user wishes to be included in the keyboard tab order, but which are not to be movable. All movable elements must also be selectable, so the element list returned by the selectables function must include all of the elements returned by the movables function. If selectables is not provided, the movables function will be used.

dropTargets: A function that returns all of the elements that can be used as drop targets for the mouse-based drag and drop functionality. If dropTargets is not provided, the movables function will be used.

grabHandle: A function that returns the element within the given movable that is to be used as a 'handle' for the mouse-based drag and drop of the movable. This can be used if the implementer wishes to restrict the user to click only on a portion of the movable item. If grabHandle is not provided, the entire movable element will be used.

layoutHandler

The layoutHandler parameter is an instance of a Layout Handler - v0.4.

options

The options parameter is an optional collection of name-value pairs that configure the Reorderer:

Name

Description

Values

Default

role

indicates the role, or general use, for this instance of the Reorderer

fluid.roles.LIST
fluid.roles.GRID
fluid.roles.REGIONS

fluid.roles.LIST

keysets

an object containing sets of keycodes to use for directional navigation, and for the modifier key used for moving a movable item.

The object must be a list of objects containing the following keys:
modifier : a function that returns true or false, indicating whether or not the required modifier(s) are activated
up
down
right
left 

fluid.defaultKeysets = [{
    modifier : function (evt) {
        return evt.ctrlKey;
    },
    up : fluid.keys.UP,
    down : fluid.keys.DOWN,
    right : fluid.keys.RIGHT,
    left : fluid.keys.LEFT
},
{
    modifier : function (evt) {
        return evt.ctrlKey;
    },
    up : fluid.keys.i,
    down : fluid.keys.m,
    right : fluid.keys.k,
    left : fluid.keys.j
}];

cssClassNames

an object containing class names for styling the Reorderer. See fluid:below for a discussion of CSS styling of the Reorderer

The object may contain any of the keys defined in the defaultCssClassNames (shown to the right). And class names not provided will revert to the default. 

var defaultCssClassNames = {
    defaultStyle: "orderable-default",
    selected: "orderable-selected",
    dragging: "orderable-dragging",
    mouseDrag: "orderable-dragging",
    hover: "orderable-hover",
    dropMarker: "orderable-drop-marker",
    avatar: "orderable-avatar"
};

avatarCreator

a function that returns a valid DOM node to be used as the dragging avatar

 

The item being dragged will be cloned

dropWarningId

the ID of an element that should be displayed if users attempt to move an item to a location where movement is not permitted

 

(none)

instructionMessageId

the ID of the element containing any instructional messages

 

"message-bundle:"

CSS Classes

The Reorderer applies CSS classes to orderable items, and updates them as they are moved. These classes can be used to apply visual cues to the various states of the orderable items. The class names are configurable. The default class names are:

   orderable-default - This class is applied to elements in their default state.
   orderable-selected - This class is applied to the element that has been selected. The selected item can then be moved using keystrokes.
   orderable-hover - This class is applied to orderable elements when the mouse hovers over them.
   orderable-dragging - This class is applied to the orderable element that is currently being moved using the keyboard.
   orderable-dragging - This class is also applied to the orderable element that is currently being moved using the mouse.
   orderable-avatar - This class is applied to the avatar, which defaults to the image of the orderable element as it is being dragged about by the mouse.
   orderable-drop-marker - This class is applied to the drop target indicator when the mouse is used to drag an item.

Dependencies

The Reorderer dependencies can be met by including the minified Fluid-all.js file in the header of the HTML file:

<script type="text/javascript" src="Fluid-all.js"></script>

Alternatively, the individual file requirements are:

<script type="text/javascript" src="jquery/jquery-1.2.6.js"></script>
<script type="text/javascript" src="jquery/jARIA.js"></script>
<script type="text/javascript" src="jquery/jquery.keyboard-a11y.js"></script>
<script type="text/javascript" src="jquery/ui.core.js"></script>
<script type="text/javascript" src="jquery/ui.draggable.js"></script>
<script type="text/javascript" src="jquery/ui.droppable.js"></script>
<script type="text/javascript" src="fluid/Fluid.js"></script>
<script type="text/javascript" src="fluid/Reorderer.js"></script>

Tutorial

You can follow a tutorial describing how to use the Reorderer at Reorderer Integration Tutorial - v0.4.