mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-07-24 17:32:15 +00:00
[ADF-4152] Updated folder structure of core docs (#4415)
* [ADF-4152] Moved core library docs into subfolders * [ADF-4152] Moved core library docs into subfolders * [ADF-4152] Manual fixes to core doc file links * [ADF-4152] Further automatic + manual link tidying
This commit is contained in:
Andy Stark
committed by
Eugenio Romano
Eugenio Romano
parent
285e56e9fb
commit
5fc05da7aa
139
docs/core/directives/check-allowable-operation.directive.md
Normal file
139
docs/core/directives/check-allowable-operation.directive.md
Normal file
@@ -0,0 +1,139 @@
|
||||
---
|
||||
Title: Check Allowable Operation directive
|
||||
Added: v2.0.0
|
||||
Status: Active
|
||||
Last reviewed: 2019-02-13
|
||||
---
|
||||
|
||||
# [Check Allowable Operation directive](../../../lib/core/directives/check-allowable-operation.directive.ts "Defined in check-allowable-operation.directive.ts")
|
||||
|
||||
Selectively disables an HTML element or Angular component.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Basic Usage](#basic-usage)
|
||||
- [Class members](#class-members)
|
||||
- [Properties](#properties)
|
||||
- [Details](#details)
|
||||
- [HTML element example](#html-element-example)
|
||||
- [Angular component example](#angular-component-example)
|
||||
- [Implementing the NodeAllowableOperationSubject interface](#implementing-the-nodeallowableoperationsubject-interface)
|
||||
- [Defining your component as an EXTENDIBLE_COMPONENT parent component](#defining-your-component-as-an-extendible_component-parent-component)
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```html
|
||||
<adf-toolbar title="toolbar example">
|
||||
<button mat-icon-button
|
||||
adf-check-allowable-operation="delete"
|
||||
[adf-nodes]="documentList.selection">
|
||||
<mat-icon>delete</mat-icon>
|
||||
</button>
|
||||
</adf-toolbar>
|
||||
|
||||
<adf-document-list #documentList ...>
|
||||
...
|
||||
</adf-document-list>
|
||||
```
|
||||
|
||||
## Class members
|
||||
|
||||
### Properties
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| ---- | ---- | ------------- | ----------- |
|
||||
| nodes | [`NodeEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md)`[]` | \[] | Nodes to check permission for. |
|
||||
| permission | `string` | null | [Node](https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/Node.md) permission to check (create, delete, update, updatePermissions, !create, !delete, !update, !updatePermissions). |
|
||||
|
||||
## Details
|
||||
|
||||
The [Check Allowable Operation Directive](check-allowable-operation.directive.md) lets you disable an HTML element or Angular component
|
||||
by taking a collection of [`NodeEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md) instances and checking their permissions.
|
||||
|
||||
The decorated element will be disabled if:
|
||||
|
||||
- there are no nodes in the collection
|
||||
- at least one of the nodes does not have the required permission
|
||||
|
||||
### HTML element example
|
||||
|
||||
A typical use case is to bind a [Document List](../../content-services/document-list.component.md)
|
||||
selection property to a toolbar button. In the following example, the "Delete" button should
|
||||
be disabled if no selection is present or if user does not have permission to delete at least one node in the selection:
|
||||
|
||||
```html
|
||||
<adf-toolbar title="toolbar example">
|
||||
<button mat-icon-button
|
||||
adf-check-allowable-operation="delete"
|
||||
[adf-nodes]="documentList.selection">
|
||||
<mat-icon>delete</mat-icon>
|
||||
</button>
|
||||
</adf-toolbar>
|
||||
|
||||
<adf-document-list #documentList ...>
|
||||
...
|
||||
</adf-document-list>
|
||||
```
|
||||
|
||||
The button will be disabled by default and will change state when the user selects or deselects
|
||||
one or more documents that they have permission to delete.
|
||||
|
||||
### Angular component example
|
||||
|
||||
You can add the directive to any Angular component that implements the [`NodeAllowableOperationSubject`](../../../lib/core/directives/check-allowable-operation.directive.ts)
|
||||
interface (the [Upload Drag Area component](../../content-services/upload-drag-area.component.md),
|
||||
for example). You can also use it in much the same way as you would with an HTML element:
|
||||
|
||||
```html
|
||||
<alfresco-upload-drag-area
|
||||
[rootFolderId]="..."
|
||||
[versioning]="..."
|
||||
[adf-check-allowable-operation]="'create'"
|
||||
[adf-nodes]="getCurrentDocumentListNode()">
|
||||
...
|
||||
</alfresco-upload-drag-area>
|
||||
```
|
||||
|
||||
To enable your own component to work with this directive, you need to implement the
|
||||
[`NodeAllowableOperationSubject`](../../../lib/core/directives/check-allowable-operation.directive.ts) interface and also define it as an
|
||||
[`EXTENDIBLE_COMPONENT`](../../../lib/core/interface/injection.tokens.ts)
|
||||
parent component,
|
||||
as described in the following sections.
|
||||
|
||||
### Implementing the NodeAllowableOperationSubject interface
|
||||
|
||||
The component must implement the [`NodeAllowableOperationSubject`](../../../lib/core/directives/check-allowable-operation.directive.ts) interface which means it must have a
|
||||
boolean `disabled` property. This is the property that will be set by the directive:
|
||||
|
||||
```js
|
||||
import { NodePermissionSubject } from '@alfresco/adf-core';
|
||||
|
||||
@Component({...})
|
||||
export class UploadDragAreaComponent implements NodeAllowableOperationSubject {
|
||||
public disabled: boolean = false;
|
||||
}
|
||||
```
|
||||
|
||||
### Defining your component as an EXTENDIBLE_COMPONENT parent component
|
||||
|
||||
The directive will look up the component in the dependency injection tree,
|
||||
up to the `@Host()` component. The host component is typically the component that requests
|
||||
the dependency. However, when this component is projected into a parent component, the
|
||||
parent becomes the host. This means you must provide your component with forward referencing
|
||||
as the
|
||||
[`EXTENDIBLE_COMPONENT`](../../../lib/core/interface/injection.tokens.ts)
|
||||
and also provide your component as a `viewProvider`:
|
||||
|
||||
```js
|
||||
import { EXTENDIBLE_COMPONENT } from '@alfresco/adf-core';
|
||||
|
||||
@Component({
|
||||
...
|
||||
viewProviders: [
|
||||
{ provide: EXTENDIBLE_COMPONENT, useExisting: forwardRef(() => UploadDragAreaComponent)}
|
||||
]
|
||||
})
|
||||
export class UploadDragAreaComponent implements NodeAllowableOperationSubject { ... }
|
||||
```
|
||||
|
||||
**Note:** the usage of **viewProviders** (instead of **providers**) is very important, especially if you want to use this directive on a transcluded component.
|
||||
58
docs/core/directives/context-menu.directive.md
Normal file
58
docs/core/directives/context-menu.directive.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
Title: Context Menu directive
|
||||
Added: v2.0.0
|
||||
Status: Active
|
||||
Last reviewed: 2018-11-20
|
||||
---
|
||||
|
||||
# [Context Menu directive](../../../lib/core/context-menu/context-menu.directive.ts "Defined in context-menu.directive.ts")
|
||||
|
||||
Adds a context menu to a component.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```html
|
||||
<my-component [adf-context-menu]="menuItems"></my-component>
|
||||
<adf-context-menu-holder></context-menu-holder>
|
||||
```
|
||||
|
||||
```ts
|
||||
@Component({
|
||||
selector: 'my-component'
|
||||
})
|
||||
export class MyComponent implements OnInit {
|
||||
|
||||
menuItems: any[];
|
||||
|
||||
constructor() {
|
||||
this.menuItems = [
|
||||
{ title: 'Item 1', subject: new Subject() },
|
||||
{ title: 'Item 2', subject: new Subject() },
|
||||
{ title: 'Item 3', subject: new Subject() }
|
||||
];
|
||||
}
|
||||
|
||||
ngOnInit() {
|
||||
this.menuItems.forEach(l => l.subject.subscribe(item => this.commandCallback(item)));
|
||||
}
|
||||
|
||||
commandCallback(item) {
|
||||
alert(`Executing ${item.title} command.`);
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
## Class members
|
||||
|
||||
### Properties
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| ---- | ---- | ------------- | ----------- |
|
||||
| enabled | `boolean` | false | Is the menu enabled? |
|
||||
| links | `any[]` | | Items for the menu. |
|
||||
|
||||
## Details
|
||||
|
||||
See the [Demo Shell](../../../demo-shell/README.md)
|
||||
or [Document List component](../../content-services/document-list.component.md) implementation for more details and use cases.
|
||||
74
docs/core/directives/highlight.directive.md
Normal file
74
docs/core/directives/highlight.directive.md
Normal file
@@ -0,0 +1,74 @@
|
||||
---
|
||||
Title: Highlight directive
|
||||
Added: v2.0.0
|
||||
Status: Active
|
||||
Last reviewed: 2018-11-20
|
||||
---
|
||||
|
||||
# [Highlight directive](../../../lib/core/directives/highlight.directive.ts "Defined in highlight.directive.ts")
|
||||
|
||||
Adds highlighting to selected sections of an HTML element's content.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```HTML
|
||||
<div
|
||||
[adf-highlight]="dance"
|
||||
adf-highlight-selector=".highlightable"
|
||||
adf-highlight-class="greenHighlight"
|
||||
>
|
||||
<div class="highlightable">You can dance if you want to</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
## Class members
|
||||
|
||||
### Properties
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| ---- | ---- | ------------- | ----------- |
|
||||
| classToApply | `string` | "adf-highlight" | CSS class used to apply highlighting. |
|
||||
| search | `string` | "" | Text to highlight. |
|
||||
| selector | `string` | "" | Class selector for highlightable elements. |
|
||||
|
||||
## Details
|
||||
|
||||
Add `adf-highlight` with a search term to an element to highlight occurrences
|
||||
of that term in its content. For example:
|
||||
|
||||
```HTML
|
||||
<div [adf-highlight]="'dance'" adf-highlight-selector=".highlightable">
|
||||
<div class="highlightable">
|
||||
You can dance if you want to
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
This will result in the word "dance" being highlighted. Note that you must also
|
||||
specify `adf-highlight-selector`, a CSS selector that specifies which
|
||||
elements can have their contents highlighted.
|
||||
|
||||
If the search string contain spaces then each section between the spaces will
|
||||
be treated as a separate item to highlight. For example, you could use this to
|
||||
highlight all occurrences of words in a list.
|
||||
|
||||
The highlighting works by adding an HTML <span> element around the
|
||||
selected text. The <span> includes a CSS class; this defaults to
|
||||
"adf-highlight" but you can supply your own class using the `adf-highlight-class`
|
||||
property:
|
||||
|
||||
```HTML
|
||||
<div
|
||||
[adf-highlight]="'dance'"
|
||||
adf-highlight-selector=".highlightable"
|
||||
adf-highlight-class="myGreenHighlight">
|
||||
<div class="highlightable">
|
||||
You can dance if you want to
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [Text highlight pipe](../pipes/text-highlight.pipe.md)
|
||||
- [Highlight transform service](../services/highlight-transform.service.md)
|
||||
28
docs/core/directives/logout.directive.md
Normal file
28
docs/core/directives/logout.directive.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
Title: Logout directive
|
||||
Added: v2.0.0
|
||||
Status: Active
|
||||
---
|
||||
|
||||
# [Logout directive](../../../lib/core/directives/logout.directive.ts "Defined in logout.directive.ts")
|
||||
|
||||
Logs the user out when the decorated element is clicked.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```html
|
||||
<button adf-logout>Logout</button>
|
||||
```
|
||||
|
||||
## Class members
|
||||
|
||||
### Properties
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| ---- | ---- | ------------- | ----------- |
|
||||
| enableRedirect | `boolean` | true | Enable redirecting after logout |
|
||||
| redirectUri | `string` | "/login" | URI to redirect to after logging out. |
|
||||
|
||||
## See also
|
||||
|
||||
- [Login component](../components/login.component.md)
|
||||
49
docs/core/directives/node-delete.directive.md
Normal file
49
docs/core/directives/node-delete.directive.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
Title: Node Delete directive
|
||||
Added: v2.0.0
|
||||
Status: Active
|
||||
Last reviewed: 2018-11-20
|
||||
---
|
||||
|
||||
# [Node Delete directive](../../../lib/core/directives/node-delete.directive.ts "Defined in node-delete.directive.ts")
|
||||
|
||||
Deletes multiple files and folders.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```html
|
||||
<adf-toolbar>
|
||||
<button mat-icon-button
|
||||
(delete)="documentList.reload()"
|
||||
[adf-delete]="documentList.selection">
|
||||
</button>
|
||||
</adf-toolbar>
|
||||
|
||||
<adf-document-list #documentList ...>
|
||||
...
|
||||
</adf-document-list>
|
||||
```
|
||||
|
||||
## Class members
|
||||
|
||||
### Properties
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| ---- | ---- | ------------- | ----------- |
|
||||
| permanent | `boolean` | false | If true then the nodes are deleted immediately rather than being put in the trash |
|
||||
| selection | [`NodeEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md)`[] \| DeletedNodeEntity[]` | | Array of nodes to delete. |
|
||||
|
||||
### Events
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
| delete | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<any>` | Emitted when the nodes have been deleted. |
|
||||
|
||||
## Details
|
||||
|
||||
Note that if a target item is already in the trashcan (and is therefore a `DeletedNodeEntity`) then
|
||||
this action will delete the file permanently.
|
||||
|
||||
## See also
|
||||
|
||||
- [Node Restore directive](node-restore.directive.md)
|
||||
33
docs/core/directives/node-download.directive.md
Normal file
33
docs/core/directives/node-download.directive.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
Title: Node Download directive
|
||||
Added: v2.2.0
|
||||
Status: Active
|
||||
Last reviewed: 2018-11-20
|
||||
---
|
||||
|
||||
# [Node Download directive](../../../lib/core/directives/node-download.directive.ts "Defined in node-download.directive.ts")
|
||||
|
||||
Allows folders and/or files to be downloaded, with multiple nodes packed as a '.ZIP' archive.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```html
|
||||
<adf-toolbar>
|
||||
<button mat-icon-button
|
||||
[adfNodeDownload]="documentList.selection">
|
||||
<mat-icon>get_app</mat-icon>
|
||||
</button>
|
||||
</adf-toolbar>
|
||||
|
||||
<adf-document-list #documentList ...>
|
||||
...
|
||||
</adf-document-list>
|
||||
```
|
||||
|
||||
## Class members
|
||||
|
||||
### Properties
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| ---- | ---- | ------------- | ----------- |
|
||||
| nodes | [`NodeEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md)` \| `[`NodeEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md)`[]` | | Nodes to download. |
|
||||
83
docs/core/directives/node-favorite.directive.md
Normal file
83
docs/core/directives/node-favorite.directive.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
Title: Node Favorite directive
|
||||
Added: v2.0.0
|
||||
Status: Active
|
||||
Last reviewed: 2018-11-13
|
||||
---
|
||||
|
||||
# [Node Favorite directive](../../../lib/core/directives/node-favorite.directive.ts "Defined in node-favorite.directive.ts")
|
||||
|
||||
Selectively toggles nodes as favorites.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```html
|
||||
<adf-toolbar>
|
||||
<button mat-icon-button
|
||||
(toggle)="done()"
|
||||
[adf-node-favorite]="documentList.selection">
|
||||
</button>
|
||||
</adf-toolbar>
|
||||
|
||||
<adf-document-list #documentList ...>
|
||||
...
|
||||
</adf-document-list>
|
||||
```
|
||||
|
||||
```ts
|
||||
@Component({
|
||||
selector: 'my-component'
|
||||
})
|
||||
export class MyComponent {
|
||||
|
||||
done() {
|
||||
// ...
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
## Class members
|
||||
|
||||
### Properties
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| ---- | ---- | ------------- | ----------- |
|
||||
| selection | [`NodeEntry`](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeEntry.md)`[]` | \[] | Array of nodes to toggle as favorites. |
|
||||
|
||||
### Events
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
| error | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<any>` | Emitted when the favorite setting fails. |
|
||||
| toggle | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<any>` | Emitted when the favorite setting is complete. |
|
||||
|
||||
## Details
|
||||
|
||||
You can bind the directive instance to a template variable through the **adfFavorite** reference,
|
||||
which also lets you add extra styling to the element:
|
||||
|
||||
<!-- {% raw %} -->
|
||||
|
||||
```html
|
||||
<button
|
||||
mat-menu-item
|
||||
#selection="adfFavorite"
|
||||
[ngClass]="{ 'icon-highlight': selection.hasFavorites() }"
|
||||
[adf-node-favorite]="documentList.selection">
|
||||
<mat-icon [ngClass]="{ 'icon-highlight': selection.hasFavorites() }">
|
||||
{{ selection.hasFavorites() ? 'star' : 'star_border' }}
|
||||
</mat-icon>
|
||||
</button>
|
||||
```
|
||||
|
||||
<!-- {% endraw %} -->
|
||||
|
||||
The directive behaves as follows:
|
||||
|
||||
- If there are no favorite nodes in the selection, then all are marked as favorites
|
||||
- If there are one or more favorite nodes in the selection, then only those that are not
|
||||
favorites are marked
|
||||
- If all nodes in the selection are favorites, then they all have their favorite status removed
|
||||
|
||||
See the **Demo Shell** for examples of usage.
|
||||
72
docs/core/directives/node-restore.directive.md
Normal file
72
docs/core/directives/node-restore.directive.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
Title: Node Restore directive
|
||||
Added: v2.0.0
|
||||
Status: Active
|
||||
Last reviewed: 2019-01-16
|
||||
---
|
||||
|
||||
# [Node Restore directive](../../../lib/core/directives/node-restore.directive.ts "Defined in node-restore.directive.ts")
|
||||
|
||||
Restores deleted nodes to their original location.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```html
|
||||
<adf-toolbar title="toolbar example">
|
||||
<button mat-icon-button
|
||||
[adf-restore]="documentList.selection"
|
||||
(restore)="onRestore($event)">
|
||||
<mat-icon>restore</mat-icon>
|
||||
</button>
|
||||
</adf-toolbar>
|
||||
|
||||
<adf-document-list #documentList
|
||||
currentFolderId="-trash-" ...>
|
||||
...
|
||||
</adf-document-list>
|
||||
```
|
||||
|
||||
```ts
|
||||
onRestore(restoreMessage: RestoreMessageModel) {
|
||||
this.notificationService
|
||||
.openSnackMessageAction(
|
||||
restoreMessage.message,
|
||||
restoreMessage.action
|
||||
)
|
||||
.onAction()
|
||||
.subscribe(() => this.navigateLocation(restoreMessage.path));
|
||||
this.documentList.reload();
|
||||
}
|
||||
|
||||
navigateLocation(path: PathInfoEntity) {
|
||||
const parent = path.elements[path.elements.length - 1];
|
||||
this.router.navigate(['files/', parent.id]);
|
||||
}
|
||||
```
|
||||
|
||||
## Class members
|
||||
|
||||
### Properties
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| ---- | ---- | ------------- | ----------- |
|
||||
| selection | [`DeletedNodeEntry`](https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/DeletedNodeEntry.md)`[]` | | Array of deleted nodes to restore. |
|
||||
|
||||
### Events
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
| restore | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`RestoreMessageModel`](../../../lib/core/directives/node-restore.directive.ts)`>` | Emitted when restoration is complete. |
|
||||
|
||||
## Details
|
||||
|
||||
The directive takes a selection of [`DeletedNodeEntry`](https://github.com/Alfresco/alfresco-js-api/blob/development/src/api/content-rest-api/docs/DeletedNodeEntry.md) instances and restores them to
|
||||
their original locations. If the original location doesn't exist anymore then they remain
|
||||
in the trash list.
|
||||
|
||||
When you restore a single node, you can use the `location` property to show where the node has
|
||||
been restored. The property specifies the route path where the list of nodes are rendered.
|
||||
|
||||
## See Also
|
||||
|
||||
- [Node delete directive](node-delete.directive.md)
|
||||
194
docs/core/directives/upload.directive.md
Normal file
194
docs/core/directives/upload.directive.md
Normal file
@@ -0,0 +1,194 @@
|
||||
---
|
||||
Title: Upload Directive
|
||||
Added: v2.0.0
|
||||
Status: Active
|
||||
Last reviewed: 2018-11-20
|
||||
---
|
||||
|
||||
# [Upload Directive](../../../lib/core/directives/upload.directive.ts "Defined in upload.directive.ts")
|
||||
|
||||
Uploads content in response to file drag and drop.
|
||||
|
||||
## Basic usage
|
||||
|
||||
```html
|
||||
<button [adf-upload]="true" [multiple]="true" [accept]="'image/*'">
|
||||
Upload photos
|
||||
</button>
|
||||
```
|
||||
|
||||
## Class members
|
||||
|
||||
### Properties
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| ---- | ---- | ------------- | ----------- |
|
||||
| accept | `string` | | (Click mode only) MIME type filter for files to accept. |
|
||||
| data | `any` | | Data to upload. |
|
||||
| directory | `boolean` | | (Click mode only) Toggles uploading of directories. |
|
||||
| enabled | `boolean` | true | Enables/disables uploading. |
|
||||
| mode | `string[]` | ['drop'] | Upload mode. Can be "drop" (receives dropped files) or "click" (clicking opens a file dialog). Both modes can be active at once. |
|
||||
| multiple | `boolean` | | Toggles multiple file uploads. |
|
||||
|
||||
## Details
|
||||
|
||||
Add the directive to a component or HTML element to enable it to upload files.
|
||||
You can decorate any element including buttons:
|
||||
|
||||
```html
|
||||
<button [adf-upload]="true" [multiple]="true" [accept]="'image/*'">
|
||||
Upload photos
|
||||
</button>
|
||||
```
|
||||
|
||||
The directive itself does not do any file management, but it collects information about
|
||||
dropped files and emits events in response.
|
||||
|
||||
```html
|
||||
<div style="width:100px; height:100px"
|
||||
[adf-upload]="true"
|
||||
[adf-upload-data]="{ some: 'data' }">
|
||||
Drop files here...
|
||||
</div>
|
||||
```
|
||||
|
||||
You can enable or disable upload functionality by binding the directive to a boolean
|
||||
value or expression:
|
||||
|
||||
```html
|
||||
<div [adf-upload]="true">...</div>
|
||||
<div [adf-upload]="allowUpload">...</div>
|
||||
<div [adf-upload]="isUploadEnabled()">...</div>
|
||||
```
|
||||
|
||||
### Modes
|
||||
|
||||
The [Upload directive](upload.directive.md) supports two modes:
|
||||
|
||||
- **drop** mode, where the decorated element acts like a drop zone for files (enabled by default)
|
||||
- **click** mode, where the decorated element invokes a file dialog to select files or folders.
|
||||
|
||||
You can also use both modes together:
|
||||
|
||||
```html
|
||||
<div [adf-upload]="true" mode="['click']">...</div>
|
||||
<div [adf-upload]="true" mode="['drop']">...</div>
|
||||
<div [adf-upload]="true" mode="['click', 'drop']">...</div>
|
||||
```
|
||||
|
||||
#### Click mode
|
||||
|
||||
In click mode you can provide extra attributes for the file dialog:
|
||||
|
||||
- **directory**, enables directory selection
|
||||
- **multiple**, enables multiple file/folder selection
|
||||
- **accept**, filters the content accepted
|
||||
|
||||
```html
|
||||
<div style="width: 50px; height: 50px; background-color: brown"
|
||||
[adf-upload]="true"
|
||||
[multiple]="true"
|
||||
[accept]="'image/*'">
|
||||
</div>
|
||||
|
||||
<div style="width: 50px; height: 50px; background-color: blueviolet"
|
||||
[adf-upload]="true"
|
||||
[multiple]="true"
|
||||
[directory]="true">
|
||||
</div>
|
||||
```
|
||||
|
||||
#### Drop mode
|
||||
|
||||
Currently, the [upload directive](upload.directive.md) supports only file drops (single or multiple).
|
||||
Support for folders and `accept` filters will probably be implemented in a
|
||||
future version.
|
||||
|
||||
### Events
|
||||
|
||||
The `upload-files` [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent)
|
||||
is emitted when single or multiple files are dropped on the decorated element.
|
||||
The DOM event is configured to have `bubbling` enabled, so any component up the component tree can handle, process or prevent it:
|
||||
|
||||
```html
|
||||
<div (upload-files)="onUploadFiles($event)">
|
||||
<div [adf-upload]="true"></div>
|
||||
</div>
|
||||
```
|
||||
|
||||
```ts
|
||||
onUploadFiles(e: CustomEvent) {
|
||||
console.log(e.detail.files);
|
||||
|
||||
// your code
|
||||
}
|
||||
```
|
||||
|
||||
Note that the event will be emitted only if valid
|
||||
[files](https://developer.mozilla.org/en-US/docs/Web/API/File)
|
||||
are dropped onto the decorated element.
|
||||
|
||||
The `upload-files` event is cancellable, so you can stop propagation of the drop event upwards
|
||||
when it has been handled by your code:
|
||||
|
||||
```ts
|
||||
onUploadFiles(e: CustomEvent) {
|
||||
e.stopPropagation();
|
||||
e.preventDefault();
|
||||
|
||||
// your code
|
||||
}
|
||||
```
|
||||
|
||||
You can also attach arbitrary data to each event which you can then access from external event handlers. A typical scenario is with data tables where you may want to make use of the data row
|
||||
or make underlying data accessible when files are dropped.
|
||||
|
||||
You can use `adf-upload-data` to bind custom values or objects for every event raised:
|
||||
|
||||
```html
|
||||
<div [adf-upload]="true" [adf-upload-data]="dataRow"></div>
|
||||
<div [adf-upload]="true" [adf-upload-data]="'string value'"></div>
|
||||
<div [adf-upload]="true" [adf-upload-data]="{ name: 'custom object' }"></div>
|
||||
<div [adf-upload]="true" [adf-upload-data]="getUploadData()"></div>
|
||||
```
|
||||
|
||||
You can access the following items of the `details` property from the
|
||||
[CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent):
|
||||
|
||||
```ts
|
||||
detail: {
|
||||
sender: UploadDirective, // directive that raised given event
|
||||
data: any, // arbitrary data associated (bound)
|
||||
files: File[] // dropped files
|
||||
}
|
||||
```
|
||||
|
||||
### Styling
|
||||
|
||||
The decorated element is styled with the `adf-upload__dragging` CSS class whenever a file is dragged
|
||||
over it. This lets you change the look and feel of your components when you need different visual
|
||||
indication. For example, you could draw a dashed border around a table row when an item is dragged
|
||||
onto it:
|
||||
|
||||
```html
|
||||
<table>
|
||||
<tr [adf-upload]="true">
|
||||
...
|
||||
</tr>
|
||||
</table>
|
||||
```
|
||||
|
||||
```css
|
||||
.adf-upload__dragging > td:first-child {
|
||||
border-left: 1px dashed rgb(68,138,255);
|
||||
}
|
||||
|
||||
.adf-upload__dragging > td {
|
||||
border-top: 1px dashed rgb(68,138,255);
|
||||
border-bottom: 1px dashed rgb(68,138,255);
|
||||
}
|
||||
|
||||
.adf-upload__dragging > td:last-child {
|
||||
border-right: 1px dashed rgb(68,138,255);
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user