inteligr8/alfresco-ng2-components
1
0
Fork 0
mirror of https://github.com/Alfresco/alfresco-ng2-components.git synced 2025-05-12 17:04:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

[ADF-1549] Added doc files for Datatable library (#2348)

Browse Source
This commit is contained in:
Andy Stark 2017-09-18 20:04:00 +01:00 committed by Eugenio Romano
parent 1c6866f7d1
commit c76e13de4c
9 changed files with 600 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docIndex.md
View File

@ -321,6 +321,7 @@ for more information about installing and using the source code.
- [Accordion component](docs/accordion.component.md)
- [Context menu directive](docs/context-menu.directive.md)
- [Data column component](docs/data-column.component.md)
- [Pagination component](docs/pagination.component.md)
- [Toolbar component](docs/toolbar.component.md)
- [Card view component](docs/card-view.component.md)
- [Node permission directive](docs/node-permission.directive.md)
@ -344,7 +345,6 @@ for more information about installing and using the source code.
- [Mdl menu directive](ng2-components/ng2-alfresco-core/src/components/material/mdl-menu.directive.ts)
- [Mdl textfield directive](ng2-components/ng2-alfresco-core/src/components/material/mdl-textfield.directive.ts)
- [Mdl upgrade element directive](ng2-components/ng2-alfresco-core/src/components/material/mdl-upgrade-element.directive.ts)
- [Pagination component](ng2-components/ng2-alfresco-core/src/components/pagination/pagination.component.ts)
- [Toolbar divider component](ng2-components/ng2-alfresco-core/src/components/toolbar/toolbar-divider.component.ts)
- [Toolbar title component](ng2-components/ng2-alfresco-core/src/components/toolbar/toolbar-title.component.ts)
- [Card view content proxy directive](ng2-components/ng2-alfresco-core/src/components/view/card-view-content-proxy.directive.ts)
@ -394,11 +394,10 @@ Contains the Datatable component and other related items. See the library's
[README file](ng2-components/ng2-alfresco-datatable/README.md)
for more information about installing and using the source code.
<!-- xxxng2-alfresco-datatable start -->
<!-- ng2-alfresco-datatable start -->
**Documented**
- [Datatable component](ng2-components/ng2-alfresco-datatable/README.md)
- [Pagination component](ng2-components/ng2-alfresco-datatable/README.md)
- [Datatable component](docs/datatable.component.md)
**Undocumented**

BIN
docassets/images/adf-empty-list.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 120 KiB

BIN
docassets/images/basic.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
docassets/images/datatable-actions-console.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

BIN
docassets/images/datatable-actions-ui.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 102 KiB

BIN
docassets/images/datatable-demo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
docassets/images/datatable-dom-events.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 133 KiB

538
docs/datatable.component.md Normal file
View File

@ -0,0 +1,538 @@
# DataTable component
Displays data as a table with customizable columns and presentation.
![DataTable demo](../docassets/images/datatable-demo.png)
See it live: [DataTable Quickstart](https://embed.plnkr.co/80qr4YFBeHjLMdAV0F6l/)
<!-- markdown-toc start - Don't edit this section. npm run toc to generate it-->
<!-- toc -->
- [Basic usage](#basic-usage)
* [Properties](#properties)
* [Events](#events)
- [Details](#details)
* [Customizing columns](#customizing-columns)
* [DataTable DOM Events](#datatable-dom-events)
* [Custom Empty content template](#custom-empty-content-template)
* [Loading content template](#loading-content-template)
* [Events](#events-1)
+ [rowClick event](#rowclick-event)
+ [rowDblClick event](#rowdblclick-event)
+ [showRowContextMenu event](#showrowcontextmenu-event)
+ [showRowActionsMenu event](#showrowactionsmenu-event)
+ [executeRowAction event](#executerowaction-event)
* [Data sources](#data-sources)
+ [Generate schema](#generate-schema)
<!-- tocstop -->
<!-- markdown-toc end -->
## Basic usage
**app.component.html**
```html
<adf-datatable
[data]="data">
</adf-datatable>
```
**app.component.ts**
```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:
```html
<adf-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>
</adf-datatable>
```
```ts
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'
}
]
);
}
}
```
### Properties
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| selectionMode | string | 'single' | Row selection mode. Can be none, `single` or `multiple`. For `multiple` mode you can use Cmd (macOS) or Ctrl (Win) modifier key to toggle selection for multiple rows. |
| rowStyle | string | | The inline style to apply to every row, see [NgStyle](https://angular.io/docs/ts/latest/api/common/index/NgStyle-directive.html) docs for more details and usage examples |
| rowStyleClass | string | | The CSS class to apply to every row |
| data | DataTableAdapter | instance of **ObjectDataTableAdapter** | data source |
| rows | Object[] | [] | The rows that the datatable should show |
| multiselect | boolean | false | Toggles multiple row selection, renders checkboxes at the beginning of each row |
| actions | boolean | false | Toggles data actions column |
| actionsPosition | string (left\|right) | right | Position of the actions dropdown menu. |
| fallbackThumbnail | string | | Fallback image for row where thumbnail is missing|
| contextMenu | boolean | false | Toggles custom context menu for the component |
| allowDropFiles | boolean | false | Toggle file drop support for rows (see **ng2-alfresco-core/UploadDirective** for more details) |
| loading | boolean | false | Flag that indicates if the datatable is in loading state and needs to show the loading template. Read the documentation above to see how to configure a loading template |
| showHeader | boolean | true | Toggles header visibility |
| selection | DataRow[] | [] | Contains selected rows |
### 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 |
## Details
### Customizing columns
You can define custom HTML templates for columns and also add tooltips, automatic column title translation and other features. See the DataColumn component page for more information.
### DataTable DOM Events
Below are the DOM events raised by DataTable component.
These events bubble up the component tree and can be handled by any parent component.
| Name | Description |
| --- | --- |
| row-click | Raised when user clicks a row |
| row-dblclick | Raised when user double-clicks a row |
| row-select | Raised after user selects a row |
| row-unselect | Raised after user unselects a row |
For example:
```html
<root-component (row-click)="onRowClick($event)">
<child-component>
<adf-datatable></adf-datatable>
</child-component>
</root-component>
```
```ts
onRowClick(event) {
console.log(event);
}
```
![](../docassets/images/datatable-dom-events.png)
### Custom Empty content template
You can add a template that will be shown when there are no results in your datatable:
```html
<adf-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>
</adf-datatable>
```
You can use the empty list component if you want to show the default ADF empty template.
You can use any HTML layout or Angular component as a content of the empty template section by using the special `<adf-empty-list-header>, <adf-empty-list-body>, <adf-empty-list-footer>` elements:
```html
<adf-datatable
[data]="data"
[actions]="contentActions"
[multiselect]="multiselect"
(showRowContextMenu)="onShowRowContextMenu($event)"
(showRowActionsMenu)="onShowRowActionsMenu($event)"
(executeRowAction)="onExecuteRowAction($event)"
(rowClick)="onRowClick($event)"
(rowDblClick)="onRowDblClick($event)">
<adf-empty-list>
<adf-empty-list-header>"'My custom Header'"</adf-empty-list-header>
<adf-empty-list-body>"'My custom body'"</adf-empty-list-body>
<adf-empty-list-footer>"'My custom footer'"</adf-empty-list-footer>
<ng-content>"'HTML Layout'"</ng-content>
</adf-empty-list>
</adf-datatable>
```
| Name | Type | Default | Description
| --- | --- | --- | --- |
| emptyListImageUrl | String | empty_doc_lib.svg | The default image used as background |
| emptyMsg | String | This list is empty | The default title message |
| dragDropMsg | String | Drag and drop | The default drag and drop message |
| additionalMsg | String | Drag and drop | The default additional message |
![](../docassets/images/adf-empty-list.png)
### Loading content template
You can add a template that will be shown during the loading of your data:
```html
<adf-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>
</adf-datatable>
```
```js
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
### Events
#### rowClick event
Emitted when user clicks a row.
Event properties:
```ts
sender: any // DataTable instance
value: DataRow, // row clicked
event: Event // original HTML DOM event
```
Handler example:
```ts
onRowClicked(event: DataRowEvent) {
console.log(event.value);
}
```
This event is cancellable, you can use `event.preventDefault()` to prevent default behaviour.
#### rowDblClick event
Emitted when user double-clicks a row.
Event properties:
```ts
sender: any // DataTable instance
value: DataRow, // row clicked
event: Event // original HTML DOM event
```
Handler example:
```ts
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:
```ts
value: {
row: DataRow,
col: DataColumn,
actions: []
}
```
Handler example:
```ts
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.
See the [ContextMenu](https://www.npmjs.com/package/ng2-alfresco-core)
documentation for more details on context actions format and behaviour.
#### showRowActionsMenu event
Emitted before actions menu is displayed for a row.
Requires `actions` property to be set to `true`.
Event properties:
```ts
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 a row action is executed by the 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.
```html
<adf-datatable
[data]="data"
[multiselect]="multiselect"
[actions]="true"
(showRowActionsMenu)="onShowRowActionsMenu($event)"
(executeRowAction)="onExecuteRowAction($event)">
</adf-datatable>
```
```ts
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}`);
}
```
![](../docassets/images/datatable-actions-ui.png)
![](../docassets/images/datatable-actions-console.png)
Developers are allowed to use 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:
```ts
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;
isDropTarget?: boolean;
hasValue(key: string): boolean;
getValue(key: string): any;
cssClass?: string;
}
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](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-alfresco-datatable/src/data/object-datatable-adapter.ts) out-of-the-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
It 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
}
]
*/
```

59
docs/pagination.component.md Normal file
View File

@ -0,0 +1,59 @@
# Pagination Component
Adds pagination to the component it is used with.
![](../docassets/images/basic.png)
<!-- markdown-toc start - Don't edit this section. npm run toc to generate it-->
<!-- toc -->
- [Basic Usage](#basic-usage)
* [Properties](#properties)
* [Events](#events)
- [Details](#details)
<!-- tocstop -->
<!-- markdown-toc end -->
## Basic Usage
```html
<adf-pagination
[pagination]="pagination"
[supportedPageSizes]="sizes"
(change)="onChange($event)"
(nextPage)="onNextPage($event)"
(prevPage)="onPreviousPage($event)"
(changePageSize)="onChangePageSize($event)"
(changePageNumber)="onChangePageNumber($event)">
</adf-pagination>
```
### Properties
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| pagination | Pagination | | Pagination object |
| supportedPageSizes | Array&lt;number&gt; | [ 25, 50, 100 ] | An array of page sizes |
### Events
| Name | Type | Description |
| --- | --- | --- |
| change | EventEmitter&lt;PaginationQueryParams&gt; | Triggered for any action in pagination |
| nextPage | EventEmitter&lt;Pagination&gt; | Triggered on next page action |
| prevPage | EventEmitter&lt;Pagination&gt; | Triggered on previous page action |
| changePageSize | EventEmitter&lt;Pagination&gt; | Triggered on page size change action |
| changePageNumber | EventEmitter&lt;Pagination&gt; | Triggered on page change action |
## Details
The pagination object is a generic component to paginate component. The Alfresco API are paginated and return a Pagination object. You can use the pagination object to feed the pagination component and then listen to the event which returns the current pagination and query again the API with the options chosen by the user.
Each event helps to detect the certain action that user have made using the component.
For `change` event, a [PaginationQueryParams](https://github.com/Alfresco/alfresco-ng2-components/blob/development/ng2-components/ng2-alfresco-core/src/components/pagination/pagination-query-params.interface.ts) (including the query params supported by the REST API, `skipCount` and `maxItems`) is returned.
For all events other than `change`, a new Pagination object is returned as in the folowing example, with updated properties to be used to query further.