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

[ADF-1586] Updated Datatable docs (#2445)

Browse Source 
* [ADF-1586] Updates to Datatable docs

* [ADF-1586] Fixed broken link in doc index page
This commit is contained in:
Andy Stark
2017-10-06 14:10:25 +01:00
committed by Denys Vuika
parent 8289492905
commit 3cd5eafdde
8 changed files with 219 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
docs/DataTableAdapter.md Normal file
View File

@@ -0,0 +1,166 @@
# DataTableAdapter interface
Defines how table data is supplied to [DataTable](datatable.component.md)
and [Tasklist](tasklist.component.md) components.
<!-- markdown-toc start - Don't edit this section. npm run toc to generate it-->
<!-- toc -->
- [Properties](#properties)
- [Methods](#methods)
- [Details](#details)
* [Columns and rows](#columns-and-rows)
* [ObjectDataTableAdapter](#objectdatatableadapter)
- [See also](#see-also)
<!-- tocstop -->
<!-- markdown-toc end -->
## Properties
| Name | Type | Description |
| --- | --- | --- |
| selectedRow | DataRow | The data for the currently selected row. |
## Methods
`getRows(): Array<DataRow>;`<br/>
`setRows(rows: Array<DataRow>): void;`<br/>
Get/set the values for display in the table using an array of rows.
`getColumns(): Array<DataColumn>;`<br/>
`setColumns(columns: Array<DataColumn>): void;`<br/>
Get/set an array of column specifications.
`getValue(row: DataRow, col: DataColumn): any;`<br/>
Get the data value from a specific table cell.
`getSorting(): DataSorting;`
`setSorting(sorting: DataSorting): void;`
Get/set the sorting key and direction (ascending or descending).
`sort(key?: string, direction?: string): void;`
Sort the table with a specified key and direction (ascending or descending).
## Details
You can implement DataTableAdapter in your own class to display your data with the [DataTable](datatable.component.md)
and [Tasklist](tasklist.component.md) components.
This interface (along with other interfaces for column and row data) hides the details of your class from the caller, so you can store your data internally however you like. The DataTable library implements the interface in the [ObjectDataTableAdapter](#objectdatatableadapter) class which is the standard adapter for the Datatable component.
The basic idea of DataTableAdapter is that the caller can request your class to return an array of column
definition objects. Each of these objects specifies the unique key, name, type and other properties of a single column.
The caller can also request the data values for the table as an array of row objects. The caller accesses the data from a row using a `getValue` method that returns the data from a specified column. This column is identified by the unique key that was set during the column definition.
The data-hiding works the other way around when the caller needs to set data in the DataTableAdapter class - the internal
details of the caller's storage are hidden by the column and row interfaces. When the `setColumns` and `setRows` methods are
called on the adapter, it can simply query the column/row objects it receives and then store the data in its own format.
### Columns and rows
Columns are defined by the DataColumn interface:
```ts
interface DataColumn {
key: string;
type: string;
format?: string;
sortable?: boolean;
title?: string;
srTitle?: string;
cssClass?: string;
template?: TemplateRef<any>;
formatTooltip?: Function;
}
```
An array of these objects is passed to your object when the `setColumns` method is called. The `key` property is used to identify columns and so each column's key should be unique. The `type` string can have a value of 'text', 'image' or 'date'.
An array of DataRow objects is passed to your object when the `setRows` method is called:
```ts
interface DataRow {
isSelected: boolean;
isDropTarget?: boolean;
cssClass?: string;
hasValue(key: string): boolean;
getValue(key: string): any;
}
```
Each row contains a set of values. An item in the set is retrieved by passing its key (specified in the column description) to the `getValue` method. As a result, the row does not need to store its data items in any particular order or format as long as it can retrieve the right item using its key.
### ObjectDataTableAdapter
The DataTable library provides a implementation of DataTableAdapter, called
[ObjectDataTableAdapter](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-alfresco-datatable/src/data/object-datatable-adapter.ts). This is a simple adapter that binds to object arrays and turns object fields into columns:
```ts
let data = new ObjectDataTableAdapter(
// Row data
[
{ id: 1, name: 'Name 1' },
{ id: 2, name: 'Name 2' }
],
// Column schema
[
{
type: 'text',
key: 'id',
title: 'Id',
sortable: true
},
{
type: 'text',
key: 'name',
title: 'Name',
sortable: true
}
]
);
```
![DataTable demo](docassets/images/datatable-demo.png)
If you don't specify the column array then the constructor will infer the layout of the columns from
the structure of the row objects. The field names ('id' and 'name' in the example below) will be used
for both the `key` and `title` properties of the columns:
```ts
let data = [
{ id: 2, name: 'abs' },
{ id: 1, name: 'xyz' }
];
let schema = ObjectDataTableAdapter.generateSchema(data);
/*Auto generated column schema:
[
{
type: 'text',
key: 'id',
title: 'Id',
sortable: false
},
{
type: 'text',
key: 'name',
title: 'Name',
sortable: false
}
]
*/
```
<!-- Don't edit the See also section. Edit seeAlsoGraph.json and run config/generateSeeAlso.js -->
<!-- seealso start -->
## See also
- [Datatable component](datatable.component.md)
- [Tasklist component](tasklist.component.md)
<!-- seealso end -->

10
docs/data-column.component.md
View File

@@ -15,6 +15,7 @@ Defines column properties for DataTable, Tasklist, Document List and other compo
* [Styling Techniques](#styling-techniques)
+ [Custom icons for selected rows](#custom-icons-for-selected-rows)
+ [Hiding columns on small screens](#hiding-columns-on-small-screens)
- [See also](#see-also)
<!-- tocstop -->
@@ -105,9 +106,9 @@ Every cell in the DataTable component is bound to the dynamic data context conta
| Name | Type | Description |
| --- | --- | --- |
| data | [DataTableAdapter](https://github.com/Alfresco/alfresco-ng2-components/tree/master/ng2-components/ng2-alfresco-datatable#data-sources) | Data adapter instance. |
| row | [DataRow](https://github.com/Alfresco/alfresco-ng2-components/tree/master/ng2-components/ng2-alfresco-datatable#data-sources) | Current data row instance. |
| col | [DataColumn](https://github.com/Alfresco/alfresco-ng2-components/tree/master/ng2-components/ng2-alfresco-datatable#data-sources) | Current data column instance. |
| data | [DataTableAdapter](DataTableAdapter.md) | Data adapter instance. |
| row | [DataRow](DataTableAdapter.md) | Current data row instance. |
| col | [DataColumn](DataTableAdapter.md) | Current data column instance. |
You can use all three properties to gain full access to underlying data from within your custom templates.
In order to wire HTML templates with the data context you will need defining a variable that is bound to `$implicit` like shown below:
@@ -156,7 +157,8 @@ In the Example below we will prepend `Hi!` to each file and folder name in the l
</data-column>
```
In the Example below we will add the [ng2-alfresco-tag](https://www.npmjs.com/package/ng2-alfresco-tag) component is integrate in the document list.
In the Example below we will integrate the [adf-tag-node-list](tag-node-list.component.md) component
with the document list.
```html
<data-column

119
docs/datatable.component.md
View File

@@ -14,18 +14,19 @@ See it live: [DataTable Quickstart](https://embed.plnkr.co/80qr4YFBeHjLMdAV0F6l/
* [Properties](#properties)
* [Events](#events)
- [Details](#details)
* [Supplying data for the table](#supplying-data-for-the-table)
* [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)
+ [row-keyup DOM event](#row-keyup-dom-event)
+ [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)
- [See also](#see-also)
<!-- tocstop -->
@@ -154,6 +155,15 @@ export class DataTableDemo {
## Details
### Supplying data for the table
The column layout and row data are supplied to the table using an object that implements the
DataTableAdapter interface. This interface hides the internal details of the class that provides
the data, which gives a lot of flexibility in how the data can be stored and accessed. The DataTable
library includes a standard adapter class called ObjectDataTableAdapter that is useful for many
common uses. See the [DataTableAdapter](DataTableAdapter.md) for full details about the interface and
the ObjectDataTableAdapter class.
### 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.
@@ -451,101 +461,12 @@ Once corresponding action is clicked in the dropdown menu DataTable invokes `exe
where you can handle the process, inspect the action payload and all custom properties defined earlier,
and do corresponding actions.
### Data sources
<!-- Don't edit the See also section. Edit seeAlsoGraph.json and run config/generateSeeAlso.js -->
<!-- seealso start -->
## See also
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
}
]
*/
```
- [Data column component](data-column.component.md)
- [Pagination component](pagination.component.md)
- [DataTableAdapter](DataTableAdapter.md)
- [Document list component](document-list.component.md)
<!-- seealso end -->

2
docs/document-list.component.md
View File

@@ -724,5 +724,5 @@ That will give the following output:
- [Breadcrumb component](breadcrumb.component.md)
- [Content action component](content-action.component.md)
- [Dropdown breadcrumb component](dropdown-breadcrumb.component.md)
- [Permission style model](permission-style.model.md)
- [Permissions style model](permissions-style.model.md)
<!-- seealso end -->

3
docs/seeAlsoGraph.json
View File

@@ -23,6 +23,7 @@
"data-column.component",
"pagination.component"
],
"DataTableAdapter": ["datatable.component", "tasklist.component"],
"diagram.component": [],
"document-actions.service": [],
"document-list.component": [
@@ -48,7 +49,7 @@
"node-permission.directive": [],
"notification.service": [],
"pagination.component": [],
"permission-style.model": ["document-list.component"],
"permissions-style.model": ["document-list.component"],
"people-search.component": [],
"people.component": [],
"process-attachment-list.component": [],

31
docs/tasklist.component.md
View File

@@ -2,21 +2,6 @@
Renders a list containing all the tasks matched by the parameters specified.
<!-- 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)
* [DataTableAdapter example](#datatableadapter-example)
* [DataColumn Features](#datacolumn-features)
<!-- tocstop -->
<!-- markdown-toc end -->
## Basic Usage
```html
@@ -54,7 +39,7 @@ You can also use HTML-based schema declaration like shown below:
| hasIcon | boolean | true | Toggle the icon on the left . |
| landingTaskId | string | | Define which task id should be selected after the reloading. If the task id doesn't exist or nothing is passed it will select the first task |
| sort | string | | Define the sort of the processes. Possible values are : `created-desc`, `created-asc`, `due-desc`, `due-asc` |
| data | DataTableAdapter | | JSON object that represent the number and the type of the columns that you want show (see the [example](#datatableadapter-example) section below) |
| data | [DataTableAdapter](DataTableAdapter.md) | | JSON object that represent the number and the type of the columns that you want show (see the [example](#datatableadapter-example) section below) |
### Events
@@ -71,6 +56,10 @@ render details of any chosen instance.
### DataTableAdapter example
See the [DataTableAdapter](DataTableAdapter.md) page for full details of the interface and its standard
implementation, ObjectDataTableAdapter. Below is an example of how you can set up the adapter for a
typical tasklist.
```json
[
{"type": "text", "key": "id", "title": "Id"},
@@ -82,4 +71,12 @@ render details of any chosen instance.
### DataColumn Features
You can customize the styling of a column and also add features like tooltips and automatic translation of column titles. See the DataColumn docs for more information about these features.
You can customize the styling of a column and also add features like tooltips and automatic translation of column titles. See the [DataColumn](data-column.component.md) page for more information about these features.
<!-- Don't edit the See also section. Edit seeAlsoGraph.json and run config/generateSeeAlso.js -->
<!-- seealso start -->
## See also
- [Data column component](data-column.component.md)
- [DataTableAdapter](DataTableAdapter.md)
<!-- seealso end -->

5
docs/undocStoplist.json
View File

@@ -6,5 +6,8 @@
"card-view-item-dispatcher",
"content-column",
"content-action-list",
"empty-folder-content"
"empty-folder-content",
"empty-list",
"loading-template",
"no-content-template"
]