[ADF-1586] Added docs for Core services (#2548)

2025-05-12 17:04:57 +00:00 · 2017-10-26 10:47:44 +01:00 · 2017-10-26 10:47:44 +01:00 · 3aa2724d25
commit 3aa2724d25
parent 851a0cfdb3
9 changed files with 402 additions and 6 deletions
--- a/docs/README.md
+++ b/docs/README.md
@ -337,12 +337,12 @@ for more information about installing and using the source code.

 ### Pipes

+- [File size pipe](file-size.pipe.md)
 - [Mime type icon pipe](mime-type-icon.pipe.md)
 - [Node name tooltip pipe](node-name-tooltip.pipe.md)
 - [Text highlight pipe](text-highlight.pipe.md)
- [*File size pipe](../ng2-components/ng2-alfresco-core/src/pipes/file-size.pipe.ts)
- [*Time ago pipe](../ng2-components/ng2-alfresco-core/src/pipes/time-ago.pipe.ts)
- [*User initial pipe](../ng2-components/ng2-alfresco-core/src/pipes/user-initial.pipe.ts)
+- [Time ago pipe](time-ago.pipe.md)
+- [User initial pipe](user-initial.pipe.md)

 ### Services

@ -350,8 +350,10 @@ for more information about installing and using the source code.
 - [App config service](app-config.service.md)
 - [Authentication service](authentication.service.md)
 - [Card view update service](card-view-update.service.md)
+- [Deleted nodes api service](deleted-nodes-api.service.md)
 - [Highlight transform service](highlight-transform.service.md)
 - [Log service](log.service.md)
+- [Nodes api service](nodes-api.service.md)
 - [Notification service](notification.service.md)
 - [Renditions service](renditions.service.md)
 - [Thumbnail service](thumbnail.service.md)
@ -368,10 +370,8 @@ for more information about installing and using the source code.
 - [*Comment process service](../ng2-components/ng2-alfresco-core/src/services/comment-process.service.ts)
 - [*Content service](../ng2-components/ng2-alfresco-core/src/services/content.service.ts)
 - [*Cookie service](../ng2-components/ng2-alfresco-core/src/services/cookie.service.ts)
- [*Deleted nodes api service](../ng2-components/ng2-alfresco-core/src/services/deleted-nodes-api.service.ts)
 - [*Discovery api service](../ng2-components/ng2-alfresco-core/src/services/discovery-api.service.ts)
 - [*Favorites api service](../ng2-components/ng2-alfresco-core/src/services/favorites-api.service.ts)
- [*Nodes api service](../ng2-components/ng2-alfresco-core/src/services/nodes-api.service.ts)
 - [*Page title service](../ng2-components/ng2-alfresco-core/src/services/page-title.service.ts)
 - [*People content service](../ng2-components/ng2-alfresco-core/src/services/people-content.service.ts)
 - [*People process service](../ng2-components/ng2-alfresco-core/src/services/people-process.service.ts)
@ -425,6 +425,7 @@ for more information about installing and using the source code.

 ### Models

+- [Document library model](document-library.model.md)
 - [Permissions style model](permissions-style.model.md)

 ### Services
--- a/docs/deleted-nodes-api.service.md
+++ b/docs/deleted-nodes-api.service.md
@ -0,0 +1,26 @@
+# Deleted Nodes Api service
+
+Gets a list of Content Services nodes currently in the trash.
+
+## Methods
+
+`getDeletedNodes(options?: Object): Observable<NodePaging>`<br/>
+Gets a list of nodes in the trash.
+
+## Details
+
+The `getDeletedNodes` method returns a NodePaging object that lists
+the items in the trash (see [Document Library model](document-library.model.md) for
+more information about this class). The format of the `options` parameter is
+described in the [getDeletedNodes](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodesApi.md#getDeletedNodes)
+page of the Alfresco JS API docs.
+
+<!-- Don't edit the See also section. Edit seeAlsoGraph.json and run config/generateSeeAlso.js -->
+<!-- seealso start -->
+## See also
+
+- [Nodes api service](nodes-api.service.md)
+<!-- seealso end -->
+
+
+
--- a/docs/document-library.model.md
+++ b/docs/document-library.model.md
@ -0,0 +1,113 @@
+# Document Library model
+
+Defines classes for use with the Content Services node API.
+
+## Details
+
+ADF provides several services that give higher-level access to
+underlying [Alfresco JS Api](alfresco-api.service.md) functionality.
+The classes defined below are used in some of these services to access
+the Content Services nodes API. You can use these services to access
+the nodes (ie, documents and folders) of a repository using their
+associated ID strings. See [Nodes Api service](nodes-api.service.md)
+for more detail about the usage of these classes.
+
+## Node information
+
+These classes contain basic information about nodes (see
+[Item information](#item-information) below for more detail
+about some of the properties). For example, this is used by the
+[Document List component](document-list.component.md) to supply
+a [data context](document-list.component.md#underlying-node-object)
+for each row of the list. The [Nodes Api service](nodes-api.service.md)
+has methods for getting the full information for a node ID string.
+
+```ts
+class NodeMinimalEntry implements MinimalNodeEntity {
+    entry: NodeMinimal;
+}
+
+class NodeMinimal implements MinimalNodeEntryEntity {
+    id: string;
+    parentId: string;
+    name: string;
+    nodeType: string;
+    isFolder: boolean;
+    isFile: boolean;
+    modifiedAt: Date;
+    modifiedByUser: UserInfo;
+    createdAt: Date;
+    createdByUser: UserInfo;
+    content: ContentInfo;
+    path: PathInfoEntity;
+    properties: NodeProperties = {};
+}
+
+interface NodeProperties {
+    [key: string]: any;
+}
+```
+
+## Paging
+
+These classes are used to handle a list of nodes, such as the
+contents of a folder node. For example, the `node` property of
+the [Document List component](document-list.component.md) contains
+the node whose contents are currently shown in the document list.
+
+```ts
+class NodePaging {
+    list: NodePagingList;
+}
+
+class NodePagingList {
+    pagination: Pagination;
+    entries: NodeMinimalEntry[];
+}
+
+class Pagination {
+    count: number;
+    hasMoreItems: boolean;
+    totalItems: number;
+    skipCount: number;
+    maxItems: number;
+}
+```
+
+## Item information
+
+These classes hold information about specific items related to
+a node.
+
+```ts
+class UserInfo {
+    displayName: string;
+    id: string;
+}
+
+class ContentInfo {
+    mimeType: string;
+    mimeTypeName: string;
+    sizeInBytes: number;
+    encoding: string;
+}
+
+class PathInfoEntity {
+    elements: PathElementEntity[];
+    isComplete: boolean;
+    name: string;
+}
+
+class PathElementEntity {
+    id: string;
+    name: string;
+}
+```
+
+<!-- Don't edit the See also section. Edit seeAlsoGraph.json and run config/generateSeeAlso.js -->
+<!-- seealso start -->
+## See also
+
+- [Document list component](document-list.component.md)
+- [Nodes api service](nodes-api.service.md)
+<!-- seealso end -->
--- a/docs/document-list.component.md
+++ b/docs/document-list.component.md
@ -721,6 +721,8 @@ That will give the following output:
 - [Pagination component](pagination.component.md)
 - [Sites dropdown component](sites-dropdown.component.md)
 - [Metadata indicators](metadata-indicators.md)
+- [Document library model](document-library.model.md)
+- [Nodes api service](nodes-api.service.md)
 - [Breadcrumb component](breadcrumb.component.md)
 - [Content action component](content-action.component.md)
 - [Dropdown breadcrumb component](dropdown-breadcrumb.component.md)
--- a/docs/file-size.pipe.md
+++ b/docs/file-size.pipe.md
@ -0,0 +1,23 @@
+# File Size pipe
+
+Converts a number of bytes to the equivalent in KB, MB, etc.
+
+## Basic Usage
+
+```HTML
+<div>
+    File Size: {{ sizeInBytes | adfFileSize:"2" }}
+</div>
+```
+
+## Details
+
+The pipe chooses the largest unit that is less than the total number of bytes and
+divides the total by this number. This ensures that the number of units is greater
+than 1 (eg, you will see "512 Bytes" rather than "0.5KB"). The pipe parameter indicates
+the number of decimal places to use for the value, defaulting to 2 decimal places.
+
+<!-- Don't edit the See also section. Edit seeAlsoGraph.json and run config/generateSeeAlso.js -->
+<!-- seealso start -->
+
+<!-- seealso end -->
--- a/docs/nodes-api.service.md
+++ b/docs/nodes-api.service.md
@ -0,0 +1,178 @@
+# Nodes Api service
+
+Accesses and manipulates ACS document nodes using their node IDs.
+
+<!-- markdown-toc start - Don't edit this section.  npm run toc to generate it-->
+
+<!-- toc -->
+
+- [Methods](#methods)
+- [Details](#details)
+  * [Getting node information](#getting-node-information)
+  * [Getting folder node contents](#getting-folder-node-contents)
+  * [Creating and updating nodes](#creating-and-updating-nodes)
+  * [Deleting and restoring nodes](#deleting-and-restoring-nodes)
+- [See also](#see-also)
+
+<!-- tocstop -->
+
+<!-- markdown-toc end -->
+
+## Methods
+
+`getNode(nodeId: string, options: any = {}): Observable<MinimalNodeEntryEntity>`<br/>
+Gets the stored information about a node.
+
+`getNodeChildren(nodeId: string, options: any = {}): Observable<NodePaging>`<br/>
+Gets the items contained in a folder node.
+
+`createNode(parentNodeId: string, nodeBody: any, options: any = {}): Observable<MinimalNodeEntryEntity>`<br/>
+Creates a new document node inside a folder.
+
+`createFolder(parentNodeId: string, nodeBody: any, options: any = {}): Observable<MinimalNodeEntryEntity>`<br/>
+Creates a new folder node inside a parent folder.
+
+`updateNode(nodeId: string, nodeBody: any, options: any = {}): Observable<MinimalNodeEntryEntity>`<br/>
+Updates the information about a node.
+
+`deleteNode(nodeId: string, options: any = {}): Observable<void>`<br/>
+Moves a node to the "trashcan".
+
+`restoreNode(nodeId: string): Observable<MinimalNodeEntryEntity>`<br/>
+Restores a node previously moved to the "trashcan".
+
+## Details
+
+Each node (ie, document or folder) in an ACS repository is identified by
+its own unique node ID value. The ID is a long string of hex values separated
+by dashes, eg:
+
+`53ef6110-ed9c-4739-a520-e7b4336229c0`
+
+The string is convenient for storage, for passing as an 
+[Angular route parameter](https://angular.io/guide/router)
+and other purposes but doesn't enable you to do very much with the node itself.
+The Nodes Api Service has methods for getting information about nodes and
+managing them within the repository (creating, deleting, etc).
+
+Other lower level interfaces to the ACS nodes API are also available - see the
+[Alfresco Api service](alfresco-api.service.md), the 
+[Alfresco JS API docs](https://github.com/Alfresco/alfresco-js-api/tree/master/src/alfresco-core-rest-api)
+and the
+[REST API Explorer](https://api-explorer.alfresco.com/api-explorer/#/nodes)
+for more information.
+
+### Getting node information
+
+The `getNode` method gives access to the MinimalNode object that represents the
+details of a node:
+
+```ts
+interface MinimalNodeEntryEntity extends MinimalNode {
+}
+interface MinimalNode extends Node {
+   id: string;
+   parentId: string;
+   name: string;
+   nodeType: string;
+   isFolder: boolean;
+   isFile: boolean;
+   modifiedAt: Date;
+   modifiedByUser: UserInfo;
+   createdAt: Date;
+   createdByUser: UserInfo;
+   content: ContentInfo;
+   path: PathInfoEntity;
+   properties: NodeProperties;
+}
+```
+
+This provides useful information about the node, such as its name, creation and
+modification dates, etc. Also, the `id` and `parentId` properties contain the node
+ID strings for the current node and its enclosing folder.
+
+Sometimes, a MinimalNode is provided directly, for example, the `folderNode` property
+of a [Document List component](document-list.component.md) or the data context of a
+[Document List row](document-list.component.md#underlying-node-object). In these cases,
+you might pass the `id` or `parentId` as a [route parameter](https://angular.io/guide/router)
+to a page describing the node in full detail. The component receiving the node ID can
+use the Nodes Api service to "decode" the ID string into a MinimalNodeEntryEntity:
+
+```ts
+import { ActivatedRoute, Router } from '@angular/router';
+import { Component, OnInit } from '@angular/core';
+import { NodesApiService } from 'ng2-alfresco-core';
+import { MinimalNodeEntryEntity } from 'alfresco-js-api';
+    ...
+
+export class RepositoryDetailsPageComponent implements OnInit {
+ nodeId: string;
+ nodeName: string;
+ isFile: boolean;
+    ...
+
+ constructor(private router: Router,
+             private activatedRoute: ActivatedRoute,
+             private nodeService: NodesApiService) {
+ }
+
+ ngOnInit() {
+   this.nodeId = this.activatedRoute.snapshot.params['node-id'];
+   this.nodeService.getNode(this.nodeId).subscribe((entry: MinimalNodeEntryEntity) => {
+     const node: MinimalNodeEntryEntity = entry;
+     this.nodeName = node.name;
+     this.isFile = node.isFile;
+        ...
+   });
+ }
+```
+
+You can supply a number of extra options using the `options` parameter. See the
+[getNode](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodesApi.md#getNode)
+page in the Alfresco JS API docs for more information.
+
+### Getting folder node contents
+
+The `getNodeChildren` method returns the contents of a folder
+as a list of items. See the [Paging section](document-library.model.md#paging)
+of [Document Library model](document-library.model.md) for
+more information about the structure of the list. Also, the
+[getNodeChildren](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodesApi.md#getNodeChildren)
+page in the Alfresco JS API gives more information about the structure of the
+`options` parameter.
+
+### Creating and updating nodes
+
+You can use the `createNode` and `createFolder` methods to add new nodes
+within a parent folder node, and the `updateNode` method to update an
+existing node. See the
+[addNode](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodesApi.md#addNode)
+and
+[updateNode](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodesApi.md#updateNode)
+entries in the Alfresco JS API for further information about the available options and 
+the format of the new node data.
+
+### Deleting and restoring nodes
+
+The Content Services repository maintains a "trashcan" where items are
+temporarily held after they have been deleted. This means you can
+restore a deleted item if you remove it from the trashcan before it
+gets deleted permanently.
+
+By default, the `deleteNode` method moves an item into the trash, where it can
+be retrieved using `restoreNode`. However, you can set an option for `deleteNode`
+to delete the node immediately if you have the right permissions. See the
+[deleteNode](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodesApi.md#deleteNode)
+and
+[restoreNode](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodesApi.md#restoreNode)
+pages in the Alfresco JS API for further details and options. Note that you can also use the
+[Deleted Nodes Api service](deleted-nodes-api.service.md) get a list of all items currently in the trashcan.
+
+<!-- Don't edit the See also section. Edit seeAlsoGraph.json and run config/generateSeeAlso.js -->
+<!-- seealso start -->
+## See also
+
+- [Document library model](document-library.model.md)
+- [Deleted nodes api service](deleted-nodes-api.service.md)
+- [Document list component](document-list.component.md)
+<!-- seealso end -->
--- a/docs/seeAlsoGraph.json
+++ b/docs/seeAlsoGraph.json
@ -24,14 +24,18 @@
        "pagination.component"
    ],
    "DataTableAdapter": ["datatable.component", "task-list.component"],
+    "deleted-nodes-api.service": [],
    "diagram.component": [],
    "document-actions.service": [],
+    "document-library.model": [],
    "document-list.component": [
        "datatable.component",
        "data-column.component",
        "pagination.component",
        "sites-dropdown.component",
-        "metadata-indicators"
+        "metadata-indicators",
+        "document-library.model",
+        "nodes-api.service"
    ],
    "dropdown-breadcrumb.component": ["document-list.component", "breadcrumb.component"],
    "extensibility": [],
@ -59,6 +63,7 @@
    "metadata-indicators": [],
    "mime-type-icon.pipe": [],
    "node-permission.directive": [],
+    "nodes-api.service": ["document-library.model", "deleted-nodes-api.service"],
    "notification.service": [],
    "pagination.component": [],
    "permissions-style.model": ["document-list.component"],
--- a/docs/time-ago.pipe.md
+++ b/docs/time-ago.pipe.md
@ -0,0 +1,22 @@
+# Time Ago pipe
+
+Converts a recent past date into a number of days ago.
+
+## Basic Usage
+
+```HTML
+<div>
+    Last modified: {{ date | adfTimeAgo }}
+</div>
+```
+
+## Details
+
+The pipe finds the difference between the input date and the current date. If it
+is less than seven days then then the date will be formatted as "X days ago".
+Otherwise, the usual full date format is used.
+
+<!-- Don't edit the See also section. Edit seeAlsoGraph.json and run config/generateSeeAlso.js -->
+<!-- seealso start -->
+
+<!-- seealso end -->
--- a/docs/user-initial.pipe.md
+++ b/docs/user-initial.pipe.md
@ -0,0 +1,26 @@
+# User Initial pipe
+
+Takes the name fields of a UserProcessModel object and extracts and formats the initials.
+
+## Basic Usage
+
+```HTML
+<div>
+    Project Leader: {{ user | usernameInitials:"initialsClass" }}
+</div>
+```
+
+## Details
+
+The pipe gets the initial characters of the user's first and last names and
+concatenates them. The results are returned in an HTML &lt;div&gt; element.
+
+The first pipe parameter specifies an optional CSS class to add to the &lt;div&gt;
+element (eg, a background color is commonly used to emphasise initials). The
+second parameter is an optional delimiter to add between the initials.
+Both parameters default to empty strings.
+
+<!-- Don't edit the See also section. Edit seeAlsoGraph.json and run config/generateSeeAlso.js -->
+<!-- seealso start -->
+
+<!-- seealso end -->