## 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
Follow the 3 steps below:
1. Npm
```sh
npm install ng2-alfresco-datatable --save
```
2. Html
Include these dependencies in your index.html page:
```html
```
3. SystemJs
Add the following components to your systemjs.config.js file:
- ng2-translate
- alfresco-js-api
- ng2-alfresco-core
- ng2-alfresco-datatable
Please refer to the following example file: [systemjs.config.js](demo/systemjs
.config.js) .
## Basic usage example
Usage example of this component :
**my.component.ts**
```ts
import { NgModule, Component } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { CoreModule } from 'ng2-alfresco-core';
import { DataTableModule } from 'ng2-alfresco-datatable';
import { ObjectDataTableAdapter } from 'ng2-alfresco-datatable';
import { Component } from '@angular/core';
import { CONTEXT_MENU_DIRECTIVES, CONTEXT_MENU_PROVIDERS } from 'ng2-alfresco-core';
import { ALFRESCO_DATATABLE_DIRECTIVES, ObjectDataTableAdapter } from 'ng2-alfresco-datatable';
@Component({
selector: 'alfresco-app-demo',
template: ``,
directives: [ALFRESCO_DATATABLE_DIRECTIVES, CONTEXT_MENU_DIRECTIVES],
providers: [CONTEXT_MENU_PROVIDERS]
})
export class DataTableDemo {
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
}
]
);
}
}
@NgModule({
imports: [
BrowserModule,
CoreModule.forRoot(),
DataTableModule
],
declarations: [DataTableDemo],
bootstrap: [DataTableDemo]
})
export class AppModule {
}
platformBrowserDynamic().bootstrapModule(AppModule);
```
### 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 |
| `fallbackThubnail` | string | | Fallback image for row ehre thubnail is missing|
### 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 {
generateSchema(row: DataRow): col: DataColumn;
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
}
]
);
```
## Generate schema
Is possible to auto generate your schema if you have only the data row
```ts
let data = [
{ id: 2, name: 'abs' },
{ id: 1, name: 'xyz' }
];
let schema = ObjectDataTableAdapter.generateSchema(data);
/*Auto generated schema value:
[
{
type: 'text',
key: 'id',
title: 'Id',
sortable: false
},
{
type: 'text',
key: 'name',
title: 'Name',
sortable: false
}
]
*/
```
## 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
```
## Demo
If you want have a demo of how the component works, please check the demo folder :
```sh
cd demo
npm install
npm start
```
## NPM scripts
| Command | Description |
| --- | --- |
| npm run build | Build component |
| npm run build:w | Build component and keep watching the changes |
| npm run test | Run unit tests in the console |
| npm run test-browser | Run unit tests in the browser
| npm run coverage | Run unit tests and display code coverage report |
## License
[Apache Version 2.0](https://github.com/Alfresco/alfresco-ng2-components/blob/master/LICENSE)
