[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
2017-08-25 17:27:09 +01:00
committed by Mario Romano
parent 541cbcb258
commit 54f4a07f53
25 changed files with 2034 additions and 1666 deletions

View File

@@ -1,42 +1,32 @@
# DocumentList Component
# DocumentList library
Contains the Document List component and other related components and classes.
<!-- markdown-toc start - Don't edit this section. npm run toc to generate it-->
<!-- toc -->
- [Prerequisites](#prerequisites)
- [See also](#see-also)
- [Install](#install)
- [Document List](#document-list)
* [Properties](#properties)
* [Events](#events)
* [DOM Events](#dom-events)
* [Handling DOM events](#handling-dom-events)
* [Data Sources](#data-sources)
+ [Node ID](#node-id)
+ [Repository aliases](#repository-aliases)
+ [DocumentList aliases](#documentlist-aliases)
* [Trashcan](#trashcan)
* [Shared Links](#shared-links)
* [Sites](#sites)
* [Favorites](#favorites)
* [Recent Files](#recent-files)
* [Setting default folder](#setting-default-folder)
- [Custom icons for selected rows](#custom-icons-for-selected-rows)
- [Calling DocumentList api directly](#calling-documentlist-api-directly)
- [Breadcrumb Component](#breadcrumb-component)
* [Properties](#properties-1)
* [Events](#events-1)
- [Dropdown Site Component](#dropdown-site-component)
* [Events](#events-2)
- [Custom columns](#custom-columns)
* [DataColumn Properties](#datacolumn-properties)
* [Column Types](#column-types)
* [Underlying node object](#underlying-node-object)
* [Date Column](#date-column)
* [Location Column](#location-column)
* [Column Template](#column-template)
* [Actions](#actions)
- [Document List component](#document-list-component)
* [Basic Usage](#basic-usage)
+ [Properties](#properties)
+ [Events](#events)
* [Details](#details)
+ [DOM Events](#dom-events)
+ [Data Sources](#data-sources)
- [Node ID](#node-id)
- [Repository aliases](#repository-aliases)
- [DocumentList aliases](#documentlist-aliases)
+ [Setting default folder](#setting-default-folder)
+ [Custom icons for selected rows](#custom-icons-for-selected-rows)
+ [Calling DocumentList api directly](#calling-documentlist-api-directly)
+ [Custom columns](#custom-columns)
+ [DataColumn Properties](#datacolumn-properties)
+ [Column Types](#column-types)
+ [Underlying node object](#underlying-node-object)
+ [Date Column](#date-column)
+ [Location Column](#location-column)
+ [Column Template](#column-template)
+ [Actions](#actions)
+ [Menu actions](#menu-actions)
+ [Default action handlers](#default-action-handlers)
- [Delete - System handler combined with custom handler](#delete---system-handler-combined-with-custom-handler)
@@ -44,11 +34,17 @@
- [Delete - Disable button checking the permission](#delete---disable-button-checking-the-permission)
- [Download](#download)
- [Copy and move](#copy-and-move)
* [Error, Permission and success callback](#error-permission-and-success-callback)
- [Error, Permission and success callback](#error-permission-and-success-callback)
+ [Folder actions](#folder-actions)
* [Context Menu](#context-menu)
* [Navigation mode](#navigation-mode)
* [Events](#events-3)
+ [Context Menu](#context-menu)
+ [Navigation mode](#navigation-mode)
- [Breadcrumb Component](#breadcrumb-component)
* [Basic Usage](#basic-usage-1)
+ [Properties](#properties-1)
+ [Events](#events-1)
- [Dropdown Site Component](#dropdown-site-component)
* [Basic Usage](#basic-usage-2)
+ [Events](#events-2)
- [Advanced usage and customization](#advanced-usage-and-customization)
* [Custom tooltips](#custom-tooltips)
* [Custom row filter](#custom-row-filter)
@@ -58,33 +54,23 @@
+ [Examples](#examples)
* [Custom 'empty folder' template](#custom-empty-folder-template)
* [Customizing default actions](#customizing-default-actions)
- [Build from sources](#build-from-sources)
- [NPM scripts](#npm-scripts)
- [Demo](#demo)
- [License](#license)
- [See also](#see-also)
- [Project Information](#project-information)
* [Prerequisites](#prerequisites)
* [Install](#install)
* [NPM scripts](#npm-scripts)
* [Demo](#demo)
* [License](#license)
<!-- tocstop -->
<!-- markdown-toc end -->
## Prerequisites
## Document List component
Before you start using this development framework, make sure you have installed all required software and done all the
necessary configuration [prerequisites](https://github.com/Alfresco/alfresco-ng2-components/blob/master/PREREQUISITES.md).
Displays the documents from a repository.
> 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)
## See also
- [Walkthrough: adding indicators to clearly highlight information about a node](docs/metadata-indicators.md)
## Install
```sh
npm install ng2-alfresco-documentlist
```
## Document List
### Basic Usage
```html
<adf-document-list
@@ -95,7 +81,7 @@ npm install ng2-alfresco-documentlist
</adf-document-list>
```
### Properties
#### Properties
The properties currentFolderId, folderNode and node are the entry initialization properties of the document list. They cannot be used together, choose the one that suites more your use case.
@@ -124,20 +110,24 @@ The properties currentFolderId, folderNode and node are the entry initialization
| sorting | string[] | | Defines default sorting. The format is an array of 2 strings `[key, direction]` i.e. `['name', 'desc']` or `['name', 'asc']`. Set this value only if you want to override default sorting detected by the component based on columns. |
| locationFormat | string | '/' | The default route for all the location-based columns (if declared). |
### Events
#### Events
| Name | Description |
| --- | --- |
| `nodeClick` | Emitted when user clicks the node |
| `nodeDblClick` | Emitted when user double-clicks the node |
| `folderChange` | Emitted upon display folder changed |
| `preview` | Emitted when document preview is requested either with single or double click |
| nodeClick | emitted when user clicks a list node |
| nodeDblClick | emitted when user double-clicks list node |
| folderChange | emitted once current display folder has changed |
| preview | emitted when user acts upon files with either single or double click (depends on `navigation-mode`), recommended for Viewer components integration |
| permissionError | emitted when user is attempting to create a folder via action menu without having the permission to do it |
| ready | emitted when the documentList is ready and loads all the elements|
_For a complete example source code please refer to
### Details
For a complete example source code, refer to the
[DocumentList Demo](https://github.com/Alfresco/alfresco-ng2-components/tree/master/ng2-components/ng2-alfresco-documentlist/demo)
repository._
repository.
### DOM Events
#### DOM Events
Below are the DOM events the DocumentList component emits.
All of them are `bubbling`, meaning you can handle them in any component up the parent hierarchy, even if DocumentList is wrapped by another component(s).
@@ -160,13 +150,11 @@ Every event is represented by a [CustomEvent](https://developer.mozilla.org/en/d
Please refer to the DataTable documentation to find details about additional DOM events the DocumentList component bubbles up from the DataTable.
### Handling DOM events
Here's a basic example on handling DOM events in the parent elements:
Below is a basic example of handling DOM events in the parent elements.
```html
<div (node-click)="onNodeClicked($event)"
(node-dblclick)="onNodeDblClicked($event)">
(node-dblclick)="onNodeDblClicked($event)">
<div>
<adf-upload-drag-area ...>
<adf-document-list ...>
@@ -177,15 +165,15 @@ Here's a basic example on handling DOM events in the parent elements:
</div>
```
### Data Sources
#### Data Sources
For the Document List data sources you can use one of the following options:
#### Node ID
##### Node ID
The unique identifier of the Node. Gets automatically updated when you perform navigation to other folders.
#### Repository aliases
##### Repository aliases
You can use one of the well-known reserved aliases:
@@ -193,7 +181,7 @@ You can use one of the well-known reserved aliases:
- `-shared-`
- `-my-`
#### DocumentList aliases
##### DocumentList aliases
The DocumentList component also provides support for the following reserved aliases you can use:
@@ -222,7 +210,7 @@ The default column layout for non-reserved views is:
- Modified (date)
- Modified by
### Trashcan
__Trashcan__
```html
<adf-document-list
@@ -240,7 +228,7 @@ Default layout:
- Deleted
- Deleted by
### Shared Links
__Shared Links__
```html
<adf-document-list
@@ -259,7 +247,7 @@ Default layout:
- Modified by
- Shared by
### Sites
__Sites__
```html
<adf-document-list
@@ -273,7 +261,7 @@ Default layout:
- Title
- Status
### Favorites
__Favorites__
```html
<adf-document-list
@@ -291,7 +279,7 @@ Default layout:
- Modified
- Modified by
### Recent Files
__Recent Files__
```html
<adf-document-list
@@ -306,7 +294,7 @@ Default layout:
- Name
- Location
### Setting default folder
#### Setting default folder
You can set current folder path by assigning a value for `currentFolderId` property.
It can be either one of the well-known locations as **-root-**, **-shared-** or **-my-** or a node ID (guid).
@@ -354,7 +342,7 @@ It helps examining other valuable information you can have access to if needed:
**Important note**: for this particular scenario you must also trigger `changeDetector.detectChanges()` as in the example above.
## Custom icons for selected rows
#### Custom icons for selected rows
You can use the "class" property of the "DataColumn" component to apply your custom css.
@@ -408,7 +396,7 @@ Once your application starts you should see the following icon for each selected
![view-child](docs/assets/document-list-custom-icon.png)
## Calling DocumentList api directly
#### Calling DocumentList api directly
Typically you will be binding DocumentList properties to your application/component class properties:
@@ -479,53 +467,7 @@ It is important accessing child components at least at the `AfterViewInit` state
Any UI click (buttons, links, etc.) event handlers are absolutely fine. This cannot be `ngOnInit` event though.
You can get more details in [Component lifecycle hooks](https://angular.io/docs/ts/latest/guide/lifecycle-hooks.html) article.
## Breadcrumb Component
DocumentList provides simple breadcrumb element to indicate the current position within a navigation hierarchy.
```html
<adf-breadcrumb
[target]="documentList"
[folderNode]="documentList.folderNode">
</adf-breadcrumb>
```
***Note:*** the `<adf-document-list-breadcrumb>` and `<adf-breadcrumb>` are the same component you can still use the old tag name
![Breadcrumb](docs/assets/breadcrumb.png)
### Properties
| Name | Type | Description |
| --- | --- | --- |
| target | DocumentListComponent | (optional) DocumentList component to operate with. Upon clicks will instruct the given component to update. |
| folderNode | [MinimalNodeEntryEntity](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeMinimalEntry.md) | Active node, builds UI based on `folderNode.path.elements` collection. |
| root | String | (optional) Name of the root element of the breadcrumb. You can use this property to rename "Company Home" to "Personal Files" for example. |
### Events
| Name | Returned Type | Description |
| --- | --- | --- |
| navigate | [PathElementEntity](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/PathElementEntity.md) | emitted when user clicks on a breadcrumb |
## Dropdown Site Component
DocumentList now provides a simple dropdown component to show and interact with the sites of the current user.
```html
<adf-sites-dropdown
(change)="getSiteContent($event)">
</adf-sites-dropdown>
```
![Dropdown sites](docs/assets/document-list-dropdown-list.png)
### Events
| Name | Returned Type | Description |
| --- | --- | --- |
| change | [SiteModel](https://github.com/Alfresco/alfresco-ng2-components/blob/development/ng2-components/ng2-alfresco-documentlist/src/models/site.model.ts) | emitted when user selects a site. When default option is selected an empty model is emitted |
## Custom columns
#### Custom columns
It is possible to reorder, extend or completely redefine data columns displayed by the component.
By default special `$thumbnail` and `displayName` columns are rendered.
@@ -576,7 +518,7 @@ You can also use HTML-based schema declaration used by DataTable, TaskList and o
</adf-datatable>
```
### DataColumn Properties
#### DataColumn Properties
Here's the list of available properties you can define for a Data Column definition.
@@ -592,7 +534,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. |
### Column Types
#### Column Types
The DataColumn `type` property can take one of the following values:
@@ -602,7 +544,7 @@ The DataColumn `type` property can take one of the following values:
- fileSize
- location
### Underlying node object
#### Underlying node object
DocumentList component assigns an instance of `MinimalNode` type (`alfresco-js-api`) as a data context of each row.
@@ -647,7 +589,7 @@ Here's a short example:
</adf-document-list>
```
### Date Column
#### Date Column
For `date` column type the [DatePipe](https://angular.io/docs/ts/latest/api/common/DatePipe-class.html) formatting is used.
For a full list of available `format` values please refer to [DatePipe](https://angular.io/docs/ts/latest/api/common/DatePipe-class.html) documentation.
@@ -655,7 +597,7 @@ For a full list of available `format` values please refer to [DatePipe](https://
ADF also supports additional `timeAgo` value for the `format` property.
That triggers the date values to be rendered using popular ["Time from now"](https://momentjs.com/docs/#/displaying/fromnow/) format.
### Location Column
#### Location Column
This column is used to display a clickable location link pointing to the parent path of the node.
@@ -695,7 +637,7 @@ All links rendered in the column above will have an address mapped to `/files`:
...
```
### Column Template
#### Column Template
It is possible to provide custom column/cell template that may contain other Angular components or HTML elements:
@@ -770,7 +712,7 @@ In the Example below we will add the [ng2-alfresco-tag](https://www.npmjs.com/pa
![Tag component in document List](docs/assets/document-list-tag-template.png)
### Actions
#### Actions
Properties:
@@ -982,7 +924,7 @@ Shows the destination chooser dialog for copy and move actions. By default the d
</adf-document-list>
```
###### Error, Permission and success callback
##### Error, Permission and success callback
Defining error, permission and success callbacks are pretty much the same as doing it for the delete permission handling.
@@ -1044,7 +986,7 @@ export class MyView {
![Folder Actions](docs/assets/folder-actions.png)
### Context Menu
#### Context Menu
DocumentList also provides integration for 'Context Menu Service' from the
[ng2-alfresco-core](https://www.npmjs.com/package/ng2-alfresco-core) library.
@@ -1070,7 +1012,7 @@ export class MyView {
This enables context menu items for documents and folders.
### Navigation mode
#### Navigation mode
By default DocumentList component uses 'double-click' mode for navigation.
That means user will see the contents of the folder by double-clicking its name
@@ -1090,18 +1032,56 @@ The following example switches navigation to single clicks:
</adf-document-list>
```
### Events
## Breadcrumb Component
DocumentList emits the following events:
Indicates the current position within a navigation hierarchy.
| Name | Description |
| --- | --- |
| nodeClick | emitted when user clicks a list node |
| nodeDblClick | emitted when user double-clicks list node |
| folderChange | emitted once current display folder has changed |
| preview | emitted when user acts upon files with either single or double click (depends on `navigation-mode`), recommended for Viewer components integration |
| permissionError | emitted when user is attempting to create a folder via action menu without having the permission to do it |
| ready | emitted when the documentList is ready and loads all the elements|
![Breadcrumb](docs/assets/breadcrumb.png)
### Basic Usage
```html
<adf-breadcrumb
[target]="documentList"
[folderNode]="documentList.folderNode">
</adf-breadcrumb>
```
***Note:*** the `<adf-document-list-breadcrumb>` and `<adf-breadcrumb>` are the same component - you can still use the old tag name.
#### Properties
| Name | Type | Description |
| --- | --- | --- |
| target | DocumentListComponent | (optional) DocumentList component to operate with. Upon clicks will instruct the given component to update. |
| folderNode | [MinimalNodeEntryEntity](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeMinimalEntry.md) | Active node, builds UI based on `folderNode.path.elements` collection. |
| root | String | (optional) Name of the root element of the breadcrumb. You can use this property to rename "Company Home" to "Personal Files" for example. |
#### Events
| Name | Returned Type | Description |
| --- | --- | --- |
| navigate | [PathElementEntity](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/PathElementEntity.md) | emitted when user clicks on a breadcrumb |
## Dropdown Site Component
Displays a dropdown menu to show and interact with the sites of the current user.
![Dropdown sites](docs/assets/document-list-dropdown-list.png)
### Basic Usage
```html
<adf-sites-dropdown
(change)="getSiteContent($event)">
</adf-sites-dropdown>
```
#### Events
| Name | Returned Type | Description |
| --- | --- | --- |
| change | [SiteModel](https://github.com/Alfresco/alfresco-ng2-components/blob/development/ng2-components/ng2-alfresco-documentlist/src/models/site.model.ts) | emitted when user selects a site. When default option is selected an empty model is emitted |
## Advanced usage and customization
@@ -1456,7 +1436,25 @@ export class MyView {
Typically you may want populating all your custom actions at the application root level or
by means of custom application service.
## Build from sources
## See also
- [Walkthrough: adding indicators to clearly highlight information about a node](docs/metadata-indicators.md)
## Project Information
### Prerequisites
Before you start using this development framework, make sure you have installed all required software and done all the
necessary configuration [prerequisites](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-documentlist
### Build from sources
You can build component from sources with the following commands:
@@ -1468,7 +1466,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 |
| --- | --- |
@@ -1477,7 +1475,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
@@ -1487,6 +1485,6 @@ npm install
npm start
```
## License
### License
[Apache Version 2.0](https://github.com/Alfresco/alfresco-ng2-components/blob/master/LICENSE)