## 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).
## Install
```sh
npm install --save ng2-alfresco-documentlist
```
### Dependencies
Add the following dependency to your index.html:
```html
```
The following component needs to be added to your `systemjs.config.js` file:
- [ng2-translate](https://github.com/ocombe/ng2-translate)
- [ng2-alfresco-core](https://www.npmjs.com/package/ng2-alfresco-core)
- [ng2-alfresco-datatable](https://www.npmjs.com/package/ng2-alfresco-datatable)
You can get more details in the
[example implementation](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-alfresco-documentlist/demo/systemjs.config.js).
#### Material Design Lite
The style of this component is based on [material design](https://getmdl.io/), so if you want to visualize it correctly you have to add the material
design dependency to your project:
```sh
npm install --save material-design-icons material-design-lite
```
Also make sure you include these dependencies in your `index.html` file:
```html
```
## Basic usage
```html
```
### Properties
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| navigate | boolean | true | Toggles navigation to folder content or file preview |
| navigationMode | string (click\|dblclick) | dblclick | User interaction for folder navigation or file preview |
| thumbnails | boolean | false | Show document thumbnails rather than icons |
| multiselect | boolean | false | Toggles multiselect mode |
| contentActions | boolean | false | Toggles content actions for each row |
| contextMenuActions | boolean | false | Toggles context menus for each row |
### 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 |
_For a complete example source code please refer to
[DocumentList Demo](https://github.com/Alfresco/alfresco-ng2-components/tree/master/ng2-components/ng2-alfresco-documentlist/demo)
repository._
### Breadcrumb
DocumentList provides simple breadcrumb element to indicate the current position within a navigation hierarchy.
```html
```
Parent folder button is not displayed when breadcrumb is enabled.
### 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.
A custom set of columns can look like the following:
```html
```
Binding to nested properties is also supported. Assuming you have the node structure similar to following:
```json
{
"nodeRef": "workspace://SpacesStore/8bb36efb-c26d-4d2b-9199-ab6922f53c28",
"nodeType": "cm:folder",
"type": "folder",
"location": {
"repositoryId": "552ca13e-458b-4566-9f3e-d0f9c92facff",
"site": "swsdp",
"siteTitle": "Sample: Web Site Design Project"
}
}
```
the binding value for the Site column to display location site will be `location.site`:
```html
```
### Column definition
HTML attributes:
| Name | Type | Default | Description
| --- | --- | --- | --- |
| title | string | | Column title |
| sr-title | string | | Screen reader title, used only when `title` is empty |
| key | string | | Column source key, example: `createdByUser.displayName` |
| sortable | boolean | false | Toggle sorting ability via column header clicks |
| class | string | | CSS class list, example: `full-width ellipsis-cell` |
| type | string | text | Column type, text\|date\|number |
| format | string | | Value format pattern |
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.
### Actions
DocumentList supports declarative actions for Documents and Folders.
Each action can be bound to either default out-of-box handler or a custom behavior.
You can define both folder and document actions at the same time.
#### Menu actions
```html
```
```ts
export class MyView {
// ...
myCustomAction1(event) {
let entry = event.value.entry;
alert(`Custom document action for ${entry.name}`);
}
}
```
All document actions are rendered as a dropdown menu as on the picture below:
#### Default action handlers
The following action handlers are provided out-of-box:
- **Download** (document)
- **Delete** (document, folder)
All system handler names are case-insensitive, `handler="download"` and `handler="DOWNLOAD"`
will trigger the same `download` action.
##### Download
Initiates download of the corresponding document file.
```html
```
#### Folder actions
Folder actions have the same declaration as document actions except ```taget="folder"``` attribute value.
```html
```
```ts
export class MyView {
// ...
myFolderAction1(event) {
let entry = event.value.entry;
alert(`Custom folder action for ${entry.name}`);
}
}
```
### Context Menu
DocumentList also provide integration for 'Context Menu Service' from the
[ng2-alfresco-core](https://www.npmjs.com/package/ng2-alfresco-core) library.
You can automatically turn all menu actions (for the files and folders)
into context menu items like shown below:
Enabling context menu is very simple:
```ts
import {
CONTEXT_MENU_DIRECTIVES,
CONTEXT_MENU_PROVIDERS
} from 'ng2-alfresco-core';
import {
DOCUMENT_LIST_DIRECTIVES,
DOCUMENT_LIST_PROVIDERS
} from 'ng2-alfresco-documentlist';
@Component({
selector: 'my-view',
template: `
...
`,
directives: [DOCUMENT_LIST_DIRECTIVES, CONTEXT_MENU_DIRECTIVES],
providers: [DOCUMENT_LIST_PROVIDERS, CONTEXT_MENU_PROVIDERS]
})
export class MyView {
}
```
This enables context menu items for documents and folders.
### 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
or icon (similar to Google Drive behaviour). However it is possible switching to
other modes, like single-click navigation for example.
The following navigation modes are supported:
- **click**
- **dblclick**
The following example switches navigation to single clicks:
```html
```
### Events
DocumentList emits the following events:
| 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 |
## Advanced usage and customization
### Hiding columns on small screens
You can hide columns on small screens by means of custom CSS rules:
```css
@media all and (max-width: 768px) {
alfresco-document-list >>> th.desktop-only .cell-value {
display: none;
}
alfresco-document-list >>> td.desktop-only .cell-value {
display: none;
}
}
```
Now you can declare columns and assign `desktop-only` class where needed:
```html
```
**Desktop View**
**Mobile View**
### Custom 'empty folder' template
By default DocumentList provides the following content for the empty folder:
This can be changed by means of the custom html template:
```html
Sorry, no content here
```
That will give the following output:
### Customizing default actions
It is possible extending or replacing the list of available system actions for documents and folders.
Actions for the documents and folders can be accessed via the following services:
- `DocumentActionsService`, document action menu and quick document actions
- `FolderActionsService`, folder action menu and quick folder actions
Example below demonstrates how a new action handler can be registered with the
`DocumentActionsService`.
```html
```
You register custom handler called `my-handler` that will be executing `myDocumentActionHandler`
function each time upon being invoked.
```ts
import {
DocumentActionsService
} from 'ng2-alfresco-documentlist';
export class MyView {
constructor(documentActions: DocumentActionsService) {
documentActions.setHandler(
'my-handler',
this.myDocumentActionHandler.bind(this)
);
}
myDocumentActionHandler(obj: any) {
window.alert('my custom action handler');
}
}
```
The same approach allows changing the way out-of-box action handlers behave.
Registering custom action with the name `download` replaces default one:
```ts
export class MyView {
constructor(documentActions: DocumentActionsService) {
documentActions.setHandler(
'download',
this.customDownloadBehavior.bind(this)
);
}
customDownloadBehavior(obj: any) {
window.alert('my custom download behavior');
}
}
```
Typically you may want populating all your custom actions at the application root level or
by means of custom application service.
## Build from sources
You can build component from sources with the following commands:
```sh
npm install
npm run build
```
### Build the files and keep watching for changes
```sh
$ npm run build:w
```
### Running unit tests
```sh
npm test
```
### Running unit tests in browser
```sh
npm test-browser
```
This task rebuilds all the code, runs tslint, license checks and other quality check tools
before performing unit testing.
### Code coverage
```sh
npm run coverage
```
