search

gdepourtales / ng-cells

AngularJS Table directive that draws a table of data with different features
http://gdepourtales.github.io/ng-cells/
Other
77 stars 17 forks source link

readme

ng-cells

AngularJS Table directive

This directive draws a table of data with different features. It has no dependency other than angularjs. It has been tested on Google Chrome, Safari, Opera and Firefox and Internet Explorer 10 (8+ in developer mode)

To use this directive, just add the ngcTableDirective as dependency. The template is handled as an external HTML file and integrated during the build process in the ngc-template module. The template is registered in the angularjs template cache with the key ngc.table.tpl.html

Features

Usage

Table

The directive displays a grid of cells organized as the following principles :

--------------------------------
| |      COLUMN LETTERS        |
--------------------------------
| |      | HEADER ROWS |       |
|-|------|---------------------|
|R|      |             |       |
|O| LEFT |   CENTER    | RIGHT |
|W| COLS |    COLS     | COLS  |
|#|      |             |       |
|-|------|-------------|-------|
| |      | FOOTER ROWS |       |
--------------------------------

When the data matrix vertical dimension than the total number of rows, the area between header and footer is scrollable. The behaviour is identical for the number of columns, the area between the left and right columns becomes scrollable.

ng-cells is also available through bower (bower install ng-cells)

Minimal example to display a table with one million cells (1000 x 1000 data matrix) with default settings and no styling :

<!DOCTYPE html>
<html ng-app="ngcTableDirectiveTest">
<head>
    <title>Test Template</title>
    <link href="https://github.com/gdepourtales/ng-cells/blob/master/./dist/ng-cells-0.1.1.css" rel="stylesheet" type="text/css">
    <script src="https://github.com/gdepourtales/ng-cells/raw/master/./lib/angular-1.2.6.js"></script>
    <script src="https://github.com/gdepourtales/ng-cells/raw/master/./dist/ng-cells-0.1.1.js"></script>
    <script>
        angular.module('ngcTableDirectiveTest', ['ngcTableDirective'])
                .controller('TestCtrl', function($scope) {
                    $scope.data = [];

                    for (var row = 0; row < 1000; row++) {
                        var rowContent = [];
                        for (var col = 0; col < 1000; col++) {
                            rowContent.push(row * col + col);
                        }
                        $scope.data.push(rowContent);
                    }

                });

    </script>

</head>
<body>
<div ng-controller="TestCtrl">
    <div ngc-table data="data"></div>
</div>
</body>
</html>

The data must be given as a two dimensional array (ie array[][]). If your data is a complex object, you can define a custom data function to extract the data value. For example, the following html snippet will use the below javascript function to get the value

<div ngc-table data="data" custom-data-value-fn="customDataFn"></div>
$scope.customDataFn = function(data, row, col) {
    return data[1000 - row - 1][1000 - col - 1];
}

The table settings like number of columns and rows in each table part can be specified with different attributes which names should be self-explanatory. Please see the reference below. For example:

<ngc-table
        data="data"
        left-column-number="5" left-column-widths="'30px'"
        center-column-number="10" center-column-widths="['40px', '60px', '40px']"
        right-column-number="5" right-column-widths="['60px', '40px', '60px', '40px', '60px']"
        header-row-number="2" header-row-heights="['30px', '15px']"
        row-number='15' row-heights="['41px', '14px']"
        footer-row-number="3" footer-row-heights="'24px'">
</ngc-table>

Cell Ranges

Ranges

Ranges let specify custom behaviour for data ranges. The range is defined by the area limits and holds custom CSS classes, format and styling functions and event callbacks. Ranges are specified in the data matrix range, thus they are not related to cells.

To add custom ranges, use the declarative ranges definitions such as this example :

 <ngc-table data="data">
     <ngc-range top="0" bottom="1000" left="0" right="5" format-fn="cellFormatRange1"></ngc-range>
     <ngc-range top="3" bottom="8" left="3" right="998" format-fn="cellFormatRange2"></ngc-range>
     <ngc-range top="10" bottom="12" left="6" right="15" format-fn="cellFormatRange3"></ngc-range>
     <ngc-range top="13" bottom="30" left="3" right="998" format-fn="cellFormatRange4"></ngc-range>
     <ngc-range top="990" bottom="998" left="3" right="998"></ngc-range>
 </ngc-table>

Ranges can overlap but only one class, event function, format function etc is activated on a single cell. The order of precedence is the same as the order of the range declarations. The callback receives the cell and the cellData.

Here an example of mousemove event handling :

<ngc-range top="0" bottom="5" left="0" right="5" click-fn="clickFn"  ></ngc-range>
$scope.clickFn = function(event, cellData) {
    console.log(event.target);
    console.log(cellData.row);
    console.log(cellData.col);
    console.log(cellData.data);
    console.log(cellData.value);
}

CSS Classes

In addition to ranges custom classes, the table embeds CSS classes to identify each part of the table. For example, to set the pen color and the background color of all cells of the right header part, use the following CSS statement in your stylesheet. If you have other elements that clash you can add an additional ngc class to make it more specific.

.cell.right.header {
    background-color: #880000;
    color: whitesmoke;
}

Directive Reference

Table

Range

CSS Reference

Here's a list of the classes which can be used to select cells according to the table parts they belong to

Column names

Header section

Middle section

Footer section

For example, in order to select the cells of the last row of the center columns in the middle section, use the following selector

.ngc.middle.row .center.middle.last.cell {
...
}

All element class declarations also have the ngc class. First and last rows of each section have the resp. first and last classes. Same for cells in each row and section.

Thanks

Many thanks for contributors

License

Copyright 2013,2014 Guy de Pourtalès

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.