inteligr8/alfresco-ng2-components
1
0
Fork 0
mirror of https://github.com/Alfresco/alfresco-ng2-components.git synced 2025-07-24 17:32:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

#393 readme updates

Browse Source
This commit is contained in:
Denys Vuika
2016-07-11 15:30:21 +01:00
parent 491a9ab57b
commit 0a9cc60016
3 changed files with 261 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
ng2-components/ng2-alfresco-datatable/README.md
View File

@@ -28,16 +28,49 @@
</a> </a>
</p> </p>
### Node ## Prerequisites
To correctly use this component check that on your machine is running Node version 5.0.0 or higher.
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 ## Install
```sh ```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
<!-- Google Material Design Lite -->
<link rel="stylesheet" href="node_modules/material-design-lite/material.min.css">
<script src="node_modules/material-design-lite/material.min.js"></script>
<link rel="stylesheet" href="node_modules/material-design-icons/iconfont/material-icons.css">
```
## Basic usage example
**my.component.html**
```html ```html
<alfresco-datatable <alfresco-datatable
@@ -45,7 +78,7 @@ npm install --save ng2-alfresco-datatable material-design-lite material-design-i
</alfresco-datatable> </alfresco-datatable>
``` ```
Example of an App that declares the file viewer component : **my.component.ts**
```ts ```ts
import { Component } from '@angular/core'; import { Component } from '@angular/core';
@@ -56,7 +89,7 @@ import {
@Component({ @Component({
selector: 'my-view', selector: 'my-view',
template: '<YOUR TEMPLATE>', templateUrl: './my.component.html',
directives: [ALFRESCO_DATATABLE_DIRECTIVES] directives: [ALFRESCO_DATATABLE_DIRECTIVES]
}) })
export class MyView { export class MyView {
@@ -71,13 +104,23 @@ export class MyView {
], ],
// schema // 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) ![DataTable demo](docs/assets/datatable-demo.png)
@@ -86,26 +129,182 @@ export class MyView {
| Name | Type | Default | Description | Name | Type | Default | Description
| --- | --- | --- | --- | | --- | --- | --- | --- |
| data | DataTableAdapter | empty **ObjectDataTableAdapter** | data source | | data | DataTableAdapter | instance of **ObjectDataTableAdapter** | data source |
| multiselect | boolean | false | toggle multiple row selection, renders checkboxes at the beginning of each row | | multiselect | boolean | false | Toggles multiple row selection, renders checkboxes at the beginning of each row |
| actions | boolean | false | toggle data actions column | | actions | boolean | false | Toggles data actions column |
### Events ### Events
| Name | Description | Name | Description
| --- | --- | | --- | --- |
| rowClick | emitted when user clicks the row | | rowClick | Emitted when user clicks the row |
| rowDblClick | emitted when user double-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
<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>
<template>
<h1>Sorry, no content</h1>
</template>
</no-content-template>
</alfresco-datatable>
```
#### 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 ## Data sources
DataTable component gets data by means of data adapter. DataTable component gets data by means of data adapter.
It is possible having data retrieved from different kinds of sources by implementing It is possible having data retrieved from different kinds of sources by implementing
a custom `DataTableAdapter`: a custom `DataTableAdapter` using the following interfaces:
```ts ```ts
interface DataTableAdapter { interface DataTableAdapter {
getRows(): Array<DataRow>; getRows(): Array<DataRow>;
setRows(rows: Array<DataRow>): void; setRows(rows: Array<DataRow>): void;
getColumns(): Array<DataColumn>; getColumns(): Array<DataColumn>;
@@ -114,12 +313,28 @@ interface DataTableAdapter {
getSorting(): DataSorting; getSorting(): DataSorting;
setSorting(sorting: DataSorting): void; setSorting(sorting: DataSorting): void;
sort(key?: string, direction?: string): 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 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.
that binds to object arrays and turns object fields into columns: This is a simple data adapter implementation that binds to object arrays
and turns object fields into columns:
```ts ```ts
let data = new ObjectDataTableAdapter( let data = new ObjectDataTableAdapter(
@@ -130,8 +345,18 @@ let data = new ObjectDataTableAdapter(
], ],
// schema // 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 npm run build
``` ```
##Build the files and keep watching for changes ### Build the files and keep watching for changes
```sh ```sh
$ npm run build:w $ npm run build:w
``` ```
## Running unit tests ### Running unit tests
```sh ```sh
npm test npm test
``` ```
## Running unit tests in browser ### Running unit tests in browser
```sh ```sh
npm test-browser 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 This task rebuilds all the code, runs tslint, license checks and other quality check tools
before performing unit testing. before performing unit testing.
## Code coverage ### Code coverage
```sh ```sh
npm run coverage npm run coverage

2
ng2-components/ng2-alfresco-datatable/src/components/datatable.component.ts
View File

@@ -94,7 +94,7 @@ export class DataTableComponent implements OnInit, AfterViewChecked {
} }
} }
onRowClick(row: DataRow, e?) { onRowClick(row: DataRow, e?: Event) {
if (e) { if (e) {
e.preventDefault(); e.preventDefault();
} }

22
ng2-components/ng2-alfresco-documentlist/README.md
View File

@@ -39,12 +39,6 @@ necessary configuration, see this [page](https://github.com/Alfresco/alfresco-ng
npm install --save ng2-alfresco-documentlist 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 ### Dependencies
Add the following dependency to your index.html: 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 | | 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 | | navigationMode | string (click\|dblclick) | dblclick | User interaction for folder navigation or file preview |
| thumbnails | boolean | false | Show document thumbnails rather than icons | | thumbnails | boolean | false | Show document thumbnails rather than icons |
| multiselect | boolean | false | Toggle multiselect mode | | multiselect | boolean | false | Toggles multiselect mode |
| contentActions | boolean | false | Toggle content actions for each row | | contentActions | boolean | false | Toggles content actions for each row |
| contextMenuActions | boolean | false | Toggle context menus for each row | | contextMenuActions | boolean | false | Toggles context menus for each row |
### Events ### Events
| Name | Description | | Name | Description |
| --- | --- | | --- | --- |
| nodeClick | Triggered when user clicks the node | | nodeClick | Emitted when user clicks the node |
| nodeDblClick | Triggered when user double-clicks the node | | nodeDblClick | Emitted when user double-clicks the node |
| folderChange | Triggered upon display folder changed | | folderChange | Emitted upon display folder changed |
| preview | Triggered when document preview is requested either with single or double click | | preview | Emitted when document preview is requested either with single or double click |
_For a complete example source code please refer to _For a complete example source code please refer to