ng2-alfresco-datatable v1.9.0

DataTable Component

• Prerequisites
• Install
• Basic usage
  • DataTable Properties
  • DataColumn Properties
  • DataTable Events
  • DataTable DOM Events
  • Empty content template
  • Loading content template
  • Column Templates
  • Events
    • rowClick event
    • rowDblClick event
    • showRowContextMenu event
    • showRowActionsMenu event
    • executeRowAction event
• Data sources
• Generate schema

• Pagination Component
  • Properties
  • Events
  • Build from sources
  • NPM scripts
  • Demo
  • License

See it live: DataTable Quickstart

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.

If you plan using this component with projects generated by Angular CLI, please refer to the following article: Using ADF with Angular CLI

Install

npm install ng2-alfresco-datatable

Basic usage

app.component.html

<alfresco-datatable 
    [data]="data">
</alfresco-datatable>

app.component.ts

import { ObjectDataTableAdapter }  from 'ng2-alfresco-datatable';

@Component({...})
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
                }
            ]
        );
    }
}

You can also use HTML-based schema declaration like shown below:

<alfresco-datatable [data]="data">
    <data-columns>
        <data-column key="icon" type="image" [sortable]="false"></data-column>
        <data-column key="id" title="Id"></data-column>
        <data-column key="createdOn" title="Created"></data-column>
        <data-column key="name" title="Name" class="full-width name-column"></data-column>
        <data-column key="createdBy.name" title="Created By"></data-column>
    </data-columns>
</alfresco-datatable>

import { ObjectDataTableAdapter } from 'ng2-alfresco-datatable';

@Component({...})
export class DataTableDemo {
    data: ObjectDataTableAdapter;

    constructor() {
        this.data = new ObjectDataTableAdapter(
            // data
            [
                {
                    id: 1, 
                    name: 'Name 1', 
                    createdBy : { name: 'user'}, 
                    createdOn: 123, 
                    icon: 'http://example.com/img.png'
                },
                {
                    id: 2, 
                    name: 'Name 2', 
                    createdBy : { name: 'user 2'}, 
                    createdOn: 123, 
                    icon: 'http://example.com/img.png'
                }
            ]
        );
    }
}

DataTable Properties

DataColumn Properties

Here's the list of available properties you can define for a Data Column definition.

DataTable Events

DataTable DOM Events

Below are the DOM events raised by DataTable component.

These events are bubbled up the element tree and can be subscribed to from within parent components.

<root-component (row-click)="onRowClick($event)">
    <child-component>
        <alfresco-datatable></alfresco-datatable>
    </child-component>
</root-component>

onRowClick(event) {
    console.log(event);
}

Empty content template

You can add a template that will be showed when there are no result in your datatable:

<alfresco-datatable
    [data]="data"
    [actions]="contentActions"
    [multiselect]="multiselect"
    (showRowContextMenu)="onShowRowContextMenu($event)"
    (showRowActionsMenu)="onShowRowActionsMenu($event)"
    (executeRowAction)="onExecuteRowAction($event)"
    (rowClick)="onRowClick($event)"
    (rowDblClick)="onRowDblClick($event)">
    
    
        <no-content-template>
            <!--Add your custom empty template here-->
            <ng-template>
                <h1>Sorry, no content</h1>
            </ng-template>
        </no-content-template>
        
</alfresco-datatable>

Loading content template

You can add a template that will be showed during the loading of your data:

<alfresco-datatable
    [data]="data"
    [actions]="contentActions"
    [multiselect]="multiselect"
    [loading]=isLoading()"
    (showRowContextMenu)="onShowRowContextMenu($event)"
    (showRowActionsMenu)="onShowRowActionsMenu($event)"
    (executeRowAction)="onExecuteRowAction($event)"
    (rowClick)="onRowClick($event)"
    (rowDblClick)="onRowDblClick($event)">
    
        <loading-content-template>
            <ng-template>
               <!--Add your custom loading template here-->
                <md-progress-spinner
                    class="adf-document-list-loading-margin"
                    [color]="'primary'"
                    [mode]="'indeterminate'">
                </md-progress-spinner>
            </ng-template>
        </loading-content-template>
        
</alfresco-datatable>

    isLoading(): boolean {
        //your custom logic to identify if you are in a loading state 
    }

Note: the <loading-content-template> and <no-content-template> can be used together

Column Templates

It is possible assigning a custom column template like the following:

<alfresco-datatable ...>
    <data-columns>
        <data-column title="Version" key="properties.cm:versionLabel">
            <template let-value="value">
                <span>V. {{value}}</span>
            </template>
        </data-column>
    </data-columns>
</alfresco-datatable>

Example above shows access to the underlying cell value by binding value property to the underlying context value:

<template let-value="value">

Alternatively you can get access to the entire data context using the following syntax:

<template let-entry="$implicit">

That means you are going to create local variable entry that is bound to the data context via Angular's special $implicit keyword.

<template let-entry="$implicit">
    <span>V. {{entry.data.getValue(entry.row, entry.col)}}</span>
</template>

In the second case entry variable is holding a reference to the following data context:

{
    data: DataTableAdapter,
    row: DataRow,
    col: DataColumn
}

Events

rowClick event

This event is emitted when user clicks the row.

Event properties:

sender: any     // DataTable instance 
value: DataRow, // row clicked
event: Event    // original HTML DOM event

Handler example:

onRowClicked(event: DataRowEvent) {
    console.log(event.value);
}

This event is cancellable, you can use event.preventDefault() to prevent default behaviour.

rowDblClick event

This event is emitted when user double-clicks the row.

Event properties:

sender: any     // DataTable instance 
value: DataRow, // row clicked
event: Event    // original HTML DOM event

Handler example:

onRowDblClicked(event: DataRowEvent) {
    console.log(event.value);
}

This event is cancellable, you can use event.preventDefault() to prevent default behaviour.

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:

value: {
    row: DataRow,
    col: DataColumn,
    actions: []
}

Handler example:

onShowRowContextMenu(event: DataCellEvent) {
    event.value.actions = [
        { ... },
        { ... }
    ]
}

This event is cancellable, you can use event.preventDefault() to prevent default behaviour.

DataTable will automatically render provided menu items.

Please refer to ContextMenu 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.

Event properties:

value: {
    row: DataRow,
    action: any
}

Note that DataTable itself does not populate action menu items, you can provide all necessary content via handler.

This event is cancellable, you can use event.preventDefault() to prevent default behaviour.

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.

<alfresco-datatable
    [data]="data"
    [multiselect]="multiselect"
    [actions]="true"
    (showRowActionsMenu)="onShowRowActionsMenu($event)"
    (executeRowAction)="onExecuteRowAction($event)">
</alfresco-datatable>

import { DataCellEvent, DataRowActionEvent } from 'ng2-alfresco-datatable';

onShowRowActionsMenu(event: DataCellEvent) {
    let myAction = {
        title: 'Hello'
        // your custom metadata needed for onExecuteRowAction
    };
    event.value.actions = [
        myAction
    ];
}

onExecuteRowAction(event: DataRowActionEvent) {
    let args = event.value;
    console.log(args.row);
    console.log(args.action);
    window.alert(`My custom action: ${args.action.title}`);
}

Developers are allowed putting any payloads as row actions. The only requirement for the objects is having title property.

Once corresponding action is clicked in the dropdown menu DataTable invokes executeRowAction event where you can handle the process, inspect the action payload and all custom properties defined earlier, and do corresponding actions.

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:

interface DataTableAdapter {
    selectedRow: DataRow;
    getRows(): Array<DataRow>;
    setRows(rows: Array<DataRow>): void;
    getColumns(): Array<DataColumn>;
    setColumns(columns: Array<DataColumn>): 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;
    template?: TemplateRef<any>;
}

DataTable provides ObjectDataTableAdapter out-of-box. This is a simple data adapter implementation that binds to object arrays and turns object fields into columns:

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

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
    }
] 
*/

Pagination Component

The pagination object is a generic component to paginate component. The Alfresco API are paginated and returns a Pagination object. You can use the pagination object to feed the pagination component and then listen to the event which return the current pagination and query again the API with the options choose by the user.

Properties

Events

All the events carry with them the current pagination object.

Build from sources

You can build component from sources with the following commands:

npm install
npm run build

The build task rebuilds all the code, runs tslint, license checks and other quality check tools before performing unit testing.

NPM scripts

Demo

Please check the demo folder for a demo project

cd demo
npm install
npm start

License

Apache Version 2.0