mochikit_v14/doc/rst/MochiKit/Sortable.rst

   1 .. title:: MochiKit.Sortable - sortable with drag and drop lists
   2
   3 Name
   4 ====
   5
   6 MochiKit.Sortable - sortable with drag and drop lists
   7
   8
   9 Synopsis
  10 ========
  11
  12 ::
  13
  14     <ul id="dnd_sortable">
  15         <li>mochibot.com</li>
  16         <li>pythonmac.org</li>
  17         <li>undefined.org</li>
  18         <li>python.org</li>
  19     </ul>
  20     <script type="text/javascript">
  21       MochiKit.Sortable.Sortable.create('dnd_sortable');
  22     </script>
  23
  24
  25 Description
  26 ===========
  27
  28 MochiKit.Sortable add a new Sortable object to manipulate easily
  29 drag&drop in lists.
  30
  31
  32 Dependencies
  33 ============
  34
  35 - :mochiref:`MochiKit.Base`
  36 - :mochiref:`MochiKit.Iter`
  37 - :mochiref:`MochiKit.DOM`
  38 - :mochiref:`MochiKit.Color`
  39 - :mochiref:`MochiKit.Visual`
  40 - :mochiref:`MochiKit.Signal`
  41 - :mochiref:`MochiKit.DragAndDrop`
  42
  43 Overview
  44 ========
  45
  46 MochiKit.Sortable mainly contains the Sortable object offering
  47 facilities to manipulate a list and drag its items to reorder it. It
  48 can also be serialized for being send to server. It is ported from
  49 Scriptaculous_.
  50
  51 .. _Scriptaculous: http://script.aculo.us
  52
  53
  54 API Reference
  55 =============
  56
  57 Objects defined
  58 ---------------
  59
  60 :mochidef:`SortableObserver`:
  61
  62     Observer for DragAndDrop object. You normally don't have to access
  63     this, only for customization purpose.
  64
  65     *Availability*:
  66         Available in MochiKit 1.4+
  67
  68
  69 :mochidef:`Sortable.create(element [, options])`:
  70
  71     Create a new Sortable. Usually you'll call it with a UL element,
  72     but it can be customized with options to use something else.
  73
  74     You have the following options:
  75
  76     ================= ==================
  77     element           element
  78     tag               'li'
  79     dropOnEmpty       false
  80     overlap           'vertical'
  81     constraint        'vertical'
  82     containment       element
  83     handle            false
  84     only              false
  85     hoverclass        null
  86     ghosting          false
  87     scroll            false
  88     scrollSensitivity 20
  89     scrollSpeed       15
  90     format            /^[^_]*_(.*)$/
  91     onChange          MochiKit.Base.noop
  92     onUpdate          MochiKit.Base.noop
  93     tree              false
  94     treeTag           'ul'
  95     ================= ==================
  96
  97     ``tag``:
  98         Name of the tag used to make the draggable elements. It matches all
  99         the childNodes of the Sortable element with this tag.
 100
 101     ``only``:
 102         Class or array of classes used to filter the children, combined with
 103         the tag criteria.
 104
 105     ``format``:
 106         Regular expression which serves as a match filter for serialization,
 107         on children' ids. For example, with the default value, you'll get
 108         ['1', '2', '3', '4'] with ids ['sort_1', 'sort_2', 'sort_3', 'sort_4'].
 109
 110     ``onChange``:
 111         Callback called when an element moves between others in the Sortable.
 112         It's called for *each* movements, even if you don't release the mouse.
 113
 114     ``onUpdate``:
 115         Callback called when the order changes in the Sortable. It's called
 116         only if the Sortable is modified, after you dropped an element.
 117
 118     ``tree``:
 119         Option for creating a Sortable tree. It's an experimental
 120         setting, that can be very slow even with a few elements. You
 121         can customize its behaviour with the ``treeTag`` option, that
 122         defines the node used to make branches in your tree (that
 123         contains leaves).
 124
 125     Other options are passed to the Draggables and Droppables objects created.
 126     Refer to :mochiref:`MochiKit.DragAndDrop` for more information.
 127
 128     *Availability*:
 129         Available in MochiKit 1.4+
 130
 131
 132 :mochidef:`Sortable.destroy(element)`:
 133
 134     Destroy a previously created sortable. It prevents further use of
 135     the Sortable functionnality on the element, unless recreated.
 136
 137     *Availability*:
 138         Available in MochiKit 1.4+
 139
 140
 141 :mochidef:`Sortable.serialize(element [, options])`:
 142
 143     Serialize the content of a Sortable. Useful to send this content
 144     through a XMLHTTPRequest. The options overrides the ones of the Sortable
 145     only for the serialization.
 146
 147     ====== ==========================================
 148     tag    tag from the Sortable
 149     only   only from the Sortable
 150     name   id of the element
 151     format format of the Sortable or /^[^_]*_(.*)$
 152     ====== ==========================================
 153
 154     *Availability*:
 155         Available in MochiKit 1.4+
 156
 157
 158 Authors
 159 =======
 160
 161 - Thomas Herve <therve@gmail.com>
 162 - Bob Ippolito <bob@redivi.com>
 163 - Originally adapted from Script.aculo.us <http://script.aculo.us/>
 164
 165
 166 Copyright
 167 =========
 168
 169 Copyright 2005 Bob Ippolito <bob@redivi.com>.  This program is
 170 dual-licensed free software; you can redistribute it and/or modify it
 171 under the terms of the `MIT License`_ or the `Academic Free License
 172 v2.1`_.
 173
 174 .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
 175 .. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php
 176
 177 Portions adapted from `Scriptaculous`_ are available under the terms
 178 of the `MIT License`_.
 179
 180 .. _`Apache License, Version 2.0`: http://www.apache.org/licenses/LICENSE-2.0.html
 181