ng2-pack

Ng2Pack

A collection of components/utilities designed for data-intensive tables.

This library is currently under the development. API may still change! Please feel free to open issues not only for bug reports but also for ideas, comments, and questions, a.k.a. support requests. We would love to hear your feedback.

There are several key characteristics of the library:

• Levels of abstraction This library provides components with a varying level of abstraction. The highest abstraction gives you the most comfort. In the case that you need more flexibility, you can switch to lower API. If that is not enough, you access even lower-level API.

• Convention over configuration Despite many inputs and configuration options, you should be able to get running quickly because sensible defaults are preset or computed from the data. In some cases, even required inputs are automatically initialized for the subcomponents according to certain conventions.

• Fallback You can gradually migrate out of the library abstraction. It happens that library's abstractions are in the way. In that case, you can get full control by providing a custom template. The library accepts custom templates of different granularity.

Installation

You can install the package with yarn or npm.

yarn add ng2-pack

Then import the table module from 'ng2-pack'.

import { TableModule } from 'ng2-pack';
// import other modules (AppComponent, BrowserModule, ...) 

@NgModule({
  declarations: [AppComponent],
  imports: [
    TableModule,
    // list other modules...
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

We recommend that you install some CSS framework (e.g. Bootstrap) to enhance the style of the table.

Getting Started

We follow the philosophy "convention over configuration" to make it easier for you to get started. You can see it from the first code snippet.

NOTE: The examples in the demo app correspond to the following code snippets.

• Prepare your data — an array of objects (a.k.a. rows). Each row object can contain a nested object or an array of objects with simple data types (in other words, two levels of nesting are allowed). For example:

let rows = [{
    name: 'Alan',
    studies: [{
      university: 'TUM', 
      // additional attributes (degree, specialization, …)
    }, 
    // more study subrows 
    ],
    address: {
      country: 'cz', 
      // city, postal code …
    },
  }, 
  // more rows…
]

• Pass the data to rows input. Other attributes have intelligent defaults.

<iw-table #table [rows]="rows"></iw-table>
<!-- HINT: You can display how the column configuration was initialized: <pre>{{ table.columnsConfig | json }} </pre>   -->

• Adjust according to your needs. The most important attribute is the column configuration since the initialized values may not be exactly what you want. See the Table API section for the description of all input attributes and output events.

<iw-table
  [rows]="rows"
  [columnsConfig]="columnsConfig"
  [visibleColumns]="visibleColumns"
  rowsSortingMode="external"
  initialSortColumn="firstName"
  (rowClick)="onAction($event)"
  (sortColumnInit)="onAction($event)"
  (sortColumn)="onAction($event)"
  (addingColumn)="onAction($event)"
  (addColumn)="onAction($event)"
  (removeColumn)="onAction($event)"
  (visibleColumnsChange)="onAction($event)"
  >
</iw-table>

• Activate extensions

<iw-table [rows]="paginatedRows" [columnsConfig]="columnsConfig" rowsSortingMode="external">
</iw-table>
<iw-pagination #p [totalItems]="rows.length" (pageChange)="onPageChange(p.pageStart, p.pageEnd)" ></iw-pagination>

• Customize with your templates while using handy utilities and subcomponents. Here a custom template for body rows is defined. So that we can make table rows sortable (with directive iwSortableItem), and we use application-specific component to modify the look of a specific cell.

<iw-table
  [bodyRowTemplate]="bodyRowTemplate"
  [columnsConfig]="columnsConfig"
  [rows]="rows"
  #tableComponent>
  <ng-template #bodyRowTemplate let-row let-i="index">
    <tr iwSortableItem>
      <ng-template ngFor let-columnName [ngForOf]="tableComponent.visibleColumns">
        <td
          [class]="isCustomField(columnName)"
          *ngIf="!isCustomField(columnName)"
          iw-td
          [column]="tableComponent.columnsLookup[columnName]"
          [row]="row">
        </td>
        <td *ngIf="isCustomField(columnName)">
          <iw-studies-cell
            [row]="row"
            [column]="tableComponent.columnsLookup['studies']">
        </iw-studies-cell>
        </td>
      </ng-template>
      <td *ngIf="tableComponent.changeColumnVisibility"></td>
    </tr>
  </ng-template>
</iw-table>

Table API: Inputs

• rows Data to be displayed in the table rows. Type: Row. The only required input.
• columnsConfig Configuration of a table. Type?: ColumnConfig[].
• visibleColumns Ids of initially visible columns in a table. Type?: string[]. Two-way data binding.
• reorderingEnabled Enable/Disable drag&drop reordering of columns. Type: boolean.
• changeColumnVisibility Enable/Disable user to select which columns are visible. Type: boolean.
• rowsSortingMode By default, table rows are sorted client-side. You can use the external mode for server-side sorting. Lastly, the sorting of rows can be disabled completely (no sorting icons). Type: 'default' | 'external' | 'disabled'.
• initialSortColumn Set column to be sorted on initialization. Optionally put plus or minus sign to specify the sort direction. Type: string.
• bodyRowTemplate Specify a template to render for each body row.
• headerRowTemplate Specify a template to render for table header row.
• tableTemplate Specify a custom template for the whole table.

Table API: Output events:

• addColumn A column was added by a user. Event data contain column id. Type: AddColumnAtPositionEvent
• removeColumn A column was removed by a user. Event data contain column id. Type: RemoveColumnEvent
• sortColumn A column was sorted by a user. Type: SortColumnEvent
• addingColumn A column is being added at a specific position. Type: AddingColumnEvent
• toggleSubfield Triggered when a visibility for a subfield is changed. Type: ToggleSubfieldEvent
• visibleColumnsChange This event is trigged whenever a column is added/removed or the order changed.
• rowClick Body row was clicked. Event data is row index. Type: RowClickEvent

Subcomponents

• HeaderRowComponent
  • ThComponent
  • AddColumnComponent
• Tbodyomponent
  • TdComponent

Licence

MIT