mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-07-24 17:32:15 +00:00
[ADF-1453] Restructure README.md files (#2239)
* ADF-1453: Restructured Activiti Analytics readme * ADF-1453: Restructured Activiti Diagrams readme * ADF-1453: Restructured Activiti Form readme * ADF-1453: Restructured Activiti Process List readme * ADF-1453: Restructured Activiti Task List readme * ADF-1453: Restructured Alfresco Core readme * [ADF-1453] Restructured DataTable readme * [ADF-1453] Restructured Document List readme * [ADF-1453] Restructured Login readme * [ADF-1453] Restructured Alfresco Search readme * [ADF-1453] Restructured Alfresco Social readme * [ADF-1453] Restructured Alfresco Tag readme * [ADF-1453] Restructured Alfresco User Info readme * [ADF-1453] Restructured Alfresco Viewer readme * [ADF-1453] Restructured Alfresco Webscript readme * [ADF-1453] Fixed table display glitch * [ADF-1453] Fixed Markdown lint errors in readme files * [ADF-1453] Adding missing fileUploadDelete event to table in Upload readme * [ADF-1453] Resolved merge conflict with Upload readme * [ADF-1453] Changes from npm run doc
This commit is contained in:
Andy Stark
Mario Romano
@@ -1,58 +1,57 @@
|
||||
# DataTable Component
|
||||
# DataTable library
|
||||
|
||||
Contains the DataTable component and other related components and classes.
|
||||
|
||||
<!-- markdown-toc start - Don't edit this section. npm run toc to generate it-->
|
||||
|
||||
<!-- toc -->
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Install](#install)
|
||||
- [Basic usage](#basic-usage)
|
||||
* [DataTable Properties](#datatable-properties)
|
||||
* [DataColumn Properties](#datacolumn-properties)
|
||||
* [DataTable Events](#datatable-events)
|
||||
* [DataTable DOM Events](#datatable-dom-events)
|
||||
* [Automatic column header translation](#automatic-column-header-translation)
|
||||
* [Custom tooltips](#custom-tooltips)
|
||||
* [Custom Empty content template](#custom-empty-content-template)
|
||||
* [Custom Empty content template](#custom-empty-content-template-1)
|
||||
* [Loading content template](#loading-content-template)
|
||||
* [Column Templates](#column-templates)
|
||||
* [Events](#events)
|
||||
+ [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)
|
||||
- [DataTable component](#datatable-component)
|
||||
* [Basic usage](#basic-usage)
|
||||
+ [Properties](#properties)
|
||||
+ [Events](#events)
|
||||
* [Details](#details)
|
||||
+ [DataColumn Properties](#datacolumn-properties)
|
||||
+ [DataTable DOM Events](#datatable-dom-events)
|
||||
+ [Automatic column header translation](#automatic-column-header-translation)
|
||||
+ [Custom tooltips](#custom-tooltips)
|
||||
+ [Custom Empty content template](#custom-empty-content-template)
|
||||
+ [Loading content template](#loading-content-template)
|
||||
+ [Column Templates](#column-templates)
|
||||
+ [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)
|
||||
- [Pagination Component](#pagination-component)
|
||||
* [Properties](#properties)
|
||||
* [Events](#events-1)
|
||||
- [Build from sources](#build-from-sources)
|
||||
- [NPM scripts](#npm-scripts)
|
||||
- [Demo](#demo)
|
||||
- [License](#license)
|
||||
* [Basic Usage](#basic-usage)
|
||||
+ [Properties](#properties-1)
|
||||
+ [Events](#events-2)
|
||||
* [Details](#details-1)
|
||||
- [Project Information](#project-information)
|
||||
* [Prerequisites](#prerequisites)
|
||||
* [Install](#install)
|
||||
* [Build from sources](#build-from-sources)
|
||||
* [NPM scripts](#npm-scripts)
|
||||
* [Demo](#demo)
|
||||
* [License](#license)
|
||||
|
||||
<!-- tocstop -->
|
||||
|
||||
<!-- markdown-toc end -->
|
||||
|
||||
## DataTable component
|
||||
|
||||
Displays data as a table with customizable columns and presentation.
|
||||
|
||||
|
||||
|
||||
See it live: [DataTable Quickstart](https://embed.plnkr.co/80qr4YFBeHjLMdAV0F6l/)
|
||||
|
||||
## 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).
|
||||
|
||||
> If you plan using this component with projects generated by Angular CLI, please refer to the following article: [Using ADF with Angular CLI](https://github.com/Alfresco/alfresco-ng2-components/wiki/Angular-CLI)
|
||||
|
||||
## Install
|
||||
|
||||
```sh
|
||||
npm install ng2-alfresco-datatable
|
||||
```
|
||||
|
||||
## Basic usage
|
||||
### Basic usage
|
||||
|
||||
**app.component.html**
|
||||
|
||||
@@ -99,8 +98,6 @@ export class DataTableDemo {
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
You can also use HTML-based schema declaration like shown below:
|
||||
|
||||
```html
|
||||
@@ -146,7 +143,7 @@ export class DataTableDemo {
|
||||
}
|
||||
```
|
||||
|
||||
### DataTable Properties
|
||||
#### Properties
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -165,9 +162,19 @@ export class DataTableDemo {
|
||||
| showHeader | boolean | true | Toggles header visibility |
|
||||
| selection | DataRow[] | [] | Contains selected rows |
|
||||
|
||||
### DataColumn Properties
|
||||
#### Events
|
||||
|
||||
Here's the list of available properties you can define for a Data Column definition.
|
||||
| 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
|
||||
|
||||
#### DataColumn Properties
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -181,17 +188,7 @@ Here's the list of available properties you can define for a Data Column definit
|
||||
| class | string | | Additional CSS class to be applied to column (header and cells) |
|
||||
| formatTooltip | Function | | Custom tooltip formatter function. |
|
||||
|
||||
### DataTable 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 |
|
||||
|
||||
### DataTable DOM Events
|
||||
#### 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.
|
||||
@@ -221,7 +218,7 @@ onRowClick(event) {
|
||||
|
||||
|
||||
|
||||
### Automatic column header translation
|
||||
#### Automatic column header translation
|
||||
|
||||
You can also use i18n resource keys with DataColumn `title` property.
|
||||
The component will automatically check the corresponding i18n resources and fetch corresponding value.
|
||||
@@ -235,7 +232,7 @@ The component will automatically check the corresponding i18n resources and fetc
|
||||
|
||||
This feature is optional. Regular text either plain or converted via the `translate` pipe will still be working as it was before.
|
||||
|
||||
### Custom tooltips
|
||||
#### Custom tooltips
|
||||
|
||||
You can create custom tooltips for the table cells by providing a `formatTooltip` property with a tooltip formatter function when declaring a data column.
|
||||
|
||||
@@ -268,7 +265,7 @@ export class MyComponent {
|
||||
|
||||
To disable the tooltip your function can return `null` or an empty string.
|
||||
|
||||
### Custom Empty content template
|
||||
#### Custom Empty content template
|
||||
|
||||
You can add a template that will be shown when there are no results in your datatable:
|
||||
|
||||
@@ -294,9 +291,7 @@ You can add a template that will be shown when there are no results in your data
|
||||
</adf-datatable>
|
||||
```
|
||||
|
||||
### Custom Empty content template
|
||||
|
||||
You can use the empty list component if you want to show the default ADF empty template:
|
||||
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:
|
||||
|
||||
@@ -330,7 +325,7 @@ You can use any HTML layout or Angular component as a content of the empty templ
|
||||
|
||||
|
||||
|
||||
### Loading content template
|
||||
#### Loading content template
|
||||
|
||||
You can add a template that will be shown during the loading of your data:
|
||||
|
||||
@@ -368,7 +363,7 @@ You can add a template that will be shown during the loading of your data:
|
||||
|
||||
Note: the `<loading-content-template>` and `<no-content-template>` can be used together
|
||||
|
||||
### Column Templates
|
||||
#### Column Templates
|
||||
|
||||
It is possible to assign a custom column template like the following:
|
||||
|
||||
@@ -414,11 +409,11 @@ In the second case `entry` variable is holding a reference to the following data
|
||||
}
|
||||
```
|
||||
|
||||
### Events
|
||||
#### Events
|
||||
|
||||
#### rowClick event
|
||||
##### rowClick event
|
||||
|
||||
_This event is emitted when user clicks the row._
|
||||
Emitted when user clicks a row.
|
||||
|
||||
Event properties:
|
||||
|
||||
@@ -436,11 +431,11 @@ onRowClicked(event: DataRowEvent) {
|
||||
}
|
||||
```
|
||||
|
||||
_This event is cancellable, you can use `event.preventDefault()` to prevent default behaviour._
|
||||
This event is cancellable, you can use `event.preventDefault()` to prevent default behaviour.
|
||||
|
||||
#### rowDblClick event
|
||||
##### rowDblClick event
|
||||
|
||||
_This event is emitted when user double-clicks the row._
|
||||
Emitted when user double-clicks a row.
|
||||
|
||||
Event properties:
|
||||
|
||||
@@ -458,11 +453,11 @@ onRowDblClicked(event: DataRowEvent) {
|
||||
}
|
||||
```
|
||||
|
||||
_This event is cancellable, you can use `event.preventDefault()` to prevent default behaviour._
|
||||
This event is cancellable, you can use `event.preventDefault()` to prevent default behaviour.
|
||||
|
||||
#### showRowContextMenu event
|
||||
##### showRowContextMenu event
|
||||
|
||||
_Emitted before context menu is displayed for a row._
|
||||
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.
|
||||
@@ -488,17 +483,17 @@ onShowRowContextMenu(event: DataCellEvent) {
|
||||
}
|
||||
```
|
||||
|
||||
_This event is cancellable, you can use `event.preventDefault()` to prevent default behaviour._
|
||||
This event is cancellable, you can use `event.preventDefault()` to prevent default behaviour.
|
||||
|
||||
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 behaviour._
|
||||
See the [ContextMenu](https://www.npmjs.com/package/ng2-alfresco-core)
|
||||
documentation for more details on context actions format and behaviour.
|
||||
|
||||
#### showRowActionsMenu event
|
||||
##### showRowActionsMenu event
|
||||
|
||||
_Emitted before actions menu is displayed for a row.
|
||||
Requires `actions` property to be set to `true`._
|
||||
Emitted before actions menu is displayed for a row.
|
||||
Requires `actions` property to be set to `true`.
|
||||
|
||||
Event properties:
|
||||
|
||||
@@ -512,11 +507,11 @@ value: {
|
||||
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._
|
||||
This event is cancellable, you can use `event.preventDefault()` to prevent default behaviour.
|
||||
|
||||
#### executeRowAction event
|
||||
##### executeRowAction event
|
||||
|
||||
_Emitted when row action is executed by user._
|
||||
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
|
||||
@@ -566,7 +561,7 @@ 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
|
||||
#### Data sources
|
||||
|
||||
DataTable component gets data by means of data adapter.
|
||||
It is possible having data retrieved from different kinds of sources by implementing
|
||||
@@ -634,7 +629,7 @@ let data = new ObjectDataTableAdapter(
|
||||
);
|
||||
```
|
||||
|
||||
## Generate schema
|
||||
#### Generate schema
|
||||
|
||||
It is possible to auto generate your schema if you have only the data row
|
||||
|
||||
@@ -667,29 +662,67 @@ let schema = ObjectDataTableAdapter.generateSchema(data);
|
||||
|
||||
## Pagination Component
|
||||
|
||||
Adds pagination to the component it is used with.
|
||||
|
||||
|
||||
|
||||
### 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<number> | [ 25, 50, 100 ] | An array of page sizes |
|
||||
|
||||
#### Events
|
||||
|
||||
| Name | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| change | EventEmitter<PaginationQueryParams> | Triggered for any action in pagination |
|
||||
| nextPage | EventEmitter<Pagination> | Triggered on next page action |
|
||||
| prevPage | EventEmitter<Pagination> | Triggered on previous page action |
|
||||
| changePageSize | EventEmitter<Pagination> | Triggered on page size change action |
|
||||
| changePageNumber | EventEmitter<Pagination> | 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.
|
||||
|
||||
### Properties
|
||||
For `change` event, a [PaginationQueryParams](https://github.com/Alfresco/alfresco-ng2-components/tree/master/ng2-components/ng2-alfresco-core/src/components/pagination/pagination-query-params.ts) (including the query params supported by the REST API, `skipCount` and `maxItems`) is returned.
|
||||
|
||||
| Name | Type | Default | Description
|
||||
| --- | --- | --- | --- |
|
||||
| supportedPageSizes | numer[] | [5, 10, 20, 50, 100] | This array describes the set of options shown in the pick list |
|
||||
| maxItems | boolean | false | Max number of elements shown per page. If you pick another size from the pick list this option will be overwritten |
|
||||
| pagination | Pagination | {count: 0, totalItems: 0, skipCount: 0, maxItems: 20 , hasMoreItems: true} | The Alfresco Api returns a pagination object, you can use it to feed the pagination component, or create your own. |
|
||||
For all events other than `change`, a new [Pagination object](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/Pagination.md) is returned as in the folowing example, with updated properties to be used to query further.
|
||||
|
||||
### Events
|
||||
## Project Information
|
||||
|
||||
| Name | Description
|
||||
| --- | --- |
|
||||
| changePageSize | Emitted when user picks one of the options from the pick list |
|
||||
| nextPage | Emitted when user clicks next page button |
|
||||
| prevPage | Emitted when user clicks previous page button |
|
||||
### Prerequisites
|
||||
|
||||
All the events carry with them the current pagination object.
|
||||
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).
|
||||
|
||||
## Build from sources
|
||||
> If you plan using this component with projects generated by Angular CLI, please refer to the following article: [Using ADF with Angular CLI](https://github.com/Alfresco/alfresco-ng2-components/wiki/Angular-CLI)
|
||||
|
||||
### Install
|
||||
|
||||
```sh
|
||||
npm install ng2-alfresco-datatable
|
||||
```
|
||||
|
||||
### Build from sources
|
||||
|
||||
You can build component from sources with the following commands:
|
||||
|
||||
@@ -701,7 +734,7 @@ npm run build
|
||||
> The `build` task rebuilds all the code, runs tslint, license checks
|
||||
> and other quality check tools before performing unit testing.
|
||||
|
||||
## NPM scripts
|
||||
### NPM scripts
|
||||
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
@@ -710,7 +743,7 @@ npm run build
|
||||
| npm run test-browser | Run unit tests in the browser
|
||||
| npm run coverage | Run unit tests and display code coverage report |
|
||||
|
||||
## Demo
|
||||
### Demo
|
||||
|
||||
Please check the demo folder for a demo project
|
||||
|
||||
@@ -720,6 +753,6 @@ npm install
|
||||
npm start
|
||||
```
|
||||
|
||||
## License
|
||||
### License
|
||||
|
||||
[Apache Version 2.0](https://github.com/Alfresco/alfresco-ng2-components/blob/master/LICENSE)
|
||||
|
||||
BIN
ng2-components/ng2-alfresco-datatable/docs/assets/basic.png
Normal file
BIN
ng2-components/ng2-alfresco-datatable/docs/assets/basic.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
Reference in New Issue
Block a user