| 1 | .. title:: MochiKit.DragAndDrop - drag and drop elements with MochiKit |
| 2 | |
| 3 | Name |
| 4 | ==== |
| 5 | |
| 6 | MochiKit.DragAndDrop - drag and drop elements with MochiKit |
| 7 | |
| 8 | Synopsis |
| 9 | ======== |
| 10 | |
| 11 | :: |
| 12 | |
| 13 | // Create a draggable |
| 14 | new Draggable('mydrag'); |
| 15 | |
| 16 | // Create a corresponding droppable |
| 17 | new Droppable('mydrop', { |
| 18 | accept: ['drag-class'], |
| 19 | ondrop: function (element) { |
| 20 | alert('"' + element.id + '" was dropped on me'); |
| 21 | } |
| 22 | }); |
| 23 | |
| 24 | Description |
| 25 | =========== |
| 26 | |
| 27 | MochiKit.DragAndDrop enables you the power of dragging elements |
| 28 | through your pages, for richer interfaces. |
| 29 | |
| 30 | Dependencies |
| 31 | ============ |
| 32 | |
| 33 | - :mochiref:`MochiKit.Base` |
| 34 | - :mochiref:`MochiKit.Iter` |
| 35 | - :mochiref:`MochiKit.DOM` |
| 36 | - :mochiref:`MochiKit.Color` |
| 37 | - :mochiref:`MochiKit.Visual` |
| 38 | - :mochiref:`MochiKit.Signal` |
| 39 | |
| 40 | Overview |
| 41 | ======== |
| 42 | |
| 43 | The implementation was adapted from Scriptaculous_. |
| 44 | |
| 45 | .. _Scriptaculous: http://script.aculo.us |
| 46 | |
| 47 | API Reference |
| 48 | ============= |
| 49 | |
| 50 | Constructors |
| 51 | ------------ |
| 52 | |
| 53 | :mochidef:`Draggable(element[, options])`: |
| 54 | |
| 55 | A object that can be drag with the mouse. |
| 56 | |
| 57 | You have the following options, with corresponding default values: |
| 58 | |
| 59 | ``handle (false)``: |
| 60 | Option for giving the element where starting the drag. By |
| 61 | default it's the element itself, but you can either put a |
| 62 | class of a subelement or the id of another element as handle. |
| 63 | |
| 64 | ``starteffect (MochiKit.Visual.Opacity)``: |
| 65 | Function called once the drag has begun, taking the dragged |
| 66 | element as argument. It's an effect by default but you can |
| 67 | define any callback. |
| 68 | |
| 69 | ``reverteffect (MochiKit.Visual.Move)``: |
| 70 | Effect applied when drag is cancelled. You have to define the |
| 71 | ``revert`` option to enable the call. By default it brings the |
| 72 | element back to its initial position, so you should know what |
| 73 | you want when you modify this. The function should return an |
| 74 | effect that can be cancelled. |
| 75 | |
| 76 | ``endeffect (MochiKit.Visual.Opacity)``: |
| 77 | Pending part of starteffect. If you have modified your element |
| 78 | during start, you'd usually want to revert it in the function. |
| 79 | |
| 80 | ``zindex (1000)``: |
| 81 | Zindex of the drag element. By default it brings it to front. |
| 82 | |
| 83 | ``revert (false)``: |
| 84 | Indicate if the reverteffect function should be called. If you |
| 85 | define a function here, this function will be called before |
| 86 | reverteffect, with the element as first argument. |
| 87 | |
| 88 | ``snap (false)``: |
| 89 | Define the behaviour of the drag element when moving. It can |
| 90 | either be a function, a value or an array of two values. If |
| 91 | it's a function, it should take the (x, y) position of the |
| 92 | element as arguments, and return the position draw in the |
| 93 | browser. If its a value, it's used as a modulo for each |
| 94 | coordinates. If it's an array, each value is applied for the |
| 95 | corresponding coordinate. |
| 96 | |
| 97 | ``selectclass (null)``: |
| 98 | If defined, name of CSS class applied during the drag. |
| 99 | |
| 100 | ``ghosting (null)``: |
| 101 | Make a ghost from the draggable: clone it at start, then |
| 102 | remove the clone at end. |
| 103 | |
| 104 | ``onchange (MochiKit.Base.noop)``: |
| 105 | Function called when updates are made on the draggable object. |
| 106 | |
| 107 | ``scroll (false)``: |
| 108 | Element to scroll around, if precised. For example, 'window' |
| 109 | will allow the draggable to scroll in the page. |
| 110 | |
| 111 | ``scrollSensitivity (20)``: |
| 112 | Scroll sensitivity, used when scroll is used. |
| 113 | |
| 114 | ``scrollSpeed (15)``: |
| 115 | Scroll speed, used when scroll is used. |
| 116 | |
| 117 | A draggable generates some signals during its lifetime: start, drag and |
| 118 | end. They are available through the Draggables handler, and are called |
| 119 | with a draggable as argument. You can register a callback for these events |
| 120 | like this:: |
| 121 | |
| 122 | onStart = function (draggable) { |
| 123 | // Do some stuff |
| 124 | }; |
| 125 | |
| 126 | connect(Draggables, 'start', onStart); |
| 127 | |
| 128 | |
| 129 | *Availability*: |
| 130 | Available in MochiKit 1.4+ |
| 131 | |
| 132 | |
| 133 | :mochidef:`Droppable(element[, options])`: |
| 134 | |
| 135 | A object where you can drop a draggable. |
| 136 | |
| 137 | You have the following options, with corresponding default values: |
| 138 | |
| 139 | ``greedy (true)``: |
| 140 | Stop on this droppable when a draggable drops over it. |
| 141 | |
| 142 | ``hoverclass (null)``: |
| 143 | If defined, name of CSS class applied when a draggable is |
| 144 | hover the droppable element (hover state). |
| 145 | |
| 146 | ``hoverfunc (MochiKit.Base.noop)``: |
| 147 | Function called on hover state. |
| 148 | |
| 149 | ``accept (null)``: |
| 150 | Array of CSS classes allowed to drop on this. |
| 151 | |
| 152 | ``activeclass (null)``: |
| 153 | If defined, name of CSS class applied if a possible draggable |
| 154 | begins its start (active state). |
| 155 | |
| 156 | ``onactive (MochiKit.Base.noop)``: |
| 157 | Function called on active state. |
| 158 | |
| 159 | ``containment ([])``: |
| 160 | Specify a list of elements to check for active state: only the |
| 161 | children of the specified elements can be dropped. Mainly |
| 162 | useful for Sortable. |
| 163 | |
| 164 | ``onhover (MochiKit.Base.noop)``: |
| 165 | Specific hover function, mainly used for Sortable. |
| 166 | |
| 167 | ``ondrop (MochiKit.Base.noop)``: |
| 168 | Function called when a draggable is dropped. The function |
| 169 | takes three arguments: the draggable element, the droppable |
| 170 | element, and the event that raised the drop. |
| 171 | |
| 172 | *Availability*: |
| 173 | Available in MochiKit 1.4+ |
| 174 | |
| 175 | |
| 176 | Authors |
| 177 | ======= |
| 178 | |
| 179 | - Thomas Herve <therve@gmail.com> |
| 180 | - Bob Ippolito <bob@redivi.com> |
| 181 | - Originally adapted from Script.aculo.us <http://script.aculo.us/> |
| 182 | |
| 183 | Copyright |
| 184 | ========= |
| 185 | |
| 186 | Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is |
| 187 | dual-licensed free software; you can redistribute it and/or modify it |
| 188 | under the terms of the `MIT License`_ or the `Academic Free License |
| 189 | v2.1`_. |
| 190 | |
| 191 | .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php |
| 192 | .. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php |
| 193 | |
| 194 | Portions adapted from `Scriptaculous`_ are available under the terms |
| 195 | of the `MIT License`_. |
| 196 | |
| 197 | |