From 3cd5eafddebb8b769aaf95ceb9d5c457135e2def Mon Sep 17 00:00:00 2001 From: Andy Stark <30621568+therealandeeee@users.noreply.github.com> Date: Fri, 6 Oct 2017 14:10:25 +0100 Subject: [PATCH] [ADF-1586] Updated Datatable docs (#2445) * [ADF-1586] Updates to Datatable docs * [ADF-1586] Fixed broken link in doc index page --- docIndex.md | 15 ++- docs/DataTableAdapter.md | 166 ++++++++++++++++++++++++++++++++ docs/data-column.component.md | 10 +- docs/datatable.component.md | 119 ++++------------------- docs/document-list.component.md | 2 +- docs/seeAlsoGraph.json | 3 +- docs/tasklist.component.md | 31 +++--- docs/undocStoplist.json | 5 +- 8 files changed, 219 insertions(+), 132 deletions(-) create mode 100644 docs/DataTableAdapter.md diff --git a/docIndex.md b/docIndex.md index ac04adc0a9..d90927ad48 100644 --- a/docIndex.md +++ b/docIndex.md @@ -284,7 +284,6 @@ for more information about installing and using the source code. ### Services -- [*People service](ng2-components/ng2-activiti-tasklist/src/services/people.service.ts) - [*Process upload service](ng2-components/ng2-activiti-tasklist/src/services/process-upload.service.ts) - [*Tasklist service](ng2-components/ng2-activiti-tasklist/src/services/tasklist.service.ts) @@ -350,8 +349,8 @@ for more information about installing and using the source code. - [*Log service](ng2-components/ng2-alfresco-core/src/services/log.service.ts) - [*Nodes api service](ng2-components/ng2-alfresco-core/src/services/nodes-api.service.ts) - [*Page title service](ng2-components/ng2-alfresco-core/src/services/page-title.service.ts) -- [*People content api service](ng2-components/ng2-alfresco-core/src/services/people-content.service.ts) -- [*People process api service](ng2-components/ng2-alfresco-core/src/services/people-process.service.ts) +- [*People content service](ng2-components/ng2-alfresco-core/src/services/people-content.service.ts) +- [*People process service](ng2-components/ng2-alfresco-core/src/services/people-process.service.ts) - [*Search api service](ng2-components/ng2-alfresco-core/src/services/search-api.service.ts) - [*Search service](ng2-components/ng2-alfresco-core/src/services/search.service.ts) - [*Shared links api service](ng2-components/ng2-alfresco-core/src/services/shared-links-api.service.ts) @@ -375,16 +374,14 @@ for more information about installing and using the source code. - [Datatable component](docs/datatable.component.md) - [*Datatable cell component](ng2-components/ng2-alfresco-datatable/src/components/datatable/datatable-cell.component.ts) - [*Date cell component](ng2-components/ng2-alfresco-datatable/src/components/datatable/date-cell.component.ts) -- [*Empty list component](ng2-components/ng2-alfresco-datatable/src/components/datatable/empty-list.component.ts) - [*Filesize cell component](ng2-components/ng2-alfresco-datatable/src/components/datatable/filesize-cell.component.ts) - [*Location cell component](ng2-components/ng2-alfresco-datatable/src/components/datatable/location-cell.component.ts) - -### Directives - -- [*Loading template directive](ng2-components/ng2-alfresco-datatable/src/directives/loading-template.directive.ts) -- [*No content template directive](ng2-components/ng2-alfresco-datatable/src/directives/no-content-template.directive.ts) +### Other classes and interfaces + +- [DataTableAdapter interface](docs/DataTableAdapter.md) + [(Back to Contents)](#contents) ## ADF Documentlist diff --git a/docs/DataTableAdapter.md b/docs/DataTableAdapter.md new file mode 100644 index 0000000000..4bf1673ecc --- /dev/null +++ b/docs/DataTableAdapter.md @@ -0,0 +1,166 @@ +# DataTableAdapter interface + +Defines how table data is supplied to [DataTable](datatable.component.md) +and [Tasklist](tasklist.component.md) components. + + + + + +- [Properties](#properties) +- [Methods](#methods) +- [Details](#details) + * [Columns and rows](#columns-and-rows) + * [ObjectDataTableAdapter](#objectdatatableadapter) +- [See also](#see-also) + + + + + +## Properties + +| Name | Type | Description | +| --- | --- | --- | +| selectedRow | DataRow | The data for the currently selected row. | + +## Methods + +`getRows(): Array;`
+`setRows(rows: Array): void;`
+Get/set the values for display in the table using an array of rows. + +`getColumns(): Array;`
+`setColumns(columns: Array): void;`
+Get/set an array of column specifications. + +`getValue(row: DataRow, col: DataColumn): any;`
+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; + 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 + } +] +*/ + +``` + + + +## See also + +- [Datatable component](datatable.component.md) +- [Tasklist component](tasklist.component.md) + \ No newline at end of file diff --git a/docs/data-column.component.md b/docs/data-column.component.md index 0eabc4a9e3..1396629864 100644 --- a/docs/data-column.component.md +++ b/docs/data-column.component.md @@ -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) @@ -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 ``` -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 @@ -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 + + +## 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; - setRows(rows: Array): void; - getColumns(): Array; - setColumns(columns: Array): 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; -} -``` - -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) + \ No newline at end of file diff --git a/docs/document-list.component.md b/docs/document-list.component.md index 380ee9d243..9633b64525 100644 --- a/docs/document-list.component.md +++ b/docs/document-list.component.md @@ -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) \ No newline at end of file diff --git a/docs/seeAlsoGraph.json b/docs/seeAlsoGraph.json index 4bc8c51da0..d3ab66c791 100644 --- a/docs/seeAlsoGraph.json +++ b/docs/seeAlsoGraph.json @@ -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": [], diff --git a/docs/tasklist.component.md b/docs/tasklist.component.md index 16674ce2f6..2dae4c3168 100644 --- a/docs/tasklist.component.md +++ b/docs/tasklist.component.md @@ -2,21 +2,6 @@ Renders a list containing all the tasks matched by the parameters specified. - - - - -- [Basic Usage](#basic-usage) - * [Properties](#properties) - * [Events](#events) -- [Details](#details) - * [DataTableAdapter example](#datatableadapter-example) - * [DataColumn Features](#datacolumn-features) - - - - - ## 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. \ No newline at end of file +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. + + + +## See also + +- [Data column component](data-column.component.md) +- [DataTableAdapter](DataTableAdapter.md) + diff --git a/docs/undocStoplist.json b/docs/undocStoplist.json index 7fe1c07098..6ff1b496a7 100644 --- a/docs/undocStoplist.json +++ b/docs/undocStoplist.json @@ -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" ] \ No newline at end of file