summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorNathaniel Catchpole2016-02-29 12:06:15 (GMT)
committerNathaniel Catchpole2016-02-29 12:06:15 (GMT)
commitcce99d5ac534acd174a2f157e59b39afe31c7bcf (patch)
tree69c267a8ff519759c634aba14777f5c88d0c47a5
parentbf28e3d006fda29b0a67f2e6bb7ed1f218ab43be (diff)
Issue #2559695 by leolando.tan, bhavikshah9, falufalump, nod_, eiriksm: JSDoc tabledrag.js
-rw-r--r--core/misc/tabledrag.js65
1 files changed, 54 insertions, 11 deletions
diff --git a/core/misc/tabledrag.js b/core/misc/tabledrag.js
index 6a27d8f..0b12f11 100644
--- a/core/misc/tabledrag.js
+++ b/core/misc/tabledrag.js
@@ -167,9 +167,10 @@
this.windowHeight = 0;
/**
- * Check this table's settings to see if there are parent relationships in
- * this table. For efficiency, large sections of code can be skipped if we
- * don't need to track horizontal movement and indentations.
+ * Check this table's settings for parent relationships.
+ *
+ * For efficiency, large sections of code can be skipped if we don't need to
+ * track horizontal movement and indentations.
*
* @type {bool}
*/
@@ -299,8 +300,10 @@
* In order to adjust the colspan instead of hiding them altogether.
*
* @param {number} columnIndex
+ * The column index to add colspan class to.
*
* @return {function}
+ * Function to add colspan class.
*/
Drupal.tableDrag.prototype.addColspanClass = function (columnIndex) {
return function () {
@@ -409,9 +412,12 @@
* Find the target used within a particular row and group.
*
* @param {string} group
+ * Group selector.
* @param {HTMLElement} row
+ * The row HTML element.
*
* @return {object}
+ * The table row settings.
*/
Drupal.tableDrag.prototype.rowSettings = function (group, row) {
var field = $(row).find('.' + group);
@@ -437,11 +443,12 @@
* Take an item and add event handlers to make it become draggable.
*
* @param {HTMLElement} item
+ * The item to add event handlers to.
*/
Drupal.tableDrag.prototype.makeDraggable = function (item) {
var self = this;
var $item = $(item);
- // Add a class to the title link
+ // Add a class to the title link.
$item.find('td:first-of-type').find('a').addClass('menu-item__link');
// Create the handle.
var handle = $('<a href="#" class="tabledrag-handle"><div class="handle">&nbsp;</div></a>').attr('title', Drupal.t('Drag to re-order'));
@@ -676,9 +683,12 @@
* Pointer movement handler, bound to document.
*
* @param {jQuery.Event} event
+ * The pointer event.
* @param {Drupal.tableDrag} self
+ * The tableDrag instance.
*
* @return {bool|undefined}
+ * Undefined if no dragObject is defined, false otherwise.
*/
Drupal.tableDrag.prototype.dragRow = function (event, self) {
if (self.dragObject) {
@@ -737,7 +747,9 @@
* Pointerup behavior.
*
* @param {jQuery.Event} event
+ * The pointer event.
* @param {Drupal.tableDrag} self
+ * The tableDrag instance.
*/
Drupal.tableDrag.prototype.dropRow = function (event, self) {
var droppedRow;
@@ -798,8 +810,10 @@
* Get the coordinates from the event (allowing for browser differences).
*
* @param {jQuery.Event} event
+ * The pointer event.
*
- * @return {{x: number, y: number}}
+ * @return {object}
+ * An object with `x` and `y` keys indicating the position.
*/
Drupal.tableDrag.prototype.pointerCoords = function (event) {
if (event.pageX || event.pageY) {
@@ -818,9 +832,12 @@
* element. To do this we need the element's position and the target position.
*
* @param {HTMLElement} target
+ * The target HTML element.
* @param {jQuery.Event} event
+ * The pointer event.
*
- * @return {{x: number, y: number}}
+ * @return {object}
+ * An object with `x` and `y` keys indicating the position.
*/
Drupal.tableDrag.prototype.getPointerOffset = function (target, event) {
var docPos = $(target).offset();
@@ -839,6 +856,7 @@
* The y coordinate of the mouse on the page (not the screen).
*
* @return {*}
+ * The drop target row, if found.
*/
Drupal.tableDrag.prototype.findDropTargetRow = function (x, y) {
var rows = $(this.table.tBodies[0].rows).not(':hidden');
@@ -1055,8 +1073,11 @@
* may have had.
*
* @param {HTMLElement} sourceRow
+ * The element for the source row.
* @param {HTMLElement} targetRow
+ * The element for the target row.
* @param {string} group
+ * The group selector.
*/
Drupal.tableDrag.prototype.copyDragClasses = function (sourceRow, targetRow, group) {
var sourceElement = $(sourceRow).find('.' + group);
@@ -1067,8 +1088,13 @@
};
/**
+ * Check the suggested scroll of the table.
+ *
* @param {number} cursorY
+ * The Y position of the cursor.
+ *
* @return {number}
+ * The suggested scroll.
*/
Drupal.tableDrag.prototype.checkScroll = function (cursorY) {
var de = document.documentElement;
@@ -1099,7 +1125,10 @@
};
/**
+ * Set the scroll for the table.
+ *
* @param {number} scrollAmount
+ * The amount of scroll to apply to the window.
*/
Drupal.tableDrag.prototype.setScroll = function (scrollAmount) {
var self = this;
@@ -1131,7 +1160,8 @@
/**
* Stub function. Allows a custom handler when a row begins dragging.
*
- * @return {?bool}
+ * @return {null}
+ * Returns null when the stub function is used.
*/
Drupal.tableDrag.prototype.onDrag = function () {
return null;
@@ -1140,7 +1170,8 @@
/**
* Stub function. Allows a custom handler when a row is dropped.
*
- * @return {?bool}
+ * @return {null}
+ * Returns null when the stub function is used.
*/
Drupal.tableDrag.prototype.onDrop = function () {
return null;
@@ -1194,6 +1225,7 @@
* relationships.
*
* @return {Array}
+ * An array of children of the row.
*/
Drupal.tableDrag.prototype.row.prototype.findChildren = function (addClasses) {
var parentIndentation = this.indents;
@@ -1241,6 +1273,7 @@
* DOM object for the row being considered for swapping.
*
* @return {bool}
+ * Whether the swap is a valid swap or not.
*/
Drupal.tableDrag.prototype.row.prototype.isValidSwap = function (row) {
var $row = $(row);
@@ -1303,7 +1336,9 @@
* DOM object for the row after the tested position
* (or null for last position in the table).
*
- * @return {{min: number, max: number}}
+ * @return {object}
+ * An object with the keys `min` and `max` to indicate the valid indent
+ * interval.
*/
Drupal.tableDrag.prototype.row.prototype.validIndentInterval = function (prevRow, nextRow) {
var $prevRow = $(prevRow);
@@ -1343,6 +1378,7 @@
* indentation level for the row.
*
* @return {number}
+ * The number of indentations applied.
*/
Drupal.tableDrag.prototype.row.prototype.indent = function (indentDiff) {
var $group = $(this.group);
@@ -1390,6 +1426,7 @@
* The field settings we're using to identify what constitutes a sibling.
*
* @return {Array}
+ * An array of siblings.
*/
Drupal.tableDrag.prototype.row.prototype.findSiblings = function (rowSettings) {
var siblings = [];
@@ -1459,7 +1496,8 @@
/**
* Stub function. Allows a custom handler when a row is indented.
*
- * @return {?bool}
+ * @return {null}
+ * Returns null when the stub function is used.
*/
Drupal.tableDrag.prototype.row.prototype.onIndent = function () {
return null;
@@ -1469,8 +1507,10 @@
* Stub function. Allows a custom handler when a row is swapped.
*
* @param {HTMLElement} swappedRow
+ * The element for the swapped row.
*
- * @return {?bool}
+ * @return {null}
+ * Returns null when the stub function is used.
*/
Drupal.tableDrag.prototype.row.prototype.onSwap = function (swappedRow) {
return null;
@@ -1480,6 +1520,7 @@
/**
* @return {string}
+ * Markup for the marker.
*/
tableDragChangedMarker: function () {
return '<abbr class="warning tabledrag-changed" title="' + Drupal.t('Changed') + '">*</abbr>';
@@ -1487,6 +1528,7 @@
/**
* @return {string}
+ * Markup for the indentation.
*/
tableDragIndentation: function () {
return '<div class="js-indentation indentation">&nbsp;</div>';
@@ -1494,6 +1536,7 @@
/**
* @return {string}
+ * Markup for the warning.
*/
tableDragChangedWarning: function () {
return '<div class="tabledrag-changed-warning messages messages--warning" role="alert">' + Drupal.theme('tableDragChangedMarker') + ' ' + Drupal.t('You have unsaved changes.') + '</div>';