Wednesday, March 1, 2017

JqueryUI - Sortable

jQueryUI provides sortable() method to reorder elements in list or grid using the mouse. This method performs sortability action based upon an operation string passed as the first parameter.

Syntax

The sortable () method can be used in two forms −

$ (selector, context).sortable (options) Method

The sortable (options) method declares that an HTML element contains interchangeable elements. The options parameter is an object that specifies the behavior of the elements involved during reordering.

Syntax

$(selector, context).sortable(options);
The following table lists the different options that can be used with this method −
Sr.No. Option & Description
1 appendTo This option specifies the element in which the new element created with options.helper will be inserted during the time of the move/drag. By default its value is parent.
2 axis This option indicates an axis of movement ("x" is horizontal, "y" is vertical). By default its value is false.
3 cancel This option is used to prevent sorting of elements by clicking on any of the selector elements. By default its value is "input,textarea,button,select,option".
4 connectWith This option is a Selector that identifies another sortable element that can accept items from this sortable. This allows items from one list to be moved to other lists, a frequent and useful user interaction. If omitted, no other element is connected. This is a one-way relationship. By default its value is false.
5 containment This option indicates an element within which the displacement takes place. The element will be represented by a selector (only the first item in the list will be considered), a DOM element, or the string "parent" (parent element) or "window" (HTML page).
6 cursor Specifies the cursor CSS property when the element moves. It represents the shape of the mouse pointer. By default its value is "auto".
7 cursorAt Sets the offset of the dragging helper relative to the mouse cursor. Coordinates can be given as a hash using a combination of one or two keys: { top, left, right, bottom }. By default its value is "false".
8 delay Delay, in milliseconds, after which the first movement of the mouse is taken into account. The displacement may begin after that time. By default its value is "0".
9 disabled This option if set to true, disables the sortable functionality. By default its value is false.
10 distance Number of pixels that the mouse must be moved before the sorting starts. If specified, sorting will not start until after mouse is dragged beyond distance. By default its value is "1".
11 dropOnEmpty This option if set to false, then items from this sortable can't be dropped on an empty connect sortable. By default its value is true.
12 forceHelperSize If this option if set to true forces the helper to have a size. By default its value is false.
13 forcePlaceholderSize This option when set to true, takes into account the size of the placeholder when an item is moved. This option is only useful if options.placeholder is initialized. By default its value is false.
14 grid This option is an Array [x, y] indicating the number of pixels that the sorting element moves horizontally and vertically during displacement of the mouse. By default its value is false.
15 handle If specified, restricts sort from starting unless the mousedown occurs on the specified element(s). By default its value is false.
16 helper Allows for a helper element to be used for dragging display. By default its value is original.
17 items This option specifies which items inside the DOM element to be sorted. By default its value is > *.
18 opacity This option is used to define the opacity of the helper while sorting. By default its value is false.
19 placeholder This option is used to class name that gets applied to the otherwise white space.By default its value is false.
20 revert This option decides whether the sortable items should revert to their new positions using a smooth animation. By default its value is false.
21 scroll This option is used to enable scrolling. If set to true the page scrolls when coming to an edge. By default its value is true.
22 scrollSensitivity This option indicates how many pixels the mouse must exit the visible area to cause scrolling. By default its value is 20. This option is used only with options.scroll set to true.
23 scrollSpeed This option indicates the scrolling speed of the display once the scrolling begins. By default its value is 20.
24 tolerance This option is a String that specifies which mode to use for testing whether the item being moved is hovering over another item. By default its value is "intersect".
25 zIndex This option represents z-index for element/helper while being sorted. By default its value is 1000.
The following section will show you a few working examples of drag functionality.

Default functionality

The following example demonstrates a simple example of sortable functionality, passing no parameters to the sortable() method.
<!DOCTYPE html>
<html>
   <head>
      <title>jQuery UI Sortable - Example</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <style>
         #sortable-1 { list-style-type: none; margin: 0; 
            padding: 0; width: 25%; }
         #sortable-1 li { margin: 0 3px 3px 3px; padding: 0.4em; 
            padding-left: 1.5em; font-size: 17px; height: 16px; }
         .default {
            background: #cedc98;
            border: 1px solid #DDDDDD;
            color: #333333;
         }
      </style>
      
      <script>
         $(function() {
            $( "#sortable-1" ).sortable();
         });
      </script>
   </head>
   
   <body>
      <ul id = "sortable-1">
         <li class = "default">Product 1</li>
         <li class = "default">Product 2</li>
         <li class = "default">Product 3</li>
         <li class = "default">Product 4</li>
         <li class = "default">Product 5</li>
         <li class = "default">Product 6</li>
         <li class = "default">Product 7</li>
      </ul>
   </body>
</html>
Let us save the above code in an HTML file sortexample.htm and open it in a standard browser which supports javascript, you should see the following output. Now, you can play with the result −
Re-arrange the products above, use mouse to drag items.

Use of Options Delay and Distance

The following example demonstrates the usage of three options (a) delay and (b) distance in the sort function of JqueryUI.
<!DOCTYPE html>
<html>
   <head>
      <title>jQuery UI Sortable - Example</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <style>
         #sortable-2, #sortable-3 { list-style-type: none; margin: 0; 
            padding: 0; width: 25%; }
         #sortable-2 li, #sortable-3 li { margin: 0 3px 3px 3px; padding: 0.4em; 
            padding-left: 1.5em; font-size: 17px; height: 16px; }
         .default {
            background: #cedc98;
            border: 1px solid #DDDDDD;
            color: #333333;
         }
      </style>
      
      <script>
         $(function() {
            $( "#sortable-2" ).sortable({
               delay:500
            });
            $( "#sortable-3" ).sortable({
               distance:30
            });
         });
      </script>
   </head>
   
   <body>
      <h3>Delay by 500ms</h3>
      <ul id = "sortable-2">
         <li class = "default">Product 1</li>
         <li class = "default">Product 2</li>
         <li class = "default">Product 3</li>
         <li class = "default">Product 4</li>
      </ul>
      <h3>Distance Delay by 30px</h3>
      <ul id = "sortable-3">
         <li class = "default">Product 1</li>
         <li class = "default">Product 2</li>
         <li class = "default">Product 3</li>
         <li class = "default">Product 4</li>
      </ul>
   </body>
</html>
Let us save the above code in an HTML file sortexample.htm and open it in a standard browser which supports javascript, you should see the following output. Now, you can play with the result −
Re-arrange the products above, use mouse to drag items. To prevent accidental sorting either by delay (time) or distance, we have set a number of milliseconds the element needs to be dragged before sorting starts with the delay option. We have also set a distance in pixels the element needs to be dragged before sorting starts with the distance option.

Use of Placeholder

The following example demonstrates the usage of three option placeholder in the sort function of JqueryUI.
<!DOCTYPE html>
<html>
   <head>
      <title>jQuery UI Sortable - Example</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>

      <style>
         #sortable-4 { list-style-type: none; margin: 0; 
            padding: 0; width: 25%; }
         #sortable-4 li { margin: 0 3px 3px 3px; padding: 0.4em; 
            padding-left: 1.5em; font-size: 17px; height: 16px; }
         .highlight {
            border: 1px solid red;
            font-weight: bold;
            font-size: 45px;
            background-color: #333333;
         }
         .default {
            background: #cedc98;
            border: 1px solid #DDDDDD;
            color: #333333;
         }
      </style>
      
      <script>
         $(function() {
            $( "#sortable-4" ).sortable({
               placeholder: "highlight"
            });
         });
      </script>
   </head>
   
   <body>
      <ul id = "sortable-4">
         <li class = "default">Product 1</li>
         <li class = "default">Product 2</li>
         <li class = "default">Product 3</li>
         <li class = "default">Product 4</li>
         <li class = "default">Product 5</li>
         <li class = "default">Product 6</li>
         <li class = "default">Product 7</li>
      </ul>
   </body>
</html>
Let us save the above code in an HTML file sortexample.htm and open it in a standard browser which supports javascript, you should see the following output. Now, you can play with the result −
Try to drag items to rearrange them, while you're dragging items, the placeholder (we have used highlight class to style this space) will show up on an available place.

Use of Options Connectwith and Droponempty

The following example demonstrates the usage of three options (a) connectWith and (b) dropOnEmpty in the sort function of JqueryUI.
<!DOCTYPE html>
<html>
   <head>
      <title>jQuery UI Sortable - Example</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <style>
         #sortable-5, #sortable-6,#sortable-7 { 
            list-style-type: none; margin: 0; padding: 0;
            width: 20%;float:left }
         #sortable-5 li, #sortable-6 li,#sortable-7 li { 
            margin: 0 3px 3px 3px; padding: 0.4em; 
            padding-left: 1.5em; font-size: 17px; height: 16px; }
         .default {
            background: #cedc98;
            border: 1px solid #DDDDDD;
            color: #333333;
         }
      </style>
      
      <script>
         $(function() {
            $( "#sortable-5, #sortable-6" ).sortable({
               connectWith: "#sortable-5, #sortable-6"
            });
            $( "#sortable-7").sortable({
               connectWith: "#sortable-5",
               dropOnEmpty: false
            });
         });
      </script>
   </head>
   
   <body>
      <ul id = "sortable-5"><h3>List 1</h3>
         <li class = "default">A</li>
         <li class = "default">B</li>
         <li class = "default">C</li>
         <li class = "default">D</li>
      </ul>
      <ul id = "sortable-6"><h3>List 2</h3>
         <li class = "default">a</li>
         <li class = "default">b</li>
         <li class = "default">c</li>
         <li class = "default">d</li>
      </ul>
      <ul id = "sortable-7"><h3>List 3</h3>
         <li class = "default">e</li>
         <li class = "default">f</li>
         <li class = "default">g</li>
         <li class = "default">h</li>
      </ul>
   </body>
</html>
Let us save the above code in an HTML file sortexample.htm and open it in a standard browser which supports javascript, you should see the following output. Now, you can play with the result −
Sort items from one List1 into another (List2) and vice versa, by passing a selector into the connectWith option. This is done by grouping all related lists with a CSS class, and then pass that class into the sortable function (i.e., connectWith: '#sortable-5, #sortable-6').
Try to drag the items under List 3 to the List 2 or List 1. As we have set dropOnEmpty option to false, it won't be possible to drop these items.

$ (selector, context).sortable ("action", [params]) Method

The sortable (action, params) method can perform an action on the sortable elements, such as to prevent displacement. The action is specified as a string in the first argument and optionally, one or more params can be provided based on the given action.
Basically, here actions are nothing but they are jQuery methods which we can use in the form of string.

Syntax

$(selector, context).sortable ("action", [params]);
The following table lists the actions for this method −
Sr.No. Action & Description
1 cancel() This action cancels the current sort operation. This is most useful within handlers for the sort receive and sort stop events. This method does not accept any arguments.
2 destroy() This action removes the sortability functionality completely. This will return the element back to its pre-init state. This method does not accept any arguments.
3 disable() This action disables the sortability of any sortable elements in the wrapped set. The sortability of the elements isn’t removed and can be restored by calling the enable variant of this method. This method does not accept any arguments.
4 enable() Re-enables sortability on any sortable elements in the wrapped set whose sortability has been disabled. Note that this method won’t add sortability to any non-sortable elements. This method does not accept any arguments.
5 option( optionName ) This action gets the value currently associated with the specified optionName. Where optionName is the name of the option to get.
6 option() Gets an object containing key/value pairs representing the current sortable options hash.. This method does not accept any arguments.
7 option( optionName, value ) This action sets the value of the sortable option associated with the specified optionName. Where optionName is the name of the option to set and value is the value to set for the option.
8 option( options ) Sets one or more options for the sortable. Where options is a map of option-value pairs to set.
9 refresh() This action refreshes the list of items if necessary. This method does not accept any arguments. Calling this method will cause new items added to the sortable to be recognized.
10 toArray( options ) This method returns an array of the id values of the sortable elements in sorted order. This method takes Options as parameter, to customize the serialization or sorted order.
11 serialize( options ) This method returns a serialized query string (submittable via Ajax) formed from the sortable.
12 refreshPositions() This method is used mostly internally to refresh the cached information of the sortable. This method does not accept any arguments.
13 widget() This method returns a jQuery object containing the sortable element. This method does not accept any arguments.

Example

Now let us see an example using the actions from the above table. The following example demonstrates the use of toArray( options ) method.
<!DOCTYPE html>
<html>
   <head>
      <title>jQuery UI Sortable - Example</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src="https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <style>
         #sortable-8{ list-style-type: none; margin: 0; 
            padding: 0; width: 25%; float:left;}
         #sortable-8 li{ margin: 0 3px 3px 3px; padding: 0.4em; 
            padding-left: 1.5em; font-size: 17px; height: 16px; }
         .default {
            background: #cedc98;
            border: 1px solid #DDDDDD;
            color: #333333;
         }
      </style>
      
      <script>
         $(function() {
            $('#sortable-8').sortable({
               update: function(event, ui) {
                  var productOrder = $(this).sortable('toArray').toString();
                  $("#sortable-9").text (productOrder);
               }
            });
         });
      </script>
   </head>
   
   <body>
      <ul id = "sortable-8">
         <li id = "1" class = "default">Product 1</li>
         <li id = "2" class = "default">Product 2</li>
         <li id = "3" class = "default">Product 3</li>
         <li id = "4" class = "default">Product 4</li>
      </ul>
      <br>
      <h3><span id = "sortable-9"></span></h3>
   </body>
</html>
Let us save the above code in an HTML file sortexample.htm and open it in a standard browser which supports javascript, you should see the following output. Now, you can play with the result −
Try sorting the items, the order of items is displayed at the bottom. Here we are calling $(this).sortable('toArray').toString(), which will give a string list of all the item id's, it might look like 1,2,3,4.

Event Management on The Sortable Elements

In addition to the sortable (options) method which we saw in the previous sections, JqueryUI provides event methods as which gets triggered for a particular event. These event methods are listed below −
Sr.No. Event Method & Description
1 activate(event, ui) This event is triggered on the sortable when a sort operation starts on connected sortable.
2 beforeStop(event, ui) This event is triggered when the sort operation is about to end, with the helper and placeholder element reference still valid.
3 change(event, ui) This event is triggered when the sorted element changes position within the DOM.
4 create(event, ui) This event is triggered when the sortable is created.
5 deactivate(event, ui) This event is triggered when a connected sort stops, propagated to the connected sortable.
6 out(event, ui) This event is triggered when the sort item is moved away from a connected list.
7 over(event, ui) This event is triggered when a sort item moves into a connected list.
8 receive(event, ui) This event is triggered when a connected list has received a sort item from another list.
9 remove(event, ui) This event is triggered when the sort item is removed from a connected list and is dragged into another.
10 sort(event, ui) This event is repeatedly triggered for mousemove events during a sort operation.
11 start(event, ui) This event is triggered when a sort operation starts.
12 stop(event, ui) This event is triggered when a sort operation has concluded.
13 update(event, ui) This event is triggered when a sort operation stops and the position of the item has been changed.

Example

The following example demonstrates the event method usage during drop functionality. This example demonstrates the use of events receive, start and stop.
<!DOCTYPE html>
<html>
   <head>
      <title>jQuery UI Sortable - Example</title>
      <link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
         rel = "stylesheet">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <style>
         #sortable-10, #sortable-11 { list-style-type: none; 
            margin: 0; padding: 0; width: 80%; }
         #sortable-10 li, #sortable-11 li { margin: 0 3px 3px 3px; 
            padding: 0.4em; padding-left: 1.5em; 
            font-size: 17px; height: 16px; }
         .highlight {
            border: 1px solid #000000;
            font-weight: bold;
            font-size: 45px;
            background-color: #cedc98;
         }
         .default {
            background: #cedc98;
            border: 1px solid #DDDDDD;
            color: #333333;
         }
         .wrap {
            display: table-row-group;
         }
         .wrap1 {
            float:left;
            width: 100px;
         }
      </style>
      
      <script>
         $(function() {
            $( "#sortable-10" ).sortable({
               start: function (event, ui) {
                  $("span#result").html ($("span#result").html () 
                     + "<b>start</b><br>");
               },
               receive : function (event, ui) {
                  $("span#result").html ($("span#result").html () 
                     + ", receive");
               },
               stop: function (event, ui) {
                  $("span#result").html ($("span#result").html () 
                     + "<b>stop</b><br>");
               }
            });
            $( "#sortable-11" ).sortable({
               connectWith : "#sortable-10, #sortable-11"
            });
         });
      </script>
   </head>
   
   <body>
      <div class = "wrap">
         <div class = "wrap1"> 
            <h3>List 1</h3>
            <ul id = "sortable-10">
               <li class = "default">A</li>
               <li class = "default">B</li>
               <li class = "default">C</li>
               <li class = "default">D</li>
            </ul>
         </div>
         <div class = "wrap1">
            <h3>List 2</h3> 
            <ul id = "sortable-11">
               <li class = "default">a</li>
               <li class = "default">b</li>
               <li class = "default">c</li>
               <li class = "default">d</li>
            </ul>
         </div>
      </div>
      <hr />
      <span id = result></span>
   </body>
</html>
Let us save the above code in an HTML file sortexample.htm and open it in a standard browser which supports javascript, you should see the following output. Now, you can play with the result −
Try sorting the items in List 1, you will see the message getting displayed at the start and stop of event. Now drop items from List 2 to List 1, again a message gets displayed on the receive event.
Labels:

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)