Skip to content

Latest commit

 

History

History
638 lines (553 loc) · 16.5 KB

ImageReordererAPI.md

File metadata and controls

638 lines (553 loc) · 16.5 KB
Raw
title category
Image Reorderer API
Components

The Image Reorderer is a convenience function for applying the Reorderer to images within a collection. This page provides technical details of the API.

Creating an Image Reorderer

var myImageReorderer = fluid.reorderImages(container);

// or

var myImageReordererWithOptions = fluid.reorderImages(container, options);

Parameters

container

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

options parameter

The options parameter is an optional collection of name-value pairs that configure the Image Reorderer, as described in the Options section below.

Supported Events

The Image Reorderer fires the following events.

Event Type Description Parameters Parameters Description

onShowKeyboardDropWarning1

 default This event fires before a drop warning is displayed.

item, kbDropWarning

item: The item being moved. kbDropWarning: The DOM element that contains the drop warning, and that will be displayed.

onSelect

 default This event fires when an item is selected by the user.

item

item: The item being selected.

onBeginMove

 "preventable" This event fires just before a request to move is processed. Because the event is preventable, listeners may prevent the move from happening.

item

item: The item being moved.

onMove

 default This event fires just before an item is actually moved.

item, requestedPosition

item: The item being moved. requestedPosition: An object describing the position that the user is trying to move the item into:

    
requestedPosition = {
element,
// the drop target

position
// the position, relative to the drop target, that a dragged item should be dropped. One of BEFORE, AFTER, INSIDE, or REPLACE
}

afterMove

 default

This event fires after an item has successfully been moved. For more information, see Talking to the Server Using The afterMove Event.

This event replaces the afterMoveCallbackUrl option, which was deprecated at version 1.1.2.

item, requestedPosition, movables

item: The item being moved. requestedPosition: An object describing the position that the user is trying to move the item into:

    
requestedPosition = {
element,
// the drop target

position
// the position, relative to the drop target, that a dragged item should be dropped. One of BEFORE, AFTER, INSIDE, or REPLACE
}

movables: A list of all of the movable elements.

onHover

 default

This event fires when the cursor moves over top of an item, and when the cursor moves away from an item. The default listener either adds or removes the hover class (styles.hover) to/from the item.

item, state

item: The item being moved. state: A boolean indicating whether the cursor is moving to (true) or away from (false) the item.

onRefresh

 default

This event fires any time the order of the items changes, or when the refresh() function is called.

 none

Options

General options

Name Description Values Default

selectors

JavaScript object defining CSS-style selectors for important DOM elements. See Selectors for more information.

The object must be a list of objects containing any subset of the following keys:

  • dropWarning
  • movables
  • selectables
  • dropTargets
  • grabHandle 

selectors: {
dropWarning: ".flc-reorderer-dropWarning",
movables:    ".flc-reorderer-movable",
selectables: ".flc-reorderer-movable",
dropTargets: ".flc-reorderer-movable",
grabHandle:  ""
}

listeners

 JavaScript object containing listeners to be attached to the supported events. Keys in the object are event names, values are functions or arrays of functions.

See Supported Events

styles

 an object containing CSS class names for styling the Reorderer. The object may contain any of the keys defined in the default class names (shown to the right). Any class names not provided will revert to the default. 
                    
styles: {
    defaultStyle: "fl-reorderer-movable-default",
    selected: "fl-reorderer-movable-selected",
    dragging: "fl-reorderer-movable-dragging",
    mouseDrag: "fl-reorderer-movable-dragging",
    hover: "fl-reorderer-movable-hover",
    dropMarker: "fl-reorderer-dropMarker",
    avatar: "fl-reorderer-avatar"
}

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.reorderer.defaultKeysets = [{
modifier : function (evt) {
return evt.ctrlKey;
},
up : fluid.reorderer.keys.UP,
down : fluid.reorderer.keys.DOWN,
right : fluid.reorderer.keys.RIGHT,
left : fluid.reorderer.keys.LEFT
},
{
modifier : function (evt) {
return evt.ctrlKey;
},
up : fluid.reorderer.keys.i,
down : fluid.reorderer.keys.m,
right : fluid.reorderer.keys.k,
left : fluid.reorderer.keys.j
}];

selectablesTabindex

 Normally injected automatically from the layoutHandler

String IoC expression

 

selectablesTabindex: "{that}.layoutHandler.options.selectablesTabindex"

avatarCreator

 a function that returns a valid DOM node to be used as the dragging avatar The item being dragged will be cloned

disableWrap

 This option is used to disable wrapping of elements within the container. boolean false

mergePolicy

an object describing how user options should be merged in with defaults For information on options merging, see Options Merging

 
                    
mergePolicy: {
    keysets: "replace",
    "selectors.selectables":
        "selectors.movables",
    "selectors.dropTargets":
        "selectors.movables"
}

Image Reorderer Options

Name Description Values Default

Deprecated as of 1.1.2: afterMoveCallbackUrl

 If an URL is provided with this option, the current state of the component model will be sent to that URL after a move is carried out using a default afterMove event handler. an URL none

Selectors

The selectors option is an object containing CSS-based selectors for various parts of the Image Reorderer. Supported selectors are:

Name Description Default Examples

grabHandle

 If present, identifies a single element within a movable item that the user must click on to drag the movable item. (If not specified, the entire movable item can be clicked on.) "" (empty string) 
                    
selectors: {
    grabHandle: ".title-bar"
}

dropTargets

 Identifies the DOM elements contained within the Reorderer container that can have movable elements dropped relative to them. Note that not all elements within the container need to be drop targets. same as movables 
                    
selectors: {
    dropTargets: "div.dropTarget"
}

selectables

 Identifies the DOM elements contained within the Reorderer container that can be selected using keyboard. Note that selectable elements do not have to be movable. same as movables 
                    
selectors: {
    selectables: "div.selectable"
}

movables

 Identifies the DOM elements contained within the Reorderer container that can be moved using the Reorderer. ".flc-reorderer-movable" 
                    
selectors: {
    movables: "div.movable"
}

dropWarning

 Identifies a single element within the DOM that can be shown to display a warning when the user tries to move an item where it can't be moved. It is assumed that this element contains whatever drop warning text and mark-up the implementor desires. ".flc-reorderer-dropWarning" 
                    
selectors: {
    dropWarning: "#drop-warning"
}

Image Reorderer-specific Selector

The Image Reorderer supports one additional selector:

Name Description Values Default

imageTitle

 Identifies a DOM element that contains a title for the image

".flc-reorderer-imageTitle"

 
                    
selectors: {
    imageTitle: ".caption"
}

Styling the Image Reorderer

The Image Reorderer includes default CSS styles that it applies to the thumbnails. The application of styles is based on known class names. The default class names are described below, and can be used by including the Image Reorderer stylesheet:

<link href="components/reorderer/css/imageReorderer.css" type="text/css" rel="stylesheet" media="all">;

NOTE that the default class names can be overridden with your own classes using the styles option: refer to the Options section above.

Default Classes

  • fl-reorderer-movable-default - This class is applied to thumbnail elements in their default state.
  • fl-reorderer-movable-selected - This class is applied to the thumbnail that has been selected. The selected thumbnail item can be moved using keystrokes.
  • fl-reorderer-movable-hover - This class is applied to thumbnails when the mouse hovers over them.
  • fl-reorderer-movable-dragging - This class is applied to the thumbnail that is currently being moved.
  • fl-reorderer-avatar - This class is applied to the avatar, the image of the thumbnail as it is being dragged about by the mouse.
  • fl-reorderer-dropMarker - This class is applied to the drop target indicator when the mouse is used to drag a thumbnail.

Dependencies

The Image Reorderer dependencies can be met by including the infusion-custom.js file in the header of the HTML file:

<script type="text/javascript" src="infusion-custom.js"></script>

Alternatively, the individual file requirements are:

<script type="text/javascript" src="lib/jquery/core/js/jquery.js"></script>
<script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.core.js"></script>
<script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.widget.js"></script>
<script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.mouse.js"></script>
<script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.draggable.js"></script>
<script type="text/javascript" src="framework/core/js/FluidDocument.js"></script>
<script type="text/javascript" src="framework/core/js/jquery.keyboard-a11y.js"></script>
<script type="text/javascript" src="framework/core/js/Fluid.js"></script>
<script type="text/javascript" src="framework/core/js/FluidDOMUtilities.js"></script>
<script type="text/javascript" src="framework/core/js/FluidIoC.js"></script>
<script type="text/javascript" src="framework/core/js/FluidView.js"></script>
<script type="text/javascript" src="framework/core/js/DataBinding.js"></script>
<script type="text/javascript" src="components/reorderer/js/ReordererDOMUtilities.js"></script>
<script type="text/javascript" src="components/reorderer/js/GeometricManager.js"></script>
<script type="text/javascript" src="components/reorderer/js/Reorderer.js"></script>
<script type="text/javascript" src="components/reorderer/js/ImageReorderer.js"></script>

The Image Reorderer also requires the following stylesheets:

<link rel="stylesheet" type="text/css" href="framework/core/css/fluid.css" />
<link rel="stylesheet" type="text/css" href="components/reorderer/css/Reorderer.css" />
<link rel="stylesheet" type="text/css" href="components/reorderer/css/ImageReorderer.css" />