From 0a9cc6001674d7d41f9c1d152118d5c327eb9589 Mon Sep 17 00:00:00 2001 From: Denys Vuika Date: Mon, 11 Jul 2016 15:30:21 +0100 Subject: [PATCH] #393 readme updates --- .../ng2-alfresco-datatable/README.md | 279 ++++++++++++++++-- .../src/components/datatable.component.ts | 2 +- .../ng2-alfresco-documentlist/README.md | 22 +- 3 files changed, 261 insertions(+), 42 deletions(-) diff --git a/ng2-components/ng2-alfresco-datatable/README.md b/ng2-components/ng2-alfresco-datatable/README.md index 0ac35ff0fa..f591e07401 100644 --- a/ng2-components/ng2-alfresco-datatable/README.md +++ b/ng2-components/ng2-alfresco-datatable/README.md @@ -28,16 +28,49 @@

-### Node -To correctly use this component check that on your machine is running Node version 5.0.0 or higher. +## 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 material-design-lite material-design-icons +npm install --save ng2-alfresco-datatable ``` -## Basic usage +### 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 ``` -Example of an App that declares the file viewer component : +**my.component.ts** ```ts import { Component } from '@angular/core'; @@ -56,7 +89,7 @@ import { @Component({ selector: 'my-view', - template: '', + templateUrl: './my.component.html', directives: [ALFRESCO_DATATABLE_DIRECTIVES] }) export class MyView { @@ -71,13 +104,23 @@ export class MyView { ], // schema [ - {type: 'text', key: 'id', title: 'Id', sortable: true}, - {type: 'text', key: 'name', title: 'Name', cssClass: 'full-width name-column', sortable: true} + { + type: 'text', + key: 'id', + title: 'Id', + sortable: true + }, + { + type: 'text', + key: 'name', + title: 'Name', + cssClass: 'full-width', + sortable: true + } ] ); } } - ``` ![DataTable demo](docs/assets/datatable-demo.png) @@ -86,26 +129,182 @@ export class MyView { | Name | Type | Default | Description | --- | --- | --- | --- | -| data | DataTableAdapter | empty **ObjectDataTableAdapter** | data source | -| multiselect | boolean | false | toggle multiple row selection, renders checkboxes at the beginning of each row | -| actions | boolean | false | toggle data actions column | +| 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 | emitted when user clicks the row | -| rowDblClick | emitted when user double-clicks the row | +| rowClick | Emitted when user clicks the row | +| rowDblClick | Emitted when user double-clicks the row | +| showRowContextMenu | Emitted before context menu is displayed for a row | +| showRowActionsMenu | Emitted before actions menu is displayed for a row | +| executeRowAction | Emitted when row action is executed by user | + + +**Advanced usage example** + +```html + + + + + +``` + +#### 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`: +a custom `DataTableAdapter` using the following interfaces: ```ts interface DataTableAdapter { - getRows(): Array; setRows(rows: Array): void; getColumns(): Array; @@ -114,12 +313,28 @@ interface DataTableAdapter { 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 ships `ObjectDataTableAdapter` out-of-box. This is a simple data adapter -that binds to object arrays and turns object fields into columns: +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( @@ -130,8 +345,18 @@ let data = new ObjectDataTableAdapter( ], // schema [ - {type: 'text', key: 'id', title: 'Id', sortable: true}, - {type: 'text', key: 'name', title: 'Name', sortable: true} + { + type: 'text', + key: 'id', + title: 'Id', + sortable: true + }, + { + type: 'text', + key: 'name', + title: 'Name', + sortable: true + } ] ); ``` @@ -145,19 +370,19 @@ npm install npm run build ``` -##Build the files and keep watching for changes +### Build the files and keep watching for changes - ```sh - $ npm run build:w - ``` +```sh +$ npm run build:w +``` -## Running unit tests +### Running unit tests ```sh npm test ``` -## Running unit tests in browser +### Running unit tests in browser ```sh npm test-browser @@ -166,7 +391,7 @@ npm test-browser This task rebuilds all the code, runs tslint, license checks and other quality check tools before performing unit testing. -## Code coverage +### Code coverage ```sh npm run coverage diff --git a/ng2-components/ng2-alfresco-datatable/src/components/datatable.component.ts b/ng2-components/ng2-alfresco-datatable/src/components/datatable.component.ts index e082904987..4d9b47b242 100644 --- a/ng2-components/ng2-alfresco-datatable/src/components/datatable.component.ts +++ b/ng2-components/ng2-alfresco-datatable/src/components/datatable.component.ts @@ -94,7 +94,7 @@ export class DataTableComponent implements OnInit, AfterViewChecked { } } - onRowClick(row: DataRow, e?) { + onRowClick(row: DataRow, e?: Event) { if (e) { e.preventDefault(); } diff --git a/ng2-components/ng2-alfresco-documentlist/README.md b/ng2-components/ng2-alfresco-documentlist/README.md index f92d59423e..eeff0ed589 100644 --- a/ng2-components/ng2-alfresco-documentlist/README.md +++ b/ng2-components/ng2-alfresco-documentlist/README.md @@ -39,12 +39,6 @@ necessary configuration, see this [page](https://github.com/Alfresco/alfresco-ng npm install --save ng2-alfresco-documentlist ``` -To correctly use this component check that on your machine is running Node version 5.0.0 or higher. - -```sh -node -v -``` - ### Dependencies Add the following dependency to your index.html: @@ -97,21 +91,21 @@ Also make sure you include these dependencies in your `index.html` file: | Name | Type | Default | Description | | --- | --- | --- | --- | -| navigate | boolean | true | Toggle navigation to folder content or file preview | +| navigate | boolean | true | Toggles navigation to folder content or file preview | | navigationMode | string (click\|dblclick) | dblclick | User interaction for folder navigation or file preview | | thumbnails | boolean | false | Show document thumbnails rather than icons | -| multiselect | boolean | false | Toggle multiselect mode | -| contentActions | boolean | false | Toggle content actions for each row | -| contextMenuActions | boolean | false | Toggle context menus for each row | +| multiselect | boolean | false | Toggles multiselect mode | +| contentActions | boolean | false | Toggles content actions for each row | +| contextMenuActions | boolean | false | Toggles context menus for each row | ### Events | Name | Description | | --- | --- | -| nodeClick | Triggered when user clicks the node | -| nodeDblClick | Triggered when user double-clicks the node | -| folderChange | Triggered upon display folder changed | -| preview | Triggered when document preview is requested either with single or double click | +| nodeClick | Emitted when user clicks the node | +| nodeDblClick | Emitted when user double-clicks the node | +| folderChange | Emitted upon display folder changed | +| preview | Emitted when document preview is requested either with single or double click | _For a complete example source code please refer to