angular-generic-table

A generic table for Angular 2+. This project is a re-write of this project for AngularJS, the idea is to have support for the same features and that the configuration should be the same. Generic table uses standard markup for tables ie. table, tr and td elements etc. and has support for expanding rows, search, filters, sorting, pagination, export to CSV, column clicks, custom column rendering, custom export values. View demo

Features

• Uses standard HTML tables (no divs etc.)
• Markup uses Twitter bootstrap class names
• Client and server-side pagination, sorting and filtering
• Lazy-loading of data from server
• Expanding rows with custom component
• Use custom functions for sorting, exporting and rendering of data
• Configure table using json object (add columns etc.)
• Toggle column visibility
• Export to CSV

Installation and usage

Run npm install --save angular-generic-table

Include generic table module in your project, for example if you want to add it to your app module:

App Module

import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import { GenericTableModule } from 'angular-generic-table';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    GenericTableModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Configure the table in your component, in this case we're adding a basic example with static data to a component called StaticComponent.

Static Component

import { Component } from '@angular/core';
import { GtConfig } from 'angular-generic-table';

@Component({
  selector: 'app-static',
  templateUrl: './static.component.html'
})
export class StaticComponent {

  public configObject: GtConfig<any>;
  
  public data:Array<{
    id:number,
    name:string,
    lucky_number:number
  }> = [];

  constructor() {

    this.configObject = {
      settings:[{
        objectKey:'id',
        sort:'desc',
        columnOrder:0
      },{
        objectKey:'name',
        sort:'enable',
        columnOrder:1
      },{
        objectKey:'lucky_number',
        sort:'enable',
        columnOrder:2
      }],
      fields:[{
        name:'Id',
        objectKey:'id'
      },{
        name:'Name',
        objectKey:'name'
      },{
        name:'Lucky number',
        objectKey:'lucky_number'
      }],
      data:[{
        "id": 1,
        "name": "Anna",
        "lucky_number": 63
      }, {
        "id": 2,
        "name": "Julie",
        "lucky_number": 8
      }, {
        "id": 3,
        "name": "Lillian",
        "lucky_number": 30
      }, {
        "id": 4,
        "name": "Norma",
        "lucky_number": 13
      }, {
        "id": 5,
        "name": "Ralph",
        "lucky_number": 28
      }, {
        "id": 6,
        "name": "Benjamin",
        "lucky_number": 66
      }, {
        "id": 7,
        "name": "George",
        "lucky_number": 66
      }, {
        "id": 8,
        "name": "Ryan",
        "lucky_number": 65
      }, {
        "id": 9,
        "name": "Martha",
        "lucky_number": 57
      }, {
        "id": 10,
        "name": "Todd",
        "lucky_number": 65
      }]
    };
  }
}

Usage

<generic-table [gtSettings]="configObject.settings" [gtFields]="configObject.fields" [gtData]="configObject.data"></generic-table>

Configuration

In order for generic tables to render the data in a table, we need to create a configuration object like this:

config = {
  settings:[],
  fields:[],
  data:[]
}

Settings array

Each column must have it's own settings object that can have the following properties:

| Key | Type | Usage | Default | | |:------------|:--------|:--------------------------------------------------------------------------------------------------|:---------------|:-----------| | objectKey | string | unique identifier for column, used for data mapping | | | | visible | boolean | should column be visible | true | (OPTIONAL) | | enabled | boolean | should column be enabled, if not enabled a user shouldn't be able to toggle visibility for column | true | (OPTIONAL) | | sort | string | "enable", "asc" or "desc" use "disable" to disable sorting | 'enable' | (OPTIONAL) | | sortOrder | number | initial sort order | order in array | (OPTIONAL) | | columnOrder | number | initial column order | order in array | (OPTIONAL) | | export | boolean | should column be included when exporting to CSV | true | (OPTIONAL) | | search | boolean | should column be included when using global search | true | (OPTIONAL) |

Usage:

[{
    objectKey:"first_column"
  }, {
    objectKey:"second_column"
  }, {
  objectKey:"third_column"
}]

Fields array

Each column must also have it's own field definition object that can have the following properties:

| Key | Type | Usage | | |:-----------|:--------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------| | name | string | heading for column | | | objectKey | string | unique identifier for column, used for data mapping | | | classNames | string | class names to be applied to column | (OPTIONAL) | | render | function(row) | custom function for data presentation, ex. display 1480579417501 as 2016-12-01 09:03:37 | (OPTIONAL) | | value | function(row) | custom function for data manipulation/creation ex. combine first name and last name into a new column | (OPTIONAL) | | sort | function(row) | custom function used when sorting column, i.e. you might want to sort a value as a number but display (render) it as a string | (OPTIONAL) | | search | function(row) | custom function used when searching column, i.e similar to render, you might want to match on something else than the raw data. If no search function is defined, generic table will look for a value function and if no value function is defined table will use raw data value. | (OPTIONAL) | | export | function(row) | feature not available yet... | (OPTIONAL) | | click | function(row) | execute function when column cell is clicked | (OPTIONAL) | | expand | boolean | if true row will expand and show a custom component passed using gtRowComponent (false by default) | (OPTIONAL) |

Usage:

[{
    objectKey:"first_column",
    name:"First column"
  }, {
    objectKey:"second_column",
    name:"Second column"
  }, {
    objectKey:"third_column",
    name:"Third column"
}]

Data array

The data for each row needs to be stored in an object where each key in the object should map against object keys specified in the settings and field arrays ex.

[{
  first_column:"first row",
  second_column:1,
  third_column:"third column"
}, {
  first_column:"second row",
  second_column:2,
  third_column:"third column"
}]

Table attributes/inputs

To pass data, settings and configuration to the table using the following inputs:

| Attribute | Type | Usage | | |:------------------|:----------|:---------------------------------------------------------------------------------------|:-----------| | gtSettings | array | used for passing settings | | | gtFields | array | used for passing field definitions | | | gtData | array | used for passing data | | | gtClasses | string | used for adding classes to table element | (OPTIONAL) | | gtTexts | object | use to override default texts | (OPTIONAL) | | gtOptions | object | use to override default table options (see available options below) | (OPTIONAL) | | gtInfo | object | used for passing record info to table (lazy loading only) | (OPTIONAL) | | gtRowComponent | component | used for passing expanding row component to table | (OPTIONAL) |

Usage:

<generic-table [gtClasses]="'table-hover'" [gtSettings]="configObject.settings" [gtFields]="configObject.fields" [(gtData)]="configObject.data" [gtRowComponent]="expandedRow" [gtOptions]="{lazyLoad:true}"></generic-table>

Table options

Available options:

| Name | Type | Usage | Default | | |:----------------|:------------|:----------------------------------------------------------------------------------------------|:--------|:-----------| | csvDelimiter | string | csv delimiter when exporting to CSV file | ";" | (OPTIONAL) | | stack | boolean | stack columns on mobile devices and tablets, requires css (included) | false | (OPTIONAL) | | lazyLoad | boolean | should table lazy load data | false | (OPTIONAL) | | cache | boolean | should table cache data when lazy loading | false | (OPTIONAL) | | debounceTime | number (ms) | prevent multiple server requests for data when lazy loading by setting a debounce time | 200 | (OPTIONAL) | | highlightSearch | boolean | should table highlight matched search terms, style using .gt-highlight-search selector | false | (OPTIONAL) | | rowSelection | boolean | enable row selection (on row click), emits select/deselect event with currently selected rows | false | (OPTIONAL) |

Usage:

<generic-table ... [gtOptions]="{lazy:true, cache: true}"></generic-table>

Table events

The table emits events using gtEvent, the events are passed in an object which looks like this:

{
  name:'gt-sorting-applied',
  value: 'passed data...'
}

Currently the table emits the following events:

| Name | Trigger | Data passed with event | |:----------------------|:-------------------------------------------------------|:-----------------------------------------------------------------------------------| | gt-sorting-applied | sorting changed | new sort order in array ex. ["-firstColumn", "secondColumn"] | | gt-row-length-changed | record length changed | new record length ex. 10 | | gt-page-changed | page changed | current state ex. {pageCurrent: current page, recordLength: current record length} | | gt-page-changed-lazy | page changed and no data exits for new page | current state ex. {pageCurrent: current page, recordLength: current record length} | | gt-info | table info has changed (not emitted when lazy loading) | current state ex. {pageCurrent: current page, recordLength: current record length} | | gt-exported-csv | table has exported data to csv file | file name | | gt-row-select | row selected (on row clicked) | row selection ex. {changedRow: row object, selectedRows: array with selected rows} | | gt-row-deselect | row deselected (on row clicked) | row selection ex. {changedRow: row object, selectedRows: array with selected rows} | | gt-row-select-all | selectAllRows function | row selection ex. {changedRow: 'all', selectedRows: array with selected rows} | | gt-row-deselect-all | deselectAllRows function | row selection ex. {changedRow: 'all', selectedRows: array with selected rows} | | gt-row-expand | when row is expanded | row state ex. {changedRow: row object, expandedRows: array with expanded rows} | | gt-row-collapse | when row is collapsed | row state ex. {changedRow: row object, expandedRows: array with expanded rows} | | gt-row-expand-all | expandAllRows function | row state ex. {changedRow: row object, expandedRows: array with expanded rows} | | gt-row-collapse-all | collapseAllRows function | row state ex. {changedRow: row object, expandedRows: array with expanded rows} |

Usage:

<generic-table ... (gtEvent)="trigger($event)"></generic-table>

public trigger = function($event){
    switch($event.name){
      case 'gt-sorting-applied':
            console.log($event.value);
            break;
    }
  };

Texts

Override texts by passing a new object using gtTexts attribute.

Available texts:

| Key | Description | Default | |:------------------------|:---------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------| | loading | Text displayed when table rows are loading data (lazy loading only) | Loading... | | noData | Text displayed when table contains no data | No data | | noMatchingData | Text displayed when table search/filter has no matches | No data matching results found | | noVisibleColumnsHeading | Table heading displayed when no columns are visible | No visible columns | | noVisibleColumns | Table content displayed when no columns are visible | Please select at least one column to be visible. | | tableInfo | Text displayed in table info component when neither search nor filter has been applied | Showing #recordFrom to #recordTo of #recordsAfterSearch entries. | | tableInfoAfterSearch | Text displayed in table info component when search or filter has been applied | Showing,#recordFrom to #recordTo of #recordsAfterSearch entries (filtered from a total of #recordsAll entries). | | csvDownload | File name for CSV export (.csv is added by default) | download | | sortLabel | Text for sort label shown when tables columns are stacked | Sort: | | paginateNext | Text used by screen readers for going to next page | Next page | | paginatePrevious | Text used by screen readers for going to previous page | Previous page |

Usage:

<generic-table ... [gtTexts]="{loading:'Loading data...'}"></generic-table>

Table functions

| Name | Description | Usage |:----------------|:--------------------------------------------------------------------------------------------------------|:---------------------------------------------| | exportCSV | See 'Export to CSV' section below | myTable.exportCSV('custom-file-name') | | gtApplyFilter | Filter table data, see example | myTable.gtApplyFilter(object with filters) | | gtClearFilter | Clear filters, see example | myTable.gtClearFilter() | | gtSearch | See 'Global table search and highlight' section below | myTable.gtSearch(search string) | | changeRowLength | Change number of visible rows, see example | myTable.changeRowLength(number of rows) | | nextPage | Go to next page | myTable.nextPage() | | previousPage | Go to previous | myTable.previousPage() | | goToPage | Go to specific page (pass page number) | myTable.goToPage() | | selectAllRows | Select all rows | myTable.selectAllRows() | | deselectAllRows | Deselect all rows | myTable.deselectAllRows() | | expandAllRows | Expand all rows | myTable.expandAllRows() | | collapseAllRows | Collapse all rows | myTable.collapseAllRows() |

Global table search and highlight

Search and filter table using global search. Separate multiple search terms with a space [ ] or match whole phrase by putting them within quotes ["].

Define custom search value for individual columns by declaring a custom search function in the fields array, ie. you might want the search to match one value but display/render another in the table ex. search for 100000 and display 1 000 000,00 in the table.

Turn of search for individual columns by setting column setting property search to false.

Usage:

Call generic tables search function and pass your search term(s)

myTable.gtSearch(searchString);

Usage (when lazy loading):

Return search terms in your server response.

this.configObject.info:GtInformation = {
  pageCurrent: 1,
  pageNext: 2,
  pagePrevious: null,
  pageTotal: 10,
  recordLength: 10,
  recordsAll: 100,
  recordsAfterFilter: 100,
  recordsAfterSearch: 13,
  searchTerms: "foo bar"
}

see demo for full implementation and examples

Column visibility

You can implement your own control for toggling column visibility, either bind directly to the settings array and alter the visibility property directly or create an object to hold the values until your ready to update. Don't forget to call 'redraw()' when you want the table to update ie. (click)="myTable.redraw()"

Export to CSV

Export table data to CSV and optionally pass a file name. Please note that the table exports data after sort order, filters and global search have been applied. In case you use the lazy load feature you'll have to implement the export server-side.

Define custom export value for individual columns by declaring a custom export function in the fields array, ie. you might want the export one value but display/render another in the table ex. export 100000 as a number but display it as a string 1 000 000,00 in the table.

Turn of export for individual columns by setting column setting property export to false.

Usage:

(click)="myTable.exportCSV('custom-file-name')"

Pagination

Display pagination for your table, uses bootstrap default markup.

Usage:

<gt-pagination [genericTable]="myTable"></gt-pagination>

Options:

| Attribute | Type | Usage | | |:------------------|:---------------|:--------------------------------------------------------------------|:-----------| | genericTable | table instance | used for linking pagination component to table | | | gtClasses | string | used for adding classes to pagination element, ex. pagination-sm | (OPTIONAL) |

Table information

Display information about your table, ie. number of records, filtered records, record length etc.

Usage:

<gt-table-info [genericTable]="myTable"></gt-table-info>

Options:

| Attribute | Type | Usage | | |:------------------|:---------------|:---------------------------------------------------------------------------------------------------------|:-----------| | genericTable | table instance | used for linking table info component to table | | | customText | string | override default text provided by generic table component, useful when you want to split up the display | (OPTIONAL) |

Available information: Use the key in the text passed, either to the table component using gtTexts attribute or to the individual table info component using customText attribute. Ex. Showing #recordFrom to #recordTo. will be rendered as Showing 1 to 10.

| Name | Key | Description | |:-------------------|:--------------------|:----------------------------------------------------------------------------| | pageCurrent | #pageCurrent | Displays current page number | | pageNext | #pageNext | Displays next page number | | pagePrevious | #pagePrevious | Displays previous page number | | pageTotal | #pageTotal | Displays total number of pages | | recordFrom | #recordFrom | Displays visible record number from | | recordTo | #recordTo | Displays visible record number to | | recordLength | #recordLength | Displays number of records shown | | recordsAll | #recordsAll | Displays total number of records | | recordsAfterFilter | #recordsAfterFilter | Displays total number of records after filters have been applied | | recordsAfterSearch | #recordsAfterSearch | Displays total number of records after filters and search have been applied |

Please note

As this component is still under development, please expect breaking changes.