## Prerequisites
Before you start using this development framework, make sure you have installed all required software and done all the
necessary configuration, see this [page](https://github.com/Alfresco/alfresco-ng2-components/blob/master/PREREQUISITES.md).
## Install
```sh
npm install --save ng2-alfresco-datatable
```
### Dependencies
You must separately install the following libraries for your application:
- [ng2-translate](https://github.com/ocombe/ng2-translate)
- [ng2-alfresco-core](https://www.npmjs.com/package/ng2-alfresco-core)
```sh
npm install --save ng2-translate ng2-alfresco-core
```
#### Material Design Lite
The style of this component is based on [material design](https://getmdl.io/), so if you want to visualize it correctly you have to add the material
design dependency to your project:
```sh
npm install --save material-design-icons material-design-lite
```
Also make sure you include these dependencies in your `index.html` file:
```html
```
## Basic usage example
**my.component.html**
```html
```
**my.component.ts**
```ts
import { Component } from '@angular/core';
import {
ALFRESCO_DATATABLE_DIRECTIVES,
ObjectDataTableAdapter
} from 'ng2-alfresco-datatable';
@Component({
selector: 'my-view',
templateUrl: './my.component.html',
directives: [ALFRESCO_DATATABLE_DIRECTIVES]
})
export class MyView {
data: ObjectDataTableAdapter;
constructor() {
this.data = new ObjectDataTableAdapter(
// data
[
{ id: 1, name: 'Name 1' },
{ id: 2, name: 'Name 2' }
],
// schema
[
{
type: 'text',
key: 'id',
title: 'Id',
sortable: true
},
{
type: 'text',
key: 'name',
title: 'Name',
cssClass: 'full-width',
sortable: true
}
]
);
}
}
```
### Properties
| Name | Type | Default | Description
| --- | --- | --- | --- |
| data | DataTableAdapter | instance of **ObjectDataTableAdapter** | data source |
| multiselect | boolean | false | Toggles multiple row selection, renders checkboxes at the beginning of each row |
| actions | boolean | false | Toggles data actions column |
### Events
| Name | Description
| --- | --- |
| [rowClick](#rowclick-event) | Emitted when user clicks the row |
| [rowDblClick](#rowdblclick-event) | Emitted when user double-clicks the row |
| [showRowContextMenu](#showrowcontextmenu-event) | Emitted before context menu is displayed for a row |
| [showRowActionsMenu](#showrowactionsmenu-event) | Emitted before actions menu is displayed for a row |
| [executeRowAction](#executerowaction-event) | Emitted when row action is executed by user |
**Advanced usage example**
```html
Sorry, no content
```
#### rowClick event
_This event is emitted when user clicks the row._
Event properties:
```ts
row: DataRow, // row clicked
event: Event // original HTML DOM event
```
Handler example:
```ts
onRowClicked(event) {
console.log(event.row);
}
```
#### rowDblClick event
_This event is emitted when user double-clicks the row._
Event properties:
```ts
row: DataRow, // row clicked
event: Event // original HTML DOM event
```
Handler example:
```ts
onRowDblClicked(event) {
console.log(event.row);
}
```
#### showRowContextMenu event
_Emitted before context menu is displayed for a row._
Note that DataTable itself does not populate context menu items,
you can provide all necessary content via handler.
Event properties:
```ts
args: {
row: DataRow,
col: DataColumn,
actions: []
}
```
Handler example:
```ts
onShowRowContextMenu(event) {
event.args.actions = [
{ ... },
{ ... }
]
}
```
DataTable will automatically render provided menu items.
_Please refer to [ContextMenu](https://www.npmjs.com/package/ng2-alfresco-core)
documentation for more details on context actions format and behavior._
#### showRowActionsMenu event
_Emitted before actions menu is displayed for a row.
Requires `actions` property to be set to `true`._
Note that DataTable itself does not populate action menu items,
you can provide all necessary content via handler.
Event properties:
```ts
args: {
row: DataRow,
col: DataColumn,
actions: []
}
```
Handler example:
```ts
onShowRowActionsMenu(event) {
event.args.actions = [
{ ... },
{ ... }
]
}
```
#### executeRowAction event
_Emitted when row action is executed by user._
Usually accompanies `showRowActionsMenu` event.
DataTable itself does not execute actions but provides support for external
integration. If there were actions provided with `showRowActionsMenu` event
then `executeRowAction` will be automatically executed when user clicks
corresponding menu item.
Event properties:
```ts
args: {
row: DataRow
action: any
}
```
Handler example:
```ts
onExecuteRowAction(event) {
// get event arguments
let row = event.args.row;
let action = event.args.action;
// your code to execute action
this.executeContentAction(row, action);
}
```
## Data sources
DataTable component gets data by means of data adapter.
It is possible having data retrieved from different kinds of sources by implementing
a custom `DataTableAdapter` using the following interfaces:
```ts
interface DataTableAdapter {
getRows(): Array;
setRows(rows: Array): void;
getColumns(): Array;
setColumns(columns: Array): void;
getValue(row: DataRow, col: DataColumn): any;
getSorting(): DataSorting;
setSorting(sorting: DataSorting): void;
sort(key?: string, direction?: string): void;
}
interface DataRow {
isSelected: boolean;
hasValue(key: string): boolean;
getValue(key: string): any;
}
interface DataColumn {
key: string;
type: string; // text|image|date
format?: string;
sortable?: boolean;
title?: string;
srTitle?: string;
cssClass?: string;
}
```
DataTable provides [ObjectDataTableAdapter](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-alfresco-datatable/src/data/object-datatable-adapter.ts) out-of-box.
This is a simple data adapter implementation that binds to object arrays
and turns object fields into columns:
```ts
let data = new ObjectDataTableAdapter(
// data
[
{ id: 1, name: 'Name 1' },
{ id: 2, name: 'Name 2' }
],
// schema
[
{
type: 'text',
key: 'id',
title: 'Id',
sortable: true
},
{
type: 'text',
key: 'name',
title: 'Name',
sortable: true
}
]
);
```
## Build from sources
Alternatively you can build component from sources with the following commands:
```sh
npm install
npm run build
```
### Build the files and keep watching for changes
```sh
$ npm run build:w
```
### Running unit tests
```sh
npm test
```
### Running unit tests in browser
```sh
npm test-browser
```
This task rebuilds all the code, runs tslint, license checks and other quality check tools
before performing unit testing.
### Code coverage
```sh
npm run coverage
```
