REDIPS.drag documentation

Namespace Summary
Constructor Attributes Constructor Name and Description
 
REDIPS.drag Version 5.3.0 (2020-03-21)

REDIPS.drag is a JavaScript drag and drop library focused on dragging table content (DIV elements) and table rows.

See:
REDIPS.drag documentation – Appendix A
jsFiddle examples
Drag and drop table content plus animation
Drag and drop table rows
Drag and Drop table content
JavaScript drag and drop plus content shift
Field Summary
Field Attributes Field Name and Description
 
Object contains animation properties: pause and step.
 
Object defines several rules related to cloning DIV elements like enable cloning with shift key, enable returning cloned DIV element to its source and so on.
 
Property defines working types of REDIPS.drag library for dragging DIV elements: multiple, single, switch, switching, overwrite and shift.
 
Hover object contains 4 properties: colorTd, colorTr, borderTd and borderTr.
 
Table cells marked with “redips-mark” class name can be allowed or forbidden for accessing (with exceptions) – default is “deny”.
 
Dragging mode “cell” or “row” (readonly).
 
Property defines “top” or “bottom” position of dropped element in table cell (if cell already contains DIV elements).
 
obj
Currently moved DIV element.
 
Previously moved DIV element (before clicked or cloned).
 
Table cells marked with “redips-only” class name can accept only defined DIV elements.
 
Property defines working types of REDIPS.drag library for dragging table rows: before, after, switch and overwrite.
 
Save content parameter name.
 
Scroll object contains properties needed for autoscroll option.
 
Object contains several properties: shift.after, shift.mode, shift.overflow and shift.animation.
 
Object contains styles (colors, opacity levels) for DIV elements and table rows.
 
Table sort is feature where tables inside drop container are sorted on each element click.
 
td
Object contains reference to previous, source, current and target table cell.
 
Object contains td class name (where DIV elements can be deleted) and confirmation questions for deleting DIV element or table row.
Method Summary
Method Attributes Method Name and Description
 
ajaxCall(url, callBack, obj)
Method calls AJAX service (using GET or POST method) and runs callback function with xhr (XMLHttpRequest) object as input parameter (xhr object is implicitly created only first time).
 
Method deletes all DIV elements with redips-drag class name from table.
 
cloneObject(div, drag)
Method clones DIV element and returns cloned element reference.
 
Method deletes DIV element from table.
 
emptyCell(tdElement, mode)
Method tests TD if is empty or removes elements from table cell.
 
enableDrag(enableFlag, el)
Method attaches / detaches onmousedown, ontouchstart and ondblclick events to DIV elements and attaches onscroll event to the scroll containers in initialization phase.
 
enableTable(enableFlag, el)
This method can select tables by class name and mark them as enabled / disabled.
 
findCell(param, el)
Method returns data (cell reference, row index and column index) for first or last cell in table or row / column.
 
findParent(tagName, el, skip)
Method returns reference of parent DOM element.
 
Method returns position as array with members tableIndex, rowIndex and cellIndex (array length is 3).
 
Method returns current page scroll values as array (X and Y axis).
 
getStyle(el, styleName)
Method returns style value for requested HTML element and style name.
 
init(dc)
Drag container initialization.
 
initTables(selector)
Tables layout initialization (preparing internal “tables” array).
 
loadContent(targetTable, param)
Method inserts DIV elements to the target table.
 
Method will calculate parameters and start animation (DIV element to the target table cell).
 
relocate(from, to, mode)
Method relocates DIV elements from source table cell to the target table cell (with optional animation).
 
rowEmpty(tblId, rowIdx, color)
Method marks selected row as empty.
 
rowOpacity(el, opacity, color)
Method sets opacity to table row or deletes row content.
 
saveContent(tbl, type)
Method scans table content and prepares query string or JSON format for submitting to the server script.
 
shiftCells(td1, td2)
Method shifts table content horizontally or vertically.
Event Summary
Event Attributes Event Name and Description
 
error.ajax(xhr, obj)
This method enables handling HTTP AJAX errors.
 
Error handler invoked if is not possible to place DIV element to the target table during content loading.
 
event.changed(currentCell)
Event handler invoked on every change of current (highlighted) table cell.
 
event.clicked(currentCell)
Event handler invoked if a mouse button is pressed down while the mouse pointer is over DIV element.
 
event.cloned(clonedElement)
Event handler invoked after DIV element is cloned – interactively by moving DIV element or by calling moveObject() in “cell” mode with “clone” option.
 
event.clonedDropped(targetCell)
Event handler invoked after cloned DIV element is dropped.
 
Event handler invoked if last element is cloned (type 1).
 
Event handler invoked if last element is cloned (type 2).
 
Event handler invoked if a mouse button is clicked twice while the mouse pointer is over DIV element.
 
event.deleted(cloned)
Event handler invoked if element is deleted (dropped to the “trash” table cell).
 
event.dropped(targetCell)
Event handler invoked if element is dropped to the table cell.
 
event.droppedBefore(targetCell)
Event handler invoked if mouse button is released but before element is dropped to the table cell.
 
Event handler invoked after any DIV element action.
 
event.moved(cloned)
Event handler invoked if element is moved from home position.
 
Event handler invoked if cloned element is dropped on start position or cloned element is dropped outside current table with “clone.drop” property set to false.
 
Event handler invoked if mouse button is pressed down and released while the mouse pointer is over DIV element (element was not actually moved).
 
Event handler invoked after DIV element is relocated.
 
Event handler invoked before DIV element will be relocated.
 
Event handler invoked after all DIV elements are relocated and before table is enabled (DIV elements enabled for dragging).
 
event.rowChanged(currentCell)
Event handler invoked on every change of current (highlighted) table row.
 
event.rowClicked(currentCell)
Event handler invoked if a mouse button is pressed down while the mouse pointer is over row handler (div class=”redips-drag redips-row”).
 
Event handler invoked if table row is cloned.
 
Event handler invoked if row is deleted (dropped to the “trash” table cell).
 
event.rowDropped(targetRow, sourceTable, sourceRowIndex)
Event handler invoked after dropping row to the table.
 
event.rowDroppedBefore(sourceTable, sourceRowIndex)
Event handler invoked in the moment when mouse button is released but before row is dropped to the table.
 
Event handler invoked if row is moved around and dropped to the home position.
 
Event handler invoked if row is moved from home position.
 
Event handler invoked if cloned row is dropped to the source row.
 
Event handler invoked if a mouse button is pressed down and released while the mouse pointer is over row handler (row was not actually moved).
 
Event handler invoked if row is undeleted.
 
Event handler invoked in a moment when overflow happen in shift mode.
 
event.switched(targetCell)
Event handler invoked if DIV elements are switched (dropMode is set to “switch”).
 
Event handler invoked if element is undeleted.
Field Detail

{Object} animation
Object contains animation properties: pause and step.

  • {Integer} animation.pause – Animation pause (lower values means the animation will go faster). Default value is 20 (milliseconds).
  • {Integer} animation.step – Value defines number of pixels in each step. Higher values means bigger step (faster animation) but with less smoothness. Default value is 2 (px).

{Object} clone
Object defines several rules related to cloning DIV elements like enable cloning with shift key, enable returning cloned DIV element to its source and so on. Instead of moving, DIV element / row will be cloned and ready for dragging. Just press SHIFT key and try to drag DIV element / row. if clone.sendBack property set to true, cloned DIV element will be deleted when dropped to the cell containing its source clone element. If exists, “climit” class will be updated (increased by 1). clone.drop property defines placing cloned DIV element (dropped outside any table) to the last marked position. If this property is set to true, the cloned DIV element will be always placed to the table cell.

  • {Boolean} clone.keyDiv – If set to true, all DIV elements on tables could be cloned with pressed SHIFT key. Default is false.
  • {Boolean} clone.keyRow – If set to true, table rows could be cloned with pressed SHIFT key. Default is false.
  • {Boolean} clone.sendBack – If set to true, cloned element can be returned to its source. Default is false.
  • {Boolean} clone.drop – If set to true, cloned element will be always placed to the table (to the last possible cell) no matter if is dropped outside the table. Default is false.

{String} dropMode
Property defines working types of REDIPS.drag library for dragging DIV elements: multiple, single, switch, switching, overwrite and shift.
// elements can be dropped to all table cells (multiple elements in table cell)
REDIPS.drag.dropMode = 'multiple';

// elements can be dropped only to the empty table cells
REDIPS.drag.dropMode = 'single';

// switch content
REDIPS.drag.dropMode = 'switch';

// switching content continuously
REDIPS.drag.dropMode = 'switching';

// overwrite content in table cell
REDIPS.drag.dropMode = 'overwrite';

// shift table content after element is dropped or moved to trash cell
REDIPS.drag.dropMode = 'shift';
Default Value:
multiple

{Object} hover
Hover object contains 4 properties: colorTd, colorTr, borderTd and borderTr. colorTd and colorTr define hover color for DIV element and table row. If borderTd is defined, then highlighted cell will have border. If borderTr is defined then highlighted row will have only top or bottom border. Top border shows that row will be placed above current row, while bottom border shows that current row will be placed below current row. Some browsers may have problem with “border-collapse:collapse” table style and border highlighting. In that case try without collapsing TD borders (e.g set “border-spacing:0” and smaller “td.border-width”).
// set "#9BB3DA" as hover color for TD
REDIPS.drag.hover.colorTd = '#9BB3DA';

// or set "Lime" as hover color for TR
REDIPS.drag.hover.colorTr = 'Lime';

// set red border for highlighted TD
REDIPS.drag.hover.borderTd = '2px solid red';

{Object} mark
Table cells marked with “redips-mark” class name can be allowed or forbidden for accessing (with exceptions) – default is “deny”. This is useful to define table cells forbidden for every DIV element with exceptions (or contrary, define table cells allowed for all DIV elements except some). Object contains:

  • {String} action – allow / deny table cell (default is “deny”)
  • {String} cname – class name of marked cells (default is “redips-mark”)
  • {Array} exception – defined DIV elements can be dropped to the table cells marked with class “redips-mark” (DIV id -> class name)
// only element with Id "d8" can be dropped to the cell with class name "mark smile"
REDIPS.drag.mark.exception.d8 = 'smile';
See:
only

{String} mode
Dragging mode “cell” or “row” (readonly). This is readonly property defined in a moment when DIV element or row handler is clicked.

{String} multipleDrop
Property defines “top” or “bottom” position of dropped element in table cell (if cell already contains DIV elements). It has affect only in case of dropMode=”multiple”.
// place dropped elements to cell top
REDIPS.drag.multipleDrop = 'top';
Default Value:
bottom

{HTMLElement} obj
Currently moved DIV element. Reference to the REDIPS.drag.obj (dragged DIV element) is visible and can be used in appropriate event handlers.

{HTMLElement} objOld
Previously moved DIV element (before clicked or cloned). In case when DIV element is cloned, obj is reference of current (cloned) DIV element while objOld is reference of bottom (origin) DIV element.

{Object} only
Table cells marked with “redips-only” class name can accept only defined DIV elements. Object contains:

  • {Array} div – defined DIV elements can be dropped only to the table cells marked with class name “redips-only” (DIV id -> class name)
  • {String} cname – class name of marked cells (default is “redips-only”)
  • {String} other – allow / deny dropping DIV elements to other table cells (default is “deny”)
// only element with Id "a1" can be dropped to the cell with class name "redips-only last"
REDIPS.drag.only.div.a1 = 'last';

// DIV elements mentioned in REDIPS.drag.only.div cannot be dropped to other cells
REDIPS.drag.only.other = 'deny';
See:
mark

{String} rowDropMode
Property defines working types of REDIPS.drag library for dragging table rows: before, after, switch and overwrite.

  • before – row will be dropped before highlighted row
  • after – row will be dropped after highlighted row
  • switch – source and highlighted rows will be switched
  • overwrite – highlighted row will be overwritten

Values “before” and “after” have effect only if row is dropped to other tables (not in current table). In case of only one table, after/before is defined relatively to source row position (middle row will be dropped before highlighted row if dragged to the table top or after highlighted row in other case).

Default Value:
before

{String} saveParamName
Save content parameter name. Parameter name should be short because it will be repeated for every DIV element. It is irrelevant in case of JSON format.
Default Value:
p

{Object} scroll
Scroll object contains properties needed for autoscroll option.

  • {Boolean} scroll.enable – Enable / disable autoscroll option. By default autoscroll is enabled but it can be usefull in some cases to completely turn off autoscroll (if application doesn’t need autoscrolling page nor autoscrolling DIV container). Turning off autoscroll will speed up application because extra calculations will be skipped. Default is true
  • {Integer} scroll.bound – Bound size for triggering page autoScroll or autoScroll of scrollable DIV container. Default value is 25 (px).
  • {Integer} scroll.speed – Autoscroll pause in milliseconds. Default value is 20 (milliseconds).

{Object} shift
Object contains several properties: shift.after, shift.mode, shift.overflow and shift.animation.

  • {String} shift.after – how to shift table content after DIV element is dropped
  • {String} shift.mode – shift modes (horizontal / vertical)
  • {String|HTMLElement} shift.overflow – defines how to behave when DIV element falls off the end
  • {Boolean} shift.animation – if set to true, table content will be relocated with animation – default is false

shift.after option has the following values: “default”, “delete” and “always” (this property will have effect only if dropMode is set to “shift”). Default value is “default”.

  • default – table content will be shifted only if DIV element is dropped to the non empty cell
  • delete – same as “default” + shift table content after DIV element is moved to trash
  • always – table content will be always shifted

shift.mode defines shift modes: “horizontal1”, “horizontal2”, “vertical1” and “vertical2”. Default value is “horizontal1”.

  • horizontal1 – horizontal shift (element shift can affect more rows)
  • horizontal2 – horizontal shift (each row is treated separately)
  • vertical1 – vertical shift (element shift can affect more columns)
  • vertical2 – vertical shift (each column is treated separately)

shift.overflow defines how to behave when DIV element falls off the end. Possible actions are: “bunch”, “delete” and “source”. Default value is “bunch”.

  • bunch – overflow will stay in last cell
  • delete – overflow will be deleted
  • source – overflow will be moved to the source TD
  • {HTMLElement} – overflow will be moved to user defined HTML element
// DIV elements will be shifted vertically (each column is treated separately)
REDIPS.drag.shift.mode = 'vertical2';

// delete overflowed DIV element
REDIPS.drag.shift.overflow = 'delete';
See:
dropMode
shiftCells

{Object} style
Object contains styles (colors, opacity levels) for DIV elements and table rows.

  • {String} style.borderEnabled – Border style for enabled DIV elements. Default is “solid”.
  • {String} style.borderDisabled – Border style for disabled DIV elements. Default is “dotted”.
  • {Integer} style.opacityDisabled – Opacity level for disabled elements. Default is empty string.
  • {String} style.rowEmptyColor – “Empty row” color. When last row from table is moved then this color will be set to “empty row”. Default is “white”.
// define border style for disabled elements
REDIPS.drag.style.borderDisabled = 'dashed';

{Boolean} tableSort
Table sort is feature where tables inside drop container are sorted on each element click. Clicked DIV element defines table that should be placed on the array top. Tables order is important for highlighting current cell in case of nested tables. But sometimes this feature should be turned off when one table overlays the other using “position” style relative, fixed or absolute.
Default Value:
true

{Object} td
Object contains reference to previous, source, current and target table cell. Td references can be used in event handlers.

  • {HTMLElement} td.source – reference to source table cell (set in onmousedown)
  • {HTMLElement} td.previous – reference to previous table cell (set in onmousemove and autoscroll)
  • {HTMLElement} td.current – reference to current table cell (set in onmousemove and autoscroll)
  • {HTMLElement} td.target – reference to target table cell (target table cell is set in a moment of dropping element to the table cell)

{Object} trash
Object contains td class name (where DIV elements can be deleted) and confirmation questions for deleting DIV element or table row.

  • {String} trash.className – Class name of td which will become trash can. Default value is “redips-trash”.
  • {String} trash.question – If trash.question is set then popup will appear and ask to confirm element deletion. Default value is null.
  • {String} trash.questionRow – If trash.questionRow is set then popup will appear and ask to confirm row deletion. Default value is null.
// confirm DIV element delete action
REDIPS.drag.trash.question = 'Are you sure you want to delete DIV element?';

// confirm row delete action
REDIPS.drag.trash.questionRow = 'Are you sure you want to delete table row?';
Method Detail

ajaxCall(url, callBack, obj)
Method calls AJAX service (using GET or POST method) and runs callback function with xhr (XMLHttpRequest) object as input parameter (xhr object is implicitly created only first time). Callback function as input parameter is optional but error handling can be defined for such AJAX call anyway. Input parameter “obj” is just passed to the callback method and is also optional in both ways (as input parameter in ajaxCall or for using in callback). obj is not only needed for optional AJAX settings but it can be useful for sending additional parameters to the callback function. In case of AJAX error (xhr.status !== 200), error.ajax() handler will be called with xhr and obj objects as input parameters. Here are examples how to initiate AJAX call, set AJAX handler and error handler:
// simple AJAX call without callback function
REDIPS.drag.ajaxCall('ajax_save.php?a=1&b=2');

// simple AJAX call (GET method)
REDIPS.drag.ajaxCall('ajax_menu.php?month=2&year=2017', myHandler);

// AJAX call with passing dragged element as div property
REDIPS.drag.ajaxCall('ajax_menu.php?month=2&year=2017', myHandler, {div: rd.obj});

// AJAX call with POST method and data in name-value format
// header 'application/x-www-form-urlencoded' is automatically applied
REDIPS.drag.ajaxCall('ajax_menu.php', myHandler, {method: 'POST', data: 'name1=value1&name2=value2'});

// xhr is XMLHttpRequest object and obj is passed from ajaxCall() to this callback function
// obj is optionally defined and if is not needed then it can be omitted as input parameter
myHandler = function (xhr, obj) {
    ...
    ...
};

// it is also possible to wrap error handling inside callback function
// this can be useful in case of many different AJAX calls with specific error processing to each call
myHandler = function (xhr, obj) {
    // if status is OK
    if (xhr.status === 200) {
        ...
    }
    // otherwise display error
    else {
        setTimeout(function () {
            alert('AJAX error: [' + xhr.status + '] ' + xhr.statusText);
        }, 10);
    }
};


// general error handler called in case of AJAX error (if xhr.status !== 200)
// obj is optional parameter
REDIPS.drag.error.ajax = function (xhr, obj) {
    // non blocking alert (alert called with setTimeout())
    setTimeout(function () {
        alert('AJAX error: [' + xhr.status + '] ' + xhr.statusText);
    }, 10);
    // return false to stop execution of callback function
    return false;
};
Parameters:
{String} url
URL address of AJAX service. In case of GET method it should contain all parameters in name-value format.
{Object} callBack Optional
Callback function called after request is ended (successfully or not). Function is called with xhr (XMLHttpRequest) object and obj object as input parameters.
{Object} obj Optional
Object with optional AJAX parameters (like POST method and data) or used for sending additional parameters to the callback function.
See:
error.ajax

clearTable(el)
Method deletes all DIV elements with redips-drag class name from table. Input parameter is table id or table reference.
// delete all DIV elements from table with id=tbl1
rd.clearTable('tbl1');
Parameters:
{String|HTMLElement} el
Table Id or table reference from which all elements should be deleted.

{HTMLElement} cloneObject(div, drag)
Method clones DIV element and returns cloned element reference. “redips-clone” class name will not be copied in cloned element (in case if source element contains “redips-clone” class name). This method is called internally when DIV elements are cloned.
Parameters:
{HTMLElement} div
DIV element to clone.
{Boolean} drag Optional
If set to true, then cloned DIV element will be ready for dragging (otherwise element will be only cloned).
Returns:
{HTMLElement} Returns cloned DIV element.

deleteObject(el)
Method deletes DIV element from table. Input parameter is DIV reference or id of DIV element.
// delete DIV element in event.dropped() event handler
rd.event.dropped = function () {
    rd.deleteObject(rd.obj);
}

// delete DIV element with id="d1"
rd.deleteObject('d1');
Parameters:
{String|HTMLElement} el
Id of DIV element or reference of DIV element that should be deleted.

{Boolean|Array} emptyCell(tdElement, mode)
Method tests TD if is empty or removes elements from table cell. Cell is considered as empty if does not contain any child nodes or if cell has only one text node. In other words, if cell contains only text then it will be treated as empty cell.
// set REDIPS.drag reference
var rd = REDIPS.drag;
// search for TABLE element (from cell reference)
tbl = rd.emptyCell(td);

// how to test TD if cell is occupied
var empty = rd.emptyCell(td, 'test');
Parameters:
{HTMLElement} tdElement
Table cell to test or from which all the elements will be deleted.
{String} mode Optional
If mode is set to “test” then method will only test TD and return true or false.
Returns:
{Boolean|Array} Returns true/false depending on cell content or array with deleted child nodes.

enableDrag(enableFlag, el)
Method attaches / detaches onmousedown, ontouchstart and ondblclick events to DIV elements and attaches onscroll event to the scroll containers in initialization phase. It also can be used for element initialization after DIV element was manually added to the table. If class attribute of DIV container contains “redips-noautoscroll” class name then autoScroll option will be disabled.
// enable element with id="id123" (element id should be string according to DOM docs)
rd.enableDrag(true, '#id123');

// or init manually added element with known id
REDIPS.drag.enableDrag(true, '#id234');

// disable all DIV elements in drag1 subtree
rd.enableDrag(false, '#drag1 div')

// init DIV elements in dragging area (including newly added DIV element)
// DIV initialization will work if table node stays intact (table is not generated dynamically)
REDIPS.drag.enableDrag('init');

// init added element with reference myElement
REDIPS.drag.enableDrag(true, myElement);

// disable all DIV elements within TD (td is reference to TD node)
REDIPS.drag.enableDrag(false, td);
Parameters:
{Boolean|String} enableFlag
Enable / disable element (or element subtree like table, dragging container …).
{HTMLElement|String} el Optional
HTML node or CSS selector to enable / disable. Parameter defines element reference or CSS selector of DIV elements to enable / disable.
See:
init
enableTable

enableTable(enableFlag, el)
This method can select tables by class name and mark them as enabled / disabled. Instead of class name, it it possible to send table reference for enable / disable. By default, all tables are enabled to accept dropped elements.
// disable tables with class name 'mini'
enableTable(false, 'mini');
Parameters:
{Boolean} enableFlag
Enable / disable one or more tables.
{String|HTMLElement} el
Class name of table(s) to enable/disable or table reference to enable/disable.
See:
enableDrag

{Array} findCell(param, el)
Method returns data (cell reference, row index and column index) for first or last cell in table or row / column.
// find first cell in row (el is table cell reference)
firstInRow = findCell('firstInRow', el);

// find last cell in table (el is reference of any cell inside table)
last = findCell('last', el);

// find last cell in column (el is table cell reference)
lastInColumn = findCell('lastInColumn', el);
Parameters:
{String} param
Parameter defines first or last table cell (values are “first”, “firstInColumn”, “firstInRow”, “last”, “lastInColumn”, “lastInRow”).
{HTMLElement} el
Table cell reference (td). For “first” or “last” request, el can be any HTMLElement within table.
Returns:
{Array} Returns array with row index, column index and cell reference,

{HTMLElement} findParent(tagName, el, skip)
Method returns reference of parent DOM element.
// find parent TABLE element (from cell reference)
tbl = findParent('TABLE', cell);

// find reference of the outside table (start node is TD in inner table - first TABLE node should be skipped)
tbl = findParent('TABLE', cell, 1);
Parameters:
{String} tagName
Tag name of parent element.
{HTMLElement} el
Start position to search.
{Integer} skip Optional
How many found nodes should be skipped. For example when start node is TD in inner table and findParent() should return reference of the outside table.
Returns:
{HTMLElement} Returns reference of the found parent element.

{Array} getPosition(ip)
Method returns position as array with members tableIndex, rowIndex and cellIndex (array length is 3). If input parameter is not defined then method will return array with current and source positions (array length will be 6).
// set REDIPS.drag reference
var rd = REDIPS.drag;
// display target and source position of dropped element
rd.event.dropped = function () {
   // get target and source position (method returns positions as array)
   // pos[0] - target table index
   // pos[1] - target row index
   // pos[2] - target cell (column) index
   // pos[3] - source table index
   // pos[4] - source row index
   // pos[5] - source cell (column) index
   var pos = rd.getPosition();
   // display element positions
   console.log(pos);
};
Parameters:
{String|HTMLElement} ip Optional
DIV element id / reference or table cell id / reference.
Returns:
{Array} Returns array with members tableIndex, rowIndex and cellIndex. If position is not found then all array members will have value -1.

{Array} getScrollPosition()
Method returns current page scroll values as array (X and Y axis).
Returns:
{Array} Returns array with two values [ scrollX, scrollY ].

{String} getStyle(el, styleName)
Method returns style value for requested HTML element and style name.
Parameters:
{HTMLElement} el
Requested HTML element.
{String} styleName
Asked style name.
Returns:
{String} Returns style value.
See:
http://www.quirksmode.org/dom/getstyles.html

init(dc)
Drag container initialization. It should be called at least once and it’s possible to call a method many times. Every page should have at least one drag container. If REDIPS.drag.init() is called without input parameter, library will search for drag container with id=”redips-drag”. Only tables inside drag container will be scanned. It is possible to have several drag containers totaly separated (elements from one container will not be visible to other drag containers). “init” method calls initTables and enableDrag. If tables are generated dynamically then REDIPS.init() method should be called to set custom properties to tables (table initialization).
// init drag container (with default id="redips-drag")
REDIPS.drag.init();

// init drag container with id="my-drag1"
REDIPS.drag.init('my-drag1');
Parameters:
{String} dc Optional
Drag container Id (default is “redips-drag”).
See:
initTables
enableDrag

initTables(selector)
Tables layout initialization (preparing internal “tables” array). Method searches for all tables inside defined selectors and prepares “tables” array. Default selector is “#redips-drag table”. Tables with className “redips-nolayout” are ignored (e.g. table with “redips-nolayout” class name in DIV element can be dragged as any other content). “tables” array is one of the main parts of REDIPS.drag library.
// call initTables after new empty table is added to the div#redips-drag
// REDIPS.init() method will also work but with some overhead
REDIPS.drag.initTables();

// change default selector for table search (div#sticky may contain table that is attached out of default drag container)
// this means that table should not be a part of div#redips-drag, but it should be positioned within drag container otherwise dragging will not work
REDIPS.drag.initTables('#my-drag table, #sticky table');

// if new table is not empty and contains DIV elements then they should be enabled also
// DIV elements in "redips-drag" container are enabled by default
REDIPS.drag.initTables('#my-drag table, #sticky table');
REDIPS.drag.enableDrag(true, '#sticky div');
Parameters:
{String} selector Optional
Defines selector for table search (default id “#redips-drag table”).

loadContent(targetTable, param)
Method inserts DIV elements to the target table. Target table can be defined as string (id) or reference. In case of wrong table reference, error.loadContent() event handler will be called with error type 0 (non-recoverable error). Second parameter could be formed in the following ways:

  • Absolute or relative URL of AJAX service that returns JSON data (e.g. ‘/service/db_data.php’)
  • JSON text containing information how to insert DIV elements
  • Array containing information how to insert DIV elements

Form of JSON text or array is the same as produced from saveContent() method: [[“id”,r,c,”n”,”t”],[“id”,r,c,”n”,”t”], …]

  • id – element id
  • r – row index
  • c – cell index
  • n – class names
  • t – DIV innerHTML
// load content from AJAX service to table with reference targetTable
REDIPS.drag.loadContent(targetTable, 'db_ajax1.php');

// load content from JSON text to table with reference targetTable
REDIPS.drag.loadContent(targetTable, '[["d16", 6, 2, "orange", "B2"], ["d17", 7, 4, "orange", "B1"]]');

// load content from array to table with id "myTable"
REDIPS.drag.loadContent('myTable', [["d6", 6, 2, "green", "A2"], ["d7", 7, 4, "green", "A1"]]);
Parameters:
{HTMLElement|String} targetTable
Reference or id of target table where DIV elements will be inserted
{String|Array} param
JSON text or array (JSON formatted array) or AJAX URL to retrieve JSON data
See:
saveContent
error.loadContent

{Array|Boolean} moveObject(ip)
Method will calculate parameters and start animation (DIV element to the target table cell). “moveObject” will always move DIV element with animation while “relocate” has option to relocate all DIV elements from one TD to another TD with or without animation. If “target” property is not defined then current location will be used. Here is properties definition of input parameter:

  • {String} id – id of element to animate – DIV element or row handler (div class=”redips-drag redips-row”)
  • {String} obj – reference of element to animate – DIV element or row handler (if “id” parameter exists, “obj” parameter will be ignored)
  • {String} mode – animation mode (if mode=”row” then source and target properties should be defined)
  • {Boolean} clone – if set to true then DIV element will be cloned instead of moving (used only in “cell” mode and default is false)
  • {Boolean} overwrite – if set to true then elements in target cell will be overwritten (used only in “cell” mode and default is false)
  • {Array} source – source position (table index and row index)
  • {Array} target – target position (table, row and cell index (optional for “row” mode)
  • {Function} callback – callback function executed after animation is finished

Method returns array containing reference of two object. In “cell” mode returned objects are:

  • Array[0] – dragged element
  • Array[1] – dragged element

In “row” mode returned objects are:

  • Array[0] – tableMini
  • Array[1] – source row

If “clone” parameter is set to true then event.cloned() event handler will be invoked with input parameter of cloned element.

// move element with id="a1" to the current location and after
// animation is finished display alert "Finished"
rd.moveObject({
    id: 'a1',
    callback: function () {
        alert('Finished');
    }
});

// move DIV element with reference "mydiv" to the TD with reference td
rd.moveObject({
    obj: mydiv,
    target: td
});

// move DIV element with reference "mydiv" to the first table, second row and third cell
rd.moveObject({
    obj: mydiv,
    target: [0, 1, 2]
});

// move element with id="a2" to the first table, second row and third cell
rd.moveObject({
    id: 'a2',
    target: [0, 1, 2]
});

// clone DIV element with reference "mydiv", move to the first table, second row,
// third cell and overwrite all content in target cell
rd.moveObject({
    obj: mydiv,
    clone: true,
    overwrite: true,
    target: [0, 1, 2]
});

// move first row and after animation is finished call "enable_button" function
// "moveObject" returns Array with references of tableMini and source row
row = rd.moveObject({
          mode: 'row',            // animation mode - row
          source: [0, 0],         // source position (table index and row index)
          target: [0, 6],         // target position
          callback: enable_button // function to call after animation is over
       });
Parameters:
{Object} ip
Object with properties: id, mode, source, target and callback.
Returns:
{Array|Boolean} Returns reference of two elements in array or false. In “cell” mode both elements are dragged element, while in “row” mode first element is tableMini and second element is source row or it could be false if “emptyRow” try to move.
See:
relocate

relocate(from, to, mode)
Method relocates DIV elements from source table cell to the target table cell (with optional animation). If animation is enabled, then target table will be disabled until animated element reaches destination cell. In animation mode, event.relocated() will be called after animation is finished.
Parameters:
{HTMLElement} from
Source table cell.
{HTMLElement} to
Target table cell.
{String} mode Optional
Relocation mode “instant” or “animation”. Default is “instant”.
See:
event.relocateBefore
event.relocateAfter
event.relocateEnd

rowEmpty(tblId, rowIdx, color)
Method marks selected row as empty. Could be needed for displaying initially empty table. Input parameters are table id and row index.
// set reference to the REDIPS.drag library
rd = REDIPS.drag;
// mark first row as empty in table with id="tbl1"
rd.rowEmpty('tbl1', 0);
Parameters:
{String} tblId
Table id.
{Integer} rowIdx
Row index (starts from 0).
{String} color Optional
Color of empty row (default is “White” or defined with REDIPS.drag.rowEmptyColor parameter).
See:
style.rowEmptyColor

rowOpacity(el, opacity, color)
Method sets opacity to table row or deletes row content. Input parameter “el” is reference to the table row or reference to the cloned mini table (when row is moved).
// set reference to the REDIPS.drag library
rd = REDIPS.drag;

// make row semi-transparent
rd.rowOpacity(rowObj, 50);

// set row as empty and white (content in table cells will be deleted)
rd.rowOpacity(rowObj, 'empty', 'White');
Parameters:
{HTMLElement|String} el
Id of row handler (div class=”redips-drag redips-row”) or reference to element (source row or mini table).
{Integer|String} opacity
Opacity level (from 0 to 100) or “empty” (then content of table cells in row will be deleted – in that case first parameter should be TR).
{String} color Optional
Background color.

{String} saveContent(tbl, type)
Method scans table content and prepares query string or JSON format for submitting to the server script. Input parameters are id / table reference and optional output format.
Query string:
'p[]='+id+'_'+r+'_'+c+'_'+n+'_'+t+'&p[]='+id+'_'+r+'_'+c+'_'+n+'_'+t ...

JSON:
[["id",r,c,"n","t"],["id",r,c,"n","t"], ...]

id - element id
r  - row index
c  - cell index
n  - class names
t  - DIV innerText

Query string example:
p[]=d1_1_0_blue_Name1&p[]=d2_1_1_green_Name2&p[]=d3_5_2_green_Name3&p[]=d4_5_3_red_Name4

JSON output example:
[["d1",1,0,"blue","Name1"],["d2",1,1,"green","Name2"],["d3",5,2,"green","Name3"],["d4",5,3,"red","Name4"]]
Parameters:
{String|HTMLElement} tbl
Id or reference of table that will be scanned.
{String} type Optional
Type defines output format. If set to “json” then output will be JSON format otherwise output will be query string.
Returns:
{String} Returns table content as query string or in JSON format.
See:
saveParamName
loadContent

shiftCells(td1, td2)
Method shifts table content horizontally or vertically. REDIPS.drag.shift.mode defines the way of how content will be shifted. Useful for sorting table content in any direction.
// define first and last table cell
var firstCell = document.getElementById('firstCellOnTable'),
    lastCell = document.getElementById('lastCellOnTable');
// enable animation
REDIPS.drag.shift.animation = true;
// shift content
REDIPS.drag.shiftCells(lastCell, firstCell);
Parameters:
{HTMLElement} td1
Source table cell.
{HTMLElement} td2
Target table cell.
See:
shift.mode
Event Detail

error.ajax(xhr, obj)
This method enables handling HTTP AJAX errors. Error handler will be called when status of AJAX request is not 200 (OK) and the reason might be 404 Not Found, 403 Forbidden, 503 Service Unavailable, 500 Internal Server Error etc. Input parameter is XMLHttpRequest object (xhr) where are all details about AJAX request (status, statusText, …) and optional obj object passed from ajaxCall() method.
Parameters:
{Object} xhr Optional
Input parameter is XMLHttpRequest object (xhr)
{Object} obj Optional
Object with optional AJAX parameters (like POST method and data) or used for sending additional parameters to the callback function.
See:
ajaxCall

error.loadContent(obj)
Error handler invoked if is not possible to place DIV element to the target table during content loading. The reason could be non-existent coordinates of TR, TD or non-existent TABLE. Method is called with optional object as input parameter containing properties that describes error context. Object properites {type, message, content, rowIndex, cellIndex} contain the following information:

  • In case of AJAX error – {0, ‘AJAX error description’, null, null, null}
  • If input JSON string is not parsable – {0, ‘JSON parse error’, null, null, null}
  • If target table does not exist – {0, ‘Target table does not exist’, null, null, null}
  • In case of nonexisting TR – {1, ‘Target TR does not exist’, ‘DIV_content’, row_index, cell_index}
  • In case of nonexisting TD – {2, ‘Target TD does not exist’, ‘DIV_content’, row_index, cell_index}

Error type 0 (AJAX error, JSON parse error or table doesn’t exist) is non-recoverable error (after calling loadError() event handler, loadContent() method will stop). If boolen “false” is returned from this event handler, further processing will be stopped. It refers to error type 1 and type 2.

Parameters:
{Object} obj Optional
Object properties are: type (message type), message text (error description), content (DIV content), rowIndex and cellIndex
See:
loadContent

event.changed(currentCell)
Event handler invoked on every change of current (highlighted) table cell.
// set REDIPS.drag reference
var rd = REDIPS.drag;
// define event.changed handler
rd.event.changed = function () {
  // get current position (method returns positions as array)
  var pos = rd.getPosition();
  // display current row and current cell
  console.log('Changed: ' + pos[1] + ' ' + pos[2]);
};
Parameters:
{HTMLElement} currentCell Optional
Reference to the current (highlighted) table cell.
See:
getPosition

event.clicked(currentCell)
Event handler invoked if a mouse button is pressed down while the mouse pointer is over DIV element.
Parameters:
{HTMLElement} currentCell Optional
Reference to the table cell of clicked element.

event.cloned(clonedElement)
Event handler invoked after DIV element is cloned – interactively by moving DIV element or by calling moveObject() in “cell” mode with “clone” option. If event handler is called from moveObject() then reference of cloned element is sent as input parameter. Otherwise, reference of cloned DIV element is set to REDIPS.drag.obj while reference of original element is set to REDIPS.drag.objOld public property.
Parameters:
{HTMLElement} clonedElement Optional
Cloned element reference.
See:
moveObject

event.clonedDropped(targetCell)
Event handler invoked after cloned DIV element is dropped.
Parameters:
{HTMLElement} targetCell Optional
Reference to the target table cell.

event.clonedEnd1()
Event handler invoked if last element is cloned (type 1). Element has defined “climit1_X” class name where X defines number of elements to clone. Last element can be dragged.

event.clonedEnd2()
Event handler invoked if last element is cloned (type 2). Element has defined “climit2_X” class name where X defines number of elements to clone. Last element can’t be dragged and stays static.

event.dblClicked()
Event handler invoked if a mouse button is clicked twice while the mouse pointer is over DIV element.

event.deleted(cloned)
Event handler invoked if element is deleted (dropped to the “trash” table cell).
Parameters:
{Boolean} cloned Optional
True if cloned element is directly moved to the trash (in one move). If cloned element is dropped to the table and then moved to the trash then “cloned” parameter will be set to false.

event.dropped(targetCell)
Event handler invoked if element is dropped to the table cell.
Parameters:
{HTMLElement} targetCell Optional
Target cell reference.

event.droppedBefore(targetCell)
Event handler invoked if mouse button is released but before element is dropped to the table cell. If boolen “false” is returned from event handler then element drop will be canceled. Dragged element will be returned to the start position while cloned element will be deleted.
Parameters:
{HTMLElement} targetCell Optional
Target cell reference.

event.finish()
Event handler invoked after any DIV element action. For example, if drop option is set to “multiple” (default drop mode) and DIV element is dropped to the table cell then the following order of event handlers will be performed:

  1. event.droppedBefore
  2. event.dropped (only if event.droppedBefore doesn’t return false)
  3. event.finish
    1. So, event.finish will be called after deleting DIV element, cloning, switching and so on. Its main purpose is to execute some common code (like “cleaning”) after any DIV element action.

event.moved(cloned)
Event handler invoked if element is moved from home position.
Parameters:
{Boolean} cloned Optional
True if moved element is actually a cloned DIV. Needed for cases when obj or objOld should be used.

event.notCloned()
Event handler invoked if cloned element is dropped on start position or cloned element is dropped outside current table with “clone.drop” property set to false. This event handler could be also invoked if “clone” type element is placed inside forbidden table cell.
See:
clone.drop

event.notMoved()
Event handler invoked if mouse button is pressed down and released while the mouse pointer is over DIV element (element was not actually moved). Default threshold value is 7px, so if DIV element is moved within threshold value (background color of cell will not change) the same event handler will be called.

event.relocateAfter(div, td)
Event handler invoked after DIV element is relocated. For example, in shift drop mode, this event handler will be called after each DIV element has been moved.
Parameters:
{HTMLElement} div
Reference of DIV element that is relocated.
{HTMLElement} td
Reference of TD where DIV element is relocated.
See:
relocate
event.relocateBefore
event.relocateEnd

event.relocateBefore(div, td)
Event handler invoked before DIV element will be relocated. For example, in shift drop mode, this event handler will be called before each DIV element move.
Parameters:
{HTMLElement} div
Reference of DIV element that will be relocated.
{HTMLElement} td
Reference of TD where DIV element will be relocated.
See:
relocate
event.relocateAfter
event.relocateEnd

event.relocateEnd()
Event handler invoked after all DIV elements are relocated and before table is enabled (DIV elements enabled for dragging). This event can be triggered after single call of relocate() method or after all DIV elements are shifted in “shift” mode. It is called only if animation is turned on.
See:
relocate
event.relocateBefore
event.relocateAfter

event.rowChanged(currentCell)
Event handler invoked on every change of current (highlighted) table row.
Parameters:
{HTMLElement} currentCell Optional
Reference to the current (highlighted) table cell.

event.rowClicked(currentCell)
Event handler invoked if a mouse button is pressed down while the mouse pointer is over row handler (div class=”redips-drag redips-row”).
Parameters:
{HTMLElement} currentCell Optional
Reference to the table cell of clicked element.

event.rowCloned()
Event handler invoked if table row is cloned.

event.rowDeleted()
Event handler invoked if row is deleted (dropped to the “trash” table cell).

event.rowDropped(targetRow, sourceTable, sourceRowIndex)
Event handler invoked after dropping row to the table.
Parameters:
{HTMLElement} targetRow Optional
Reference to the target row (dropped row).
{HTMLElement} sourceTable Optional
Source table reference. If row is dropped to the same table then this reference and targetRow will be in correlation (actually “source table” contains targetRow).
{Integer} sourceRowIndex Optional
Source row index.

event.rowDroppedBefore(sourceTable, sourceRowIndex)
Event handler invoked in the moment when mouse button is released but before row is dropped to the table.
Parameters:
{HTMLElement} sourceTable Optional
Source table reference.
{Integer} sourceRowIndex Optional
Source row index.
If boolen “false” is returned from event handler then row drop will be canceled.

event.rowDroppedSource(targetCell)
Event handler invoked if row is moved around and dropped to the home position.
Parameters:
{HTMLElement} targetCell Optional
Reference to the target table cell.

event.rowMoved()
Event handler invoked if row is moved from home position.

event.rowNotCloned()
Event handler invoked if cloned row is dropped to the source row.

event.rowNotMoved()
Event handler invoked if a mouse button is pressed down and released while the mouse pointer is over row handler (row was not actually moved).

event.rowUndeleted()
Event handler invoked if row is undeleted. After row is dropped to the “trash” table cell and trash.questionRow property is not null then popup with set question will appear. Clicking on “Cancel” will undelete row and call this event handler.
See:
trash

event.shiftOverflow(td)
Event handler invoked in a moment when overflow happen in shift mode.
Parameters:
{HTMLElement} td
Reference of TD where overflow happen.
See:
dropMode

event.switched(targetCell)
Event handler invoked if DIV elements are switched (dropMode is set to “switch”).
Parameters:
{HTMLElement} targetCell Optional
Reference to the target table cell.
See:
dropMode

event.undeleted()
Event handler invoked if element is undeleted. After element is dropped to the “trash” table cell and trash.question property is not null then popup with set question will appear. Clicking on “Cancel” will undelete element and call this event handler.
See:
trash

181 thoughts on “REDIPS.drag documentation”

  1. @Corax – Yes, it’s possible to have a table with DIV elements without option to accept any other DIV element. Table cells should be marked with class=”mark” like in example09 Single and shift mode. All class names with special meanings are described in Appendix A documentation.

    Hope my comment gives answer to your question. If not, don’t hesitate to ask again.

  2. Hi,
    Great job thanks.
    Is it possible to manipulate divs that cover more than one cell (height).
    I like to implement the positioning of equipments inside a rack, the equipment can be on more than one row.
    Thanks.

  3. @Toufik – DIV element can be placed only to one table cell. It can’t be spread across several cells. But, table cells can be merged before dropping DIV element. Please see REDIPS.table tiny lib which has abilities to merge/split table cells and add/remove table rows and columns. It’s possible to use and combine both, REDIPS.drag and REDIPS.table libraries on the same page.

  4. @dbunic – Thx, that solve my problem. I thought if a cell marked with class=’mark’ than it can’t be dragged, but I was wrong.
    THX again.

  5. Hi Darko,
    Can I specify the number of containers that can be dropped to a cell with REDIPS.drag.drop_option = ‘multiple’;

  6. @Dave – If you ask about possibility to control a number of dropped DIV elements to the table cell then yes, it’s possible. The code should be written inside myhandler_dropped_before event handler. Handler contains reference of the target table cell as optional input parameter. So, it’s only needed to write a JS code to count current number of DIV elements. If number of DIV elements is not allowed, event handler should return boolean false and dropped DIV element will be returned to its start position.

  7. Hello! I’ve been trying to get your:

    rd.delete_object(rd.obj);
    

    to work while nested inside a myhandler_row_dropped or myhandler_dropped by the dropped element is not being removed.

    Basically, I’m going to run a check to see if the number of row in a table exceeds a certain number and then upon more rows being dropped, it deletes them. Normally, I’d just lock the table but I want to be able to drag the rows to the trash OR rearrange them.

    Is there another way to do this or am I just doing something wrong? Will send code if needed, it’s a modified version of your Example 20.

    Thanks,
    Philip

  8. @Philip – Here is JS code to limit number of rows in the second table (modification of example20):

    // define cloned flag
    var cloned;
    // reset cloned flag (set to false) on every row click
    rd.myhandler_row_clicked = function () {
        cloned = false;
    };
    // set cloned flag to true (in case of cloning row)
    rd.myhandler_row_cloned = function () {
        cloned = true;
    };
    // event handler called before row is dropped to the table
    rd.myhandler_row_dropped_before = function () {
        // set table reference of source and target table
        var tbl1 = rd.find_parent('TABLE', rd.obj_old),     // source table
            tbl2 = rd.find_parent('TABLE', rd.target_cell); // target table
        // allow dragging row within the same table
        if (tbl1 === tbl2 && !cloned) {
            return;
        }
        // limit number of rows in second table to 3
        if (tbl2.id === 'tbl2' && tbl2.rows.length > 3) {
            // make source row completely visible (no opacity) and return false
            rd.row_opacity(rd.obj_old, 100);
            return false;
        }
    };
    

    Basically, if “false” is returned from myhandler_row_dropped_before event handler then dragged or cloned row will be deleted. I also added simple JS logic to determine current number of rows in second table (it’s a table with id=”tbl2″).

  9. @dbunic: Thank you very much! It works beautifully.. I didn’t think to use the myhandler_row_dropped_before.

  10. Hi there,

    Is there a way to make the draggable cells only go into certain columns? So like, Item 1 can only go into column 3, Item 2 can only going into column 1 etc…

    Thanks!

  11. @Robbie L – This rules can be written inside myhandler_dropped_before() event handler by using get_position() method. Here is code snippet to return DIV element in case of dropping element with id=”green” to the third column:

    rd.myhandler_dropped_before = function () {
        // define DIV id and position
        var id = rd.obj.id,
            pos = rd.get_position();
        // if id=green and DIV is dropped to the third column
        // then return DIV to the source position
        if (id === 'green' && pos[2] === 2) {
            return false;
        }
    };
    
  12. Thanks for your help in my previous help. I found another solution just using move_object function, what i did was to loop through the entire first column and check if the row is empty and if it is empty I will moved the element to that position using move_object. :D

  13. Hi Sir,

    Thank you very much and I very expressed the example 21 (Shift table content). However, I need to call drop function while dragging. It likes as iPhone screen. I want that ” When I clicked on cell A and drag to cell B (still being press left mouse button) then remain cells will re-arrange without release the left mouse button.

    Thanks.
    Chau.

  14. @Chau – If you want to sort elements in table while dragging current DIV element, please see example14: Sort elements in long table. Before start to drag, click on radio button “Switching”.

    http://www.redips.net/my/preview/REDIPS_drag/example14/

    This drop option is called switching. REDIPS.drag has several drop options defined with drop_option public parameter. Hope this example will be helpful to you.

  15. Hi,

    How can I get the DIV id of the target_cell ?

    What I need to get to is the innerHTML and add it to the innerHTML of the cell being dropped onto it.

    Is this possible ?

    Thanks,
    David.

  16. Here is how to define Id of target_cell inside myhandler_dropped event handler:

    // redips initialization
    redips_init = function () {
        // set REDIPS.drag reference
        var rd = REDIPS.drag;
        // define event handler
        rd.myhandler_dropped = function () {
            // define id of target cell
            var id = rd.target_cell.id;
            ...
            ...
        };
    };
    

    … and how to delete dropped DIV element and append inner HTML to the target cell:

    rd.myhandler_dropped = function () {
        // delete dropped DIV element
        rd.obj.parentNode.removeChild(rd.obj);
        // append innerHTML of dropped DIV element to the target cell
        rd.target_cell.innerHTML += rd.obj.innerHTML + '<br>';
    };
    

Leave a Comment