gajus / wholly Goto Github PK

jQuery plugin used to select the entire table row and column in response to mouseenter and mouseleave events. Wholly supports table layouts that utilize colspan and rowspan.

Home Page: http://gajus.com/sandbox/wholly/demo/

License: Other

JavaScript 94.27% CSS 5.73%

wholly's Introduction

Wholly

jQuery plugin used to select the entire table row and column in response to mouseenter and mouseleave events. Wholly supports table layouts that utilize colspan and rowspan.

Interactive demo.

How does it work?

If you want to support colspan and rowspan, then first you need to build table index, ie. matrix that identifies cell position in every row regardless of the markup. Then you need to track events of all the table cells and calculate their offset in the matrix and the columns that share the horizontal and vertical index.

The resulting lookup is illustrated in the following animation:

Why not CSS?

There are at least a few ways to achieve column highlighting using just CSS or with little JavaScript, e.g.

http://stackoverflow.com/a/11175979/368691, CSS only solution using pseudo elements.
http://www.cssnewbie.com/simple-table-column-highlighting/#.U1Ywa1GSwe4, JavaScript together with HTML table column element.

Neither of the above solutions support rowspan or colspan. In essence, neither of the above will work if you have header groups, merged columns or a summarizing table footer. Wholly supports colspan and rowspan anywhere in the <table>.

Use case

Most often you'd use Wholly to highlight the entire column of the selected cell.

Wholly is not limited to setting a particular style. The custom event hooks allow you to select the entire row and column and can be used to copy the data, for selecting multiple columns, etc.

Usage

There are two options that automate highlighting:

$('table').wholly({
    highlightHorizontal: 'horizontal-class-name',
    highlightVertical: 'vertical-class-name'
});

The following events are available:

Event Name	Description
`wholly.mouseenter-horizontal`	Fired on the individual table cells.
`wholly.mouseleave-horizontal`	Fired on the individual table cells.
`wholly.mouseenter-vertical`	Fired on the individual table cells.
`wholly.mouseleave-vertical`	Fired on the individual table cells.
`wholly.mouseenter`	Fired on the whole table.
`wholly.mouseleave`	Fired on the whole table.

To get the affected cells, use the the above events as such:

$('table').on('wholly.mouseenter-horizontal wholly.mouseleave-horizontal mouseenter-vertical mouseleave-vertical', function (e) {
    // e.target
});

$('table').on('wholly.mouseenter wholly.mouseleave', function (e, affectedAxes) {
    // affectedAxes.horizontal
    // affectedAxes.vertical
});

wholly's People

Contributors

Stargazers

Watchers

wholly's Issues

Problem with wholly table which contains a datepicker table

I have a table which is highlighted by wholly, and that's great. However, inside some of the table cells, I am using the bootstrap datepicker, which generates its own table. If I click the datepicker, and then mouse-over the datepicker's tooltip, then every one of these cells generates this unhelpful console.log:

Uncaught TypeError: Cannot read property '1' of undefined at HTMLTableCellElement.

I don't actually need wholly to work within the embedded datepicker (indeed, it's best that it doesn't), but it would be nice to get rid of the error messages. Maybe we need a way to tell wholly that a table within a table should not be treated as inheriting the highlightable class?

Documentation: how to turn it off again

If you are scrolling a wholly-highlighted table, and there is a position:sticky first-row or first column, then
a side-effect of wholly is that the table cells that are supposed to slide "under" the hidden row/col always show-through.
So we need a way to undo wholly after it has been applied. How?

Include unit tests

Include unit tests to cover the most fundamental logic components, such as matrix building.

Add row selector

When a table is nested in a cell, selecting cells gives unexpected results. For example:

<table id="main">
    <tr>
        <td>Main Cell</td>
    </tr>
    <tr>
        <td>
            <table id="child">
                <tr>
                    <td>Child cell</td>
                </tr>
            </table>
        </td>
    </tr>
</table>

To be able to distinguish between the rows of the main table and the rows of the nested table, an option can be added to select rows (with tr as default):

Wholly.DEFAULTS = {
    rowSelector: 'tr',
    ...
}

The rows selection is set as:

wholly.indexTable = function (table) {
    var tableIndex = wholly.generateTableMatrix(table),
        rows = table.find(this.options.rowSelector);
    ...
}

And for the example above:

<table id="main">
    <tr>
        <td>Main Cell</td>
    </tr>
    <tr>
        <td>
            <table id="child">
                <tr class="skip">
                    <td>Child cell</td>
                </tr>
            </table>
        </td>
    </tr>
</table>

$('#main')wholly({
    rowSelector: 'tr:not(.skip)',
    ...
});

Method to reindex the table

Reindex the table in case of "change" event.

td with display:none should be treated as rowspan=0,colspan=0

Consider a table where some of the are switched on and off by having "style='display:none'".
For a of this type, it is removed entirely from the table, and the HTML treats it as never existing (effectively a zero rowspan/colspan).

However, wholly still counts these cells as if they were there with a normal colspan/rowspan of 1.

As a result, the vertical/horizontal highlighting goes completely crooked.

Add selection option

This will be good if the cells selection is set as an option. For example:

 defaultOptions = {
     highlightHorizontal: null,
     highlightVertical: null,
     selection: 'td, th'
 };

And in code:

table.on('mouseenter', options.selection, function () {
...
}

table.on('mouseleave', options.selection, mouseleave);

So user can decide wich cells are processed.

$('table').wholly({
    highlightHorizontal: 'horizontal-class-name',
    highlightVertical: 'vertical-class-name',
    selection: 'td:not(".skip")'
})

Add an example of large table

Demonstrate scalability of Wholly. Include example of a table with 10x200 rows.

How do I install the script using the Bower?

Since

$ bower install jquery.wholly.min.js
bower                        ENOTFOUND Package jquery.wholly.min.js not found

Tables within Tables

If the table.highlightable contains another table, some really weird things occur.

The highlighting mechanism binds the x,y of the outer-table to the x,y of the inner table, so both sets of highlights trigger each other.
If we're unlucky, the columns in the outer table can get a "kink" in which cells are highlighted.

There may be a better way, but here is my fix.

Change wholly.js:

var tableIndex = wholly.generateTableMatrix(table),
//If the table contains another table, some 'bad' things happen with the counters.
//Add .fixhighlightable to the tr of the inner table.
//rows = table.find('tr');
rows = table.find('tr:not(.fixhighlightable)');

In the html, edit the inner table, and add .fixhighlightable on every <tr>.

This fix would be neater if wholly could either scan for and ignore the inner table, or if the fixhighlightable class were applied to the inner table.

Supporting selected column/row events

Thanks for developing a slick plugin, I like it!

Any chance in providing some additional wholly events for selected (via mousedown/mouseup) column/row so that a class could be toggled? Maybe there is a way to do this already?

Error - console.groupEnd() IE<v.11

Object doesn't support property or method 'groupEnd'
wholly.min.js, line 162
/console.groupEnd()/
How do fix this?
Thanks.