2 * ©2008-2014 SpryMedia Ltd - datatables.net/license
7 * @description Add Excel like click and drag auto-fill options to DataTables
9 * @file dataTables.autoFill.js
10 * @author SpryMedia Ltd (www.sprymedia.co.uk)
11 * @contact www.sprymedia.co.uk/contact
12 * @copyright Copyright 2010-2014 SpryMedia Ltd.
14 * This source file is free software, available under the following license:
15 * MIT license - http://datatables.net/license/mit
17 * This source file is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
19 * or FITNESS FOR A PARTICULAR PURPOSE. See the license files for details.
21 * For details please refer to: http://www.datatables.net
24 (function( window, document, undefined ) {
26 var factory = function( $, DataTable ) {
30 * AutoFill provides Excel like auto-fill features for a DataTable
34 * @param {object} oTD DataTables settings object
35 * @param {object} oConfig Configuration object for AutoFill
37 var AutoFill = function( oDT, oConfig )
39 /* Sanity check that we are a new instance */
40 if ( ! (this instanceof AutoFill) ) {
41 throw( "Warning: AutoFill must be initialised with the keyword 'new'" );
44 if ( ! $.fn.dataTableExt.fnVersionCheck('1.7.0') ) {
45 throw( "Warning: AutoFill requires DataTables 1.7 or greater");
49 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
50 * Public class variables
51 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
56 * @namespace Settings object which contains customisable information for AutoFill instance
60 * @namespace Cached information about the little dragging icon (the filler)
68 * @namespace Cached information about the border display
75 * @namespace Store for live information for the current drag
86 * @namespace Data cache for information that we need for scrolling the screen when we near
97 * @namespace Data cache for the position of the DataTables scrolling element (when scrolling
106 * @namespace Information stored for each column. An array of objects
113 * @namespace Common and useful DOM elements for the class instance
120 "borderBottom": null,
122 "currentTarget": null
127 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
128 * Public class methods
129 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
132 * Retreieve the settings object from an instance
134 * @returns {object} AutoFill settings object
136 this.fnSettings = function () {
141 /* Constructor logic */
142 this._fnInit( oDT, oConfig );
148 AutoFill.prototype = {
149 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
150 * Private methods (they are of course public in JS, but recommended as private)
151 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
156 * @param {object} dt DataTables settings object
157 * @param {object} config Configuration object for AutoFill
160 "_fnInit": function ( dt, config )
166 // Use DataTables API to get the settings allowing selectors, instances
167 // etc to be used, or for backwards compatibility get from the old
169 this.s.dt = DataTable.Api ?
170 new DataTable.Api( dt ).settings()[0] :
172 this.s.init = config || {};
173 this.dom.table = this.s.dt.nTable;
175 $.extend( true, this.c, AutoFill.defaults, config );
177 /* Add and configure the columns */
180 /* Auto Fill click and drag icon */
181 var filler = $('<div/>', {
182 'class': 'AutoFill_filler'
185 this.dom.filler = filler[0];
187 // Get the height / width of the click element
188 this.s.filler.height = filler.height();
189 this.s.filler.width = filler.width();
190 filler[0].style.display = "none";
192 /* Border display - one div for each side. We can't just use a single
193 * one with a border, as we want the events to effectively pass through
194 * the transparent bit of the box
197 var appender = document.body;
198 if ( that.s.dt.oScroll.sY !== "" ) {
199 that.s.dt.nTable.parentNode.style.position = "relative";
200 appender = that.s.dt.nTable.parentNode;
203 border = $('<div/>', {
204 "class": "AutoFill_border"
206 this.dom.borderTop = border.clone().appendTo( appender )[0];
207 this.dom.borderRight = border.clone().appendTo( appender )[0];
208 this.dom.borderBottom = border.clone().appendTo( appender )[0];
209 this.dom.borderLeft = border.clone().appendTo( appender )[0];
212 filler.on( 'mousedown.DTAF', function (e) {
213 this.onselectstart = function() { return false; };
214 that._fnFillerDragStart.call( that, e );
218 $('tbody', this.dom.table).on(
219 'mouseover.DTAF mouseout.DTAF',
222 that._fnFillerDisplay.call( that, e );
226 $(this.dom.table).on( 'destroy.dt.DTAF', function () {
227 filler.off( 'mousedown.DTAF' ).remove();
228 $('tbody', this.dom.table).off( 'mouseover.DTAF mouseout.DTAF' );
233 _initColumns: function ( )
238 var config = this.s.init;
240 for ( i=0, ien=dt.aoColumns.length ; i<ien ; i++ ) {
241 this.s.columns[i] = $.extend( true, {}, AutoFill.defaults.column );
244 dt.oApi._fnApplyColumnDefs(
246 config.aoColumnDefs || config.columnDefs,
247 config.aoColumns || config.columns,
248 function (colIdx, def) {
249 that._fnColumnOptions( colIdx, def );
253 // For columns which don't have read, write, step functions defined,
254 // use the default ones
255 for ( i=0, ien=dt.aoColumns.length ; i<ien ; i++ ) {
256 var column = this.s.columns[i];
258 if ( ! column.read ) {
259 column.read = this._fnReadCell;
261 if ( ! column.write ) {
262 column.read = this._fnWriteCell;
264 if ( ! column.step ) {
265 column.read = this._fnStep;
271 "_fnColumnOptions": function ( i, opts )
273 var column = this.s.columns[ i ];
274 var set = function ( outProp, inProp ) {
275 if ( opts[ inProp[0] ] !== undefined ) {
276 column[ outProp ] = opts[ inProp[0] ];
278 if ( opts[ inProp[1] ] !== undefined ) {
279 column[ outProp ] = opts[ inProp[1] ];
283 // Compatibility with the old Hungarian style of notation
284 set( 'enable', ['bEnable', 'enable'] );
285 set( 'read', ['fnRead', 'read'] );
286 set( 'write', ['fnWrite', 'write'] );
287 set( 'step', ['fnStep', 'step'] );
288 set( 'increment', ['bIncrement', 'increment'] );
293 * Find out the coordinates of a given TD cell in a table
294 * @method _fnTargetCoords
296 * @returns {Object} x and y properties, for the position of the cell in the tables DOM
298 "_fnTargetCoords": function ( nTd )
300 var nTr = $(nTd).parents('tr')[0];
301 var position = this.s.dt.oInstance.fnGetPosition( nTd );
304 "x": $('td', nTr).index(nTd),
305 "y": $('tr', nTr.parentNode).index(nTr),
307 "column": position[2]
313 * Display the border around one or more cells (from start to end)
314 * @method _fnUpdateBorder
315 * @param {Node} nStart Starting cell
316 * @param {Node} nEnd Ending cell
319 "_fnUpdateBorder": function ( nStart, nEnd )
322 border = this.s.border.width,
323 offsetStart = $(nStart).offset(),
324 offsetEnd = $(nEnd).offset(),
325 x1 = offsetStart.left - border,
326 x2 = offsetEnd.left + $(nEnd).outerWidth(),
327 y1 = offsetStart.top - border,
328 y2 = offsetEnd.top + $(nEnd).outerHeight(),
329 width = offsetEnd.left + $(nEnd).outerWidth() - offsetStart.left + (2*border),
330 height = offsetEnd.top + $(nEnd).outerHeight() - offsetStart.top + (2*border),
333 // Recalculate start and end (when dragging "backwards")
334 if( offsetStart.left > offsetEnd.left) {
335 x1 = offsetEnd.left - border;
336 x2 = offsetStart.left + $(nStart).outerWidth();
337 width = offsetStart.left + $(nStart).outerWidth() - offsetEnd.left + (2*border);
340 if ( this.s.dt.oScroll.sY !== "" )
342 /* The border elements are inside the DT scroller - so position relative to that */
344 offsetScroll = $(this.s.dt.nTable.parentNode).offset(),
345 scrollTop = $(this.s.dt.nTable.parentNode).scrollTop(),
346 scrollLeft = $(this.s.dt.nTable.parentNode).scrollLeft();
348 x1 -= offsetScroll.left - scrollLeft;
349 x2 -= offsetScroll.left - scrollLeft;
350 y1 -= offsetScroll.top - scrollTop;
351 y2 -= offsetScroll.top - scrollTop;
355 oStyle = this.dom.borderTop.style;
356 oStyle.top = y1+"px";
357 oStyle.left = x1+"px";
358 oStyle.height = this.s.border.width+"px";
359 oStyle.width = width+"px";
362 oStyle = this.dom.borderBottom.style;
363 oStyle.top = y2+"px";
364 oStyle.left = x1+"px";
365 oStyle.height = this.s.border.width+"px";
366 oStyle.width = width+"px";
369 oStyle = this.dom.borderLeft.style;
370 oStyle.top = y1+"px";
371 oStyle.left = x1+"px";
372 oStyle.height = height+"px";
373 oStyle.width = this.s.border.width+"px";
376 oStyle = this.dom.borderRight.style;
377 oStyle.top = y1+"px";
378 oStyle.left = x2+"px";
379 oStyle.height = height+"px";
380 oStyle.width = this.s.border.width+"px";
385 * Mouse down event handler for starting a drag
386 * @method _fnFillerDragStart
387 * @param {Object} e Event object
390 "_fnFillerDragStart": function (e)
393 var startingTd = this.dom.currentTarget;
395 this.s.drag.dragging = true;
397 that.dom.borderTop.style.display = "block";
398 that.dom.borderRight.style.display = "block";
399 that.dom.borderBottom.style.display = "block";
400 that.dom.borderLeft.style.display = "block";
402 var coords = this._fnTargetCoords( startingTd );
403 this.s.drag.startX = coords.x;
404 this.s.drag.startY = coords.y;
406 this.s.drag.startTd = startingTd;
407 this.s.drag.endTd = startingTd;
409 this._fnUpdateBorder( startingTd, startingTd );
411 $(document).bind('mousemove.AutoFill', function (e) {
412 that._fnFillerDragMove.call( that, e );
415 $(document).bind('mouseup.AutoFill', function (e) {
416 that._fnFillerFinish.call( that, e );
419 /* Scrolling information cache */
420 this.s.screen.y = e.pageY;
421 this.s.screen.height = $(window).height();
422 this.s.screen.scrollTop = $(document).scrollTop();
424 if ( this.s.dt.oScroll.sY !== "" )
426 this.s.scroller.top = $(this.s.dt.nTable.parentNode).offset().top;
427 this.s.scroller.bottom = this.s.scroller.top + $(this.s.dt.nTable.parentNode).height();
430 /* Scrolling handler - we set an interval (which is cancelled on mouse up) which will fire
431 * regularly and see if we need to do any scrolling
433 this.s.screen.interval = setInterval( function () {
434 var iScrollTop = $(document).scrollTop();
435 var iScrollDelta = iScrollTop - that.s.screen.scrollTop;
436 that.s.screen.y += iScrollDelta;
438 if ( that.s.screen.height - that.s.screen.y + iScrollTop < 50 )
440 $('html, body').animate( {
441 "scrollTop": iScrollTop + 50
444 else if ( that.s.screen.y - iScrollTop < 50 )
446 $('html, body').animate( {
447 "scrollTop": iScrollTop - 50
451 if ( that.s.dt.oScroll.sY !== "" )
453 if ( that.s.screen.y > that.s.scroller.bottom - 50 )
455 $(that.s.dt.nTable.parentNode).animate( {
456 "scrollTop": $(that.s.dt.nTable.parentNode).scrollTop() + 50
459 else if ( that.s.screen.y < that.s.scroller.top + 50 )
461 $(that.s.dt.nTable.parentNode).animate( {
462 "scrollTop": $(that.s.dt.nTable.parentNode).scrollTop() - 50
471 * Mouse move event handler for during a move. See if we want to update the display based on the
472 * new cursor position
473 * @method _fnFillerDragMove
474 * @param {Object} e Event object
477 "_fnFillerDragMove": function (e)
479 if ( e.target && e.target.nodeName.toUpperCase() == "TD" &&
480 e.target != this.s.drag.endTd )
482 var coords = this._fnTargetCoords( e.target );
484 if ( this.c.mode == "y" && coords.x != this.s.drag.startX )
486 e.target = $('tbody>tr:eq('+coords.y+')>td:eq('+this.s.drag.startX+')', this.dom.table)[0];
488 if ( this.c.mode == "x" && coords.y != this.s.drag.startY )
490 e.target = $('tbody>tr:eq('+this.s.drag.startY+')>td:eq('+coords.x+')', this.dom.table)[0];
493 if ( this.c.mode == "either")
495 if(coords.x != this.s.drag.startX )
497 e.target = $('tbody>tr:eq('+this.s.drag.startY+')>td:eq('+coords.x+')', this.dom.table)[0];
499 else if ( coords.y != this.s.drag.startY ) {
500 e.target = $('tbody>tr:eq('+coords.y+')>td:eq('+this.s.drag.startX+')', this.dom.table)[0];
505 if ( this.c.mode !== "both" ) {
506 coords = this._fnTargetCoords( e.target );
509 var drag = this.s.drag;
510 drag.endTd = e.target;
512 if ( coords.y >= this.s.drag.startY ) {
513 this._fnUpdateBorder( drag.startTd, drag.endTd );
516 this._fnUpdateBorder( drag.endTd, drag.startTd );
518 this._fnFillerPosition( e.target );
521 /* Update the screen information so we can perform scrolling */
522 this.s.screen.y = e.pageY;
523 this.s.screen.scrollTop = $(document).scrollTop();
525 if ( this.s.dt.oScroll.sY !== "" )
527 this.s.scroller.scrollTop = $(this.s.dt.nTable.parentNode).scrollTop();
528 this.s.scroller.top = $(this.s.dt.nTable.parentNode).offset().top;
529 this.s.scroller.bottom = this.s.scroller.top + $(this.s.dt.nTable.parentNode).height();
535 * Mouse release handler - end the drag and take action to update the cells with the needed values
536 * @method _fnFillerFinish
537 * @param {Object} e Event object
540 "_fnFillerFinish": function (e)
542 var that = this, i, iLen, j;
544 $(document).unbind('mousemove.AutoFill mouseup.AutoFill');
546 this.dom.borderTop.style.display = "none";
547 this.dom.borderRight.style.display = "none";
548 this.dom.borderBottom.style.display = "none";
549 this.dom.borderLeft.style.display = "none";
551 this.s.drag.dragging = false;
553 clearInterval( this.s.screen.interval );
556 var table = this.dom.table;
557 var coordsStart = this._fnTargetCoords( this.s.drag.startTd );
558 var coordsEnd = this._fnTargetCoords( this.s.drag.endTd );
559 var columnIndex = function ( visIdx ) {
560 return that.s.dt.oApi._fnVisibleToColumnIndex( that.s.dt, visIdx );
563 // xxx - urgh - there must be a way of reducing this...
564 if ( coordsStart.y <= coordsEnd.y ) {
565 for ( i=coordsStart.y ; i<=coordsEnd.y ; i++ ) {
566 if ( coordsStart.x <= coordsEnd.x ) {
567 for ( j=coordsStart.x ; j<=coordsEnd.x ; j++ ) {
569 node: $('tbody>tr:eq('+i+')>td:eq('+j+')', table)[0],
570 x: j - coordsStart.x,
571 y: i - coordsStart.y,
572 colIdx: columnIndex( j )
577 for ( j=coordsStart.x ; j>=coordsEnd.x ; j-- ) {
579 node: $('tbody>tr:eq('+i+')>td:eq('+j+')', table)[0],
580 x: j - coordsStart.x,
581 y: i - coordsStart.y,
582 colIdx: columnIndex( j )
589 for ( i=coordsStart.y ; i>=coordsEnd.y ; i-- ) {
590 if ( coordsStart.x <= coordsEnd.x ) {
591 for ( j=coordsStart.x ; j<=coordsEnd.x ; j++ ) {
593 node: $('tbody>tr:eq('+i+')>td:eq('+j+')', table)[0],
594 x: j - coordsStart.x,
595 y: i - coordsStart.y,
596 colIdx: columnIndex( j )
601 for ( j=coordsStart.x ; j>=coordsEnd.x ; j-- ) {
603 node: $('tbody>tr:eq('+i+')>td:eq('+j+')', table)[0],
604 x: coordsStart.x - j,
605 y: coordsStart.y - i,
606 colIdx: columnIndex( j )
613 // An auto-fill requires 2 or more cells
614 if ( cells.length <= 1 ) {
621 for ( i=0, iLen=cells.length ; i<iLen ; i++ ) {
623 var column = this.s.columns[ cell.colIdx ];
624 var read = column.read.call( column, cell.node );
625 var stepValue = column.step.call( column, cell.node, read, previous, i, cell.x, cell.y );
627 column.write.call( column, cell.node, stepValue );
629 previous = stepValue;
638 if ( this.c.complete !== null ) {
639 this.c.complete.call( this, edited );
642 // In 1.10 we can do a static draw
643 if ( DataTable.Api ) {
644 new DataTable.Api( this.s.dt ).draw( false );
647 this.s.dt.oInstance.fnDraw();
653 * Display the drag handle on mouse over cell
654 * @method _fnFillerDisplay
655 * @param {Object} e Event object
658 "_fnFillerDisplay": function (e)
660 var filler = this.dom.filler;
662 /* Don't display automatically when dragging */
663 if ( this.s.drag.dragging)
668 /* Check that we are allowed to AutoFill this column or not */
669 var nTd = (e.target.nodeName.toLowerCase() == 'td') ? e.target : $(e.target).parents('td')[0];
670 var iX = this._fnTargetCoords(nTd).column;
671 if ( !this.s.columns[iX].enable )
673 filler.style.display = "none";
677 if (e.type == 'mouseover')
679 this.dom.currentTarget = nTd;
680 this._fnFillerPosition( nTd );
682 filler.style.display = "block";
684 else if ( !e.relatedTarget || !e.relatedTarget.className.match(/AutoFill/) )
686 filler.style.display = "none";
692 * Position the filler icon over a cell
693 * @method _fnFillerPosition
694 * @param {Node} nTd Cell to position filler icon over
697 "_fnFillerPosition": function ( nTd )
699 var offset = $(nTd).offset();
700 var filler = this.dom.filler;
701 filler.style.top = (offset.top - (this.s.filler.height / 2)-1 + $(nTd).outerHeight())+"px";
702 filler.style.left = (offset.left - (this.s.filler.width / 2)-1 + $(nTd).outerWidth())+"px";
708 DataTable.AutoFill = AutoFill;
709 DataTable.AutoFill = AutoFill;
713 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
715 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
723 AutoFill.version = "1.2.1";
730 AutoFill.defaults = {
732 * Mode for dragging (restrict to y-axis only, x-axis only, either one or none):
734 * * `y` - y-axis only (default)
735 * * `x` - x-axis only
736 * * `either` - either one, but not both axis at the same time
737 * * `both` - multiple cells allowed
747 * Column definition defaults
752 * If AutoFill should be enabled on this column
760 * Allow automatic increment / decrement on this column if a number
771 * Default function will simply read the value from the HTML of the
775 * @param {node} cell `th` / `td` element to read the value from
776 * @return {string} Data that has been read
778 read: function ( cell ) {
779 return $(cell).html();
783 * Cell write function
785 * Default function will simply write to the HTML and tell the DataTable
789 * @param {node} cell `th` / `td` element to write the value to
790 * @return {string} Data two write
792 write: function ( cell, val ) {
793 var table = $(cell).parents('table');
794 if ( DataTable.Api ) {
796 table.DataTable().cell( cell ).data( val );
800 var dt = table.dataTable();
801 var pos = dt.fnGetPosition( cell );
802 dt.fnUpdate( val, pos[0], pos[2], false );
807 * Step function. This provides the ability to customise how the values
810 * @param {node} cell `th` / `td` element that is being operated upon
811 * @param {string} read Cell value from `read` function
812 * @param {string} last Value of the previous cell
813 * @param {integer} i Loop counter
814 * @param {integer} x Cell x-position in the current auto-fill. The
815 * starting cell is coordinate 0 regardless of its physical position
817 * @param {integer} y Cell y-position in the current auto-fill. The
818 * starting cell is coordinate 0 regardless of its physical position
820 * @return {string} Value to write
822 step: function ( cell, read, last, i, x, y ) {
823 // Increment a number if it is found
825 var match = this.increment && last ? last.match(re) : null;
827 return last.replace( re, parseInt(match[1],10) + (x<0 || y<0 ? -1 : 1) );
829 return last === undefined ?
840 // Define as an AMD module if possible
841 if ( typeof define === 'function' && define.amd ) {
842 define( ['jquery', 'datatables'], factory );
844 else if ( typeof exports === 'object' ) {
846 factory( require('jquery'), require('datatables') );
848 else if ( jQuery && !jQuery.fn.dataTable.AutoFill ) {
849 // Otherwise simply initialise as normal, stopping multiple evaluation
850 factory( jQuery, jQuery.fn.dataTable );
854 }(window, document));