From 6dc14eb2e01bd4147edd295c7fc0a6da64787c7f Mon Sep 17 00:00:00 2001 From: Andy Stark <30621568+therealandeeee@users.noreply.github.com> Date: Tue, 23 Jan 2018 17:38:33 +0000 Subject: [PATCH] [ADF-2201] Tidied Content Node Dialog docs (#2870) --- docs/README.md | 4 +- docs/content-node-dialog.service.md | 69 ++++++++ docs/content-node-selector-panel.component.md | 47 ++++++ docs/content-node-selector.component.md | 150 ++++++------------ 4 files changed, 165 insertions(+), 105 deletions(-) create mode 100644 docs/content-node-dialog.service.md create mode 100644 docs/content-node-selector-panel.component.md diff --git a/docs/README.md b/docs/README.md index b4cd923fcf..d9312e1e02 100644 --- a/docs/README.md +++ b/docs/README.md @@ -174,6 +174,7 @@ for more information about installing and using the source code. | [Breadcrumb component](breadcrumb.component.md) | Indicates the current position within a navigation hierarchy. | [Source](../lib/content-services/breadcrumb/breadcrumb.component.ts) | | [Dropdown breadcrumb component](dropdown-breadcrumb.component.md) | Indicates the current position within a navigation hierarchy using a dropdown menu. | [Source](../lib/content-services/breadcrumb/dropdown-breadcrumb.component.ts) | | [Content metadata component](content-metadata.component.md) | Allows a user to display and edit metadata related to a node. | [Source](../lib/content-services/content-metadata/components/content-metadata/content-metadata.component.ts) | +| [Content node selector panel component](content-node-selector-panel.component.md) | Opens a [Content Node Selector](content-node-selector.component.md) in its own dialog window. | [Source](../lib/content-services/content-node-selector/content-node-selector-panel.component.ts) | | [Content node selector component](content-node-selector.component.md) | Allows a user to select items from a Content Services repository. | [Source](../lib/content-services/content-node-selector/content-node-selector.component.ts) | | [Content action component](content-action.component.md) | Adds options to a Document List actions menu for a particular content type. | [Source](../lib/content-services/document-list/components/content-action/content-action.component.ts) | | [Document list component](document-list.component.md) | Displays the documents from a repository. | [Source](../lib/content-services/document-list/components/document-list.component.ts) | @@ -192,7 +193,6 @@ for more information about installing and using the source code. | [Version manager component](version-manager.component.md) | Displays the version history of a node with the ability to upload a new version. | [Source](../lib/content-services/version-manager/version-manager.component.ts) | | [Webscript component](webscript.component.md) | Provides access to Webscript features. | [Source](../lib/content-services/webscript/webscript.component.ts) | | _Content metadata card component_ | _Not currently documented_ | [Source](../lib/content-services/content-metadata/components/content-metadata-card/content-metadata-card.component.ts) | -| _Content node selector panel component_ | _Not currently documented_ | [Source](../lib/content-services/content-node-selector/content-node-selector-panel.component.ts) | ## Directives @@ -213,6 +213,7 @@ for more information about installing and using the source code. | Name | Description | Source link | | ---- | ----------- | ----------- | +| [Content node dialog service](content-node-dialog.service.md) | Displays and manages dialogs for selecting content to open, copy or upload. | [Source](../lib/content-services/content-node-selector/content-node-dialog.service.ts) | | [Document actions service](document-actions.service.md) | Implements the document menu actions for the Document List component. | [Source](../lib/content-services/document-list/services/document-actions.service.ts) | | [Document list service](document-list.service.md) | Implements node operations used by the Document List component. | [Source](../lib/content-services/document-list/services/document-list.service.ts) | | [Folder actions service](folder-actions.service.md) | Implements the folder menu actions for the Document List component. | [Source](../lib/content-services/document-list/services/folder-actions.service.ts) | @@ -223,7 +224,6 @@ for more information about installing and using the source code. | _Content metadata service_ | _Not currently documented_ | [Source](../lib/content-services/content-metadata/services/content-metadata.service.ts) | | _Properties loader service_ | _Not currently documented_ | [Source](../lib/content-services/content-metadata/services/properties-loader.service.ts) | | _Property descriptors service_ | _Not currently documented_ | [Source](../lib/content-services/content-metadata/services/property-descriptors.service.ts) | -| _Content node dialog service_ | _Not currently documented_ | [Source](../lib/content-services/content-node-selector/content-node-dialog.service.ts) | diff --git a/docs/content-node-dialog.service.md b/docs/content-node-dialog.service.md new file mode 100644 index 0000000000..edb0a17451 --- /dev/null +++ b/docs/content-node-dialog.service.md @@ -0,0 +1,69 @@ +# Content Node Dialog service + +Displays and manages dialogs for selecting content to open, copy or upload. + +## Methods + +`openFileBrowseDialogByFolderId(folderNodeId: string): Observable`
+Opens a file browser at a chosen folder location. + +`openFolderBrowseDialogByFolderId(folderNodeId: string): Observable`
+Opens a folder browser at a chosen folder location. + +`openFileBrowseDialogBySite(): Observable`
+Opens a file browser at a chosen site location. + +`openFolderBrowseDialogBySite(): Observable`
+Opens a folder browser at a chosen site location. + +`openCopyMoveDialog(action: string, contentEntry: MinimalNodeEntryEntity, permission?: string): Observable`
+Opens a dialog to copy or move an item to a new location. + +`openUploadFileDialog(action: string, contentEntry: MinimalNodeEntryEntity): Observable`
+Opens a dialog to choose a file to upload. + +`openUploadFolderDialog(action: string, contentEntry: MinimalNodeEntryEntity): Observable`
+Opens a dialog to choose a folder to upload. + +`close()`
+Closes the currently open dialog. + +## Details + +The `openXXX` methods return an +[Observable](http://reactivex.io/rxjs/manual/overview.html#observable) that you can subscribe +to in order to get the information from the result: + +```ts +import { ContentNodeDialogService } from '@adf/content-services' + + +constructor(private contentDialogService: ContentNodeDialogService){} + +yourFunctionOnCopyOrMove(){ + this.contentDialogService + .openCopyMoveDialog(actionName, targetNode, neededPermissionForAction) + .subscribe((selections: MinimalNodeEntryEntity[]) => { + // place your action here on operation success! + }); +} +``` + +The `openXXXByFolderId` methods let you set the initial folder location of the browser +using a folder ID string. This can be obtained from the `id` property of a +[MinimalNodeEntryEntity](document-library.model.md) object (returned from a previous +dialog operation, say) or be set to one of the well-known names "-my-" , "-shared-" or +"-root-". + +The `openCopyMoveDialog` and `openUploadXXX` methods require the following parameters: + +| Name | Type | Description | +| ---- | ---- | ----------- | +| action | string | The label for the confirm button of the dialog. | +| contentEntry | [MinimalNodeEntryEntity](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/MinimalNode.md) | The node we want to be copied/moved or uploaded. | +| neededPermissionForAction | string | (`openCopyMoveDialog` only) Permission required to perform the relative action (eg: copy will need the 'update' permission ). | + +## See Also + +- [Content node selector panel component](content-node-selector-panel.component.md) +- [Content node selector component](content-node-selector.component.md) diff --git a/docs/content-node-selector-panel.component.md b/docs/content-node-selector-panel.component.md new file mode 100644 index 0000000000..afea02f65e --- /dev/null +++ b/docs/content-node-selector-panel.component.md @@ -0,0 +1,47 @@ +# Content Node Selector Panel component + +Opens a [Content Node Selector](content-node-selector.component.md) in its own dialog window. + +## Basic Usage + +```html + + +``` + +### Properties + +| Name | Type | Default | Description | +| ---- | ---- | ------- | ----------- | +| currentFolderId | string | null | Node ID of the folder currently listed | +| dropdownHideMyFiles | boolean | false | Hide the "My Files" option added to the site list by default. [See More](sites-dropdown.component.md) | +| dropdownSiteList | [SitePaging](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/SitePaging.md) | | custom site for site dropdown same as siteList. [See More](sites-dropdown.component.md#properties) | +| rowFilter | RowFilter | null | Custom row filter function. [See More](document-list.component.md#custom-row-filter) | +| imageResolver | ImageResolver | null | Custom image resolver function. [See More](document-list.component.md#custom-image-resolver) | +| pageSize | number | 10 | Number of items shown per page in the list | + +### Events + +| Name | Description | +| ---- | ----------- | +| select | Emitted when the user has selected an item | + +## Details + +This component opens a _content node selector_ in its own dialog window. This behaves a lot like the +standard file open/save dialogs used by applications to choose files. Full details are given in the +[Content Node Selector component](content-node-selector.component.md) page (this is similar but does +not manage the dialog window for you). Also, the +[Content Node Dialog service](content-node-dialog.service.md) has several methods that give you +finer control over the behavior of the dialog. + +## See also + +- [Content Node Selector component](content-node-selector.component.md) +- [Content Node Dialog service](content-node-dialog.service.md) diff --git a/docs/content-node-selector.component.md b/docs/content-node-selector.component.md index 56265fa44d..db45add79b 100644 --- a/docs/content-node-selector.component.md +++ b/docs/content-node-selector.component.md @@ -6,38 +6,56 @@ Allows a user to select items from a Content Services repository. ## Basic Usage -The component is showed within a material [dialog window](https://material.angular.io/components/dialog/overview) with two action available and it can be opened with the following ways: +### Properties -### Using Content node dialog service - recommended +| Name | Type | Default | Description | +| ---- | ---- | ------- | ----------- | +| title | string | "" | Text shown at the top of the selector | +| currentFolderId | string | null | Node ID of the folder currently listed | +| dropdownHideMyFiles | boolean | false | Hide the "My Files" option added to the site list by default. [See More](sites-dropdown.component.md) | +| dropdownSiteList | [SitePaging](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/SitePaging.md) | | custom site for site dropdown same as siteList. [See More](sites-dropdown.component.md#properties) | +| rowFilter | RowFilter | null | Custom row filter function. [See More](document-list.component.md#custom-row-filter) | +| imageResolver | ImageResolver | null | Custom image resolver function. [See More](document-list.component.md#custom-image-resolver) | +| pageSize | number | 10 | Number of items shown per page in the list | + +### Events + +| Name | Description | +| ---- | ----------- | +| select | Emitted when the user has selected an item | + +## Details + +The Content Node Selector component works a lot like the standard File Open/Save +dialog used by desktop applications except that it chooses items from a Content Services +repository rather than the filesystem. For example, the +[Document List component](document-list.component.md) uses a selector to choose the targets +of Copy/Move actions (see the [Content Action component](content-action.component.md) for +more information). + +Unlike most components, the Content Node Selector is typically shown in a dialog box +rather than the main page and you are responsible for opening the dialog yourself. You can use the +[Angular Material Dialog](https://material.angular.io/components/dialog/overview) for this, +as shown in the usage example. ADF provides the `ContentNodeSelectorComponentData` interface +to work with the Dialog's +[data option](https://material.angular.io/components/dialog/overview#sharing-data-with-the-dialog-component-): ```ts -import { ContentNodeDialogService } from '@adf/content-services' - - -constructor(private contentDialogService: ContentNodeDialogService){} - -yourFunctionOnCopyOrMove(){ - this.contentDialogService - .openCopyMoveDialog(actionName, targetNode, neededPermissionForAction) - .subscribe((selections: MinimalNodeEntryEntity[]) => { - // place your action here on operation success! - }); +interface ContentNodeSelectorComponentData { + title: string; + currentFolderId?: string; + rowFilter?: RowFilter; + imageResolver?: ImageResolver; + select: EventEmitter; } ``` -#### Required parameters +If you don't want to manage the dialog yourself then it is easier to use the +[Content Node Selector Panel component](content-node-selector-panel.component.md), or the +methods of the [Content Node Dialog service](content-node-dialog.service.md), which create +the dialog for you. -The dialog needs this information to be correctly opened : - -| Name | Type | Description | -| ---- | ---- | ----------- | -| actionName | string | This will be the label for the confirm button of the dialog | -| targetNode | [MinimalNodeEntryEntity](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/MinimalNode.md) | the node on which we are asking for copy/move action | -| neededPermissionForAction | string | needed permission to check to perform the relative action (es: copy will need the 'update' permission ) | - -the `openCopyMoveDialog` method will return an [observable](http://reactivex.io/rxjs/manual/overview.html#observable) that can where you can subscribe to get the selection result and apply the custom actions. - -### Using ContentNodeSelectorComponent +### Usage example ```ts import { MatDialog } from '@angular/material'; @@ -75,84 +93,8 @@ openSelectorDialog() { } ``` -With this system your function has to take care of opening/closing the dialog. All the results will be streamed on the select [subject](http://reactivex.io/rxjs/manual/overview.html#subject) present into the `ContentNodeSelectorComponentData` object given to the dialog. -When clicked on the action the data.select stream will be completed. - -### Properties - -| Name | Type | Default | Description | -| ---- | ---- | ------- | ----------- | -| title | string | "" | Text shown at the top of the selector | -| currentFolderId | string | null | Node ID of the folder currently listed | -| dropdownHideMyFiles | boolean | false | Hide the "My Files" option added to the site list by default. [See More](https://github.com/Alfresco/alfresco-ng2-components/blob/master/docs/sites-dropdown.component.md) | -| dropdownSiteList | [SitePaging](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/SitePaging.md) | | custom site for site dropdown same as siteList. [See More](https://github.com/Alfresco/alfresco-ng2-components/blob/master/docs/sites-dropdown.component.md#properties) | -| rowFilter | RowFilter | null | Custom row filter function. [See More](https://github.com/Alfresco/alfresco-ng2-components/blob/master/docs/document-list.component.md#custom-row-filter) | -| imageResolver | ImageResolver | null | Custom image resolver function. [See More](https://github.com/Alfresco/alfresco-ng2-components/blob/master/docs/document-list.component.md#custom-image-resolver) | -| pageSize | number | 10 | Number of items shown per page in the list | - -### Events - -| Name | Description | -| ---- | ----------- | -| select | Emitted when the user has selected an item | - -### Using ContentNodeSelectorPanelComponent - -```html - - -``` - -This will allow you to use the content node selector without the material dialog. - -### Properties - -| Name | Type | Default | Description | -| ---- | ---- | ------- | ----------- | -| currentFolderId | string | null | Node ID of the folder currently listed | -| dropdownHideMyFiles | boolean | false | Hide the "My Files" option added to the site list by default. [See More](https://github.com/Alfresco/alfresco-ng2-components/blob/master/docs/sites-dropdown.component.md) | -| dropdownSiteList | [SitePaging](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/SitePaging.md) | | custom site for site dropdown same as siteList. [See More](https://github.com/Alfresco/alfresco-ng2-components/blob/master/docs/sites-dropdown.component.md#properties) | -| rowFilter | RowFilter | null | Custom row filter function. [See More](https://github.com/Alfresco/alfresco-ng2-components/blob/master/docs/document-list.component.md#custom-row-filter) | -| imageResolver | ImageResolver | null | Custom image resolver function. [See More](https://github.com/Alfresco/alfresco-ng2-components/blob/master/docs/document-list.component.md#custom-image-resolver) | -| pageSize | number | 10 | Number of items shown per page in the list | - -### Events - -| Name | Description | -| ---- | ----------- | -| select | Emitted when the user has selected an item | - -## Details - -The Content Node Selector component works a lot like the standard File Open/Save -dialog used by desktop applications except that it chooses items from a Content Services -repository rather than the filesystem. For example, the -[Document List component](document-list.component.md) uses a selector to choose the targets -of Copy/Move actions (see the [Content Action component](content-action.component.md) for -more information). - -Unlike most components, the Content Node Selector is typically shown in a dialog box -rather than the main page. You can use the -[Angular Material Dialog](https://material.angular.io/components/dialog/overview) for this, -as shown in the usage example. ADF provides the `ContentNodeSelectorComponentData` interface -to work with the Dialog's -[data option](https://material.angular.io/components/dialog/overview#sharing-data-with-the-dialog-component-): - -```ts -interface ContentNodeSelectorComponentData { - title: string; - currentFolderId?: string; - rowFilter?: RowFilter; - imageResolver?: ImageResolver; - select: EventEmitter; -} -``` +All the results will be streamed to the select [subject](http://reactivex.io/rxjs/manual/overview.html#subject) present in the `ContentNodeSelectorComponentData` object passed to the dialog. +When the dialog action is selected by clicking, the `data.select` stream will be completed. ### RowFilter and ImageResolver @@ -167,3 +109,5 @@ section of the Document List page to learn how these functions are implemented. ## See also - [Document list component](document-list.component.md) +- [Content Node Selector Panel component](content-node-selector-panel.component.md) +- [Content Node Dialog service](content-node-dialog.service.md)