Commit | Line | Data |
---|---|---|
6a1aa64f DV |
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 |