From c824e646de4b866ee86be8fb6fd95f420136a2b3 Mon Sep 17 00:00:00 2001 From: Andy Stark <30621568+therealandeeee@users.noreply.github.com> Date: Fri, 4 May 2018 19:03:13 +0100 Subject: [PATCH] [ADF-2905] Updated JSDocs for core (#3271) --- docs/core/app-config.service.md | 29 +++++- docs/core/bpm-user.service.md | 13 ++- docs/core/card-view.component.md | 29 ++++-- docs/core/comment-content.service.md | 8 +- docs/core/content.service.md | 92 +++++++++++-------- docs/core/context-menu.directive.md | 4 +- docs/core/favorites-api.service.md | 9 +- docs/core/form-rendering.service.md | 29 +++--- docs/core/form.service.md | 2 +- lib/core/app-config/app-config.service.ts | 24 +++++ .../card-view/card-view.component.ts | 3 + .../context-menu/context-menu.directive.ts | 2 + lib/core/form/services/form.service.ts | 55 ++++++++--- lib/core/services/comment-content.service.ts | 11 +++ lib/core/services/content.service.ts | 49 ++++------ .../dynamic-component-mapper.service.ts | 2 + lib/core/services/favorites-api.service.ts | 6 ++ .../userinfo/services/bpm-user.service.ts | 8 +- 18 files changed, 256 insertions(+), 119 deletions(-) diff --git a/docs/core/app-config.service.md b/docs/core/app-config.service.md index 05d615c5d6..560a679530 100644 --- a/docs/core/app-config.service.md +++ b/docs/core/app-config.service.md @@ -2,10 +2,35 @@ Added: v2.0.0 Status: Active --- + # App Config service Supports app configuration settings, stored server side. +## Class members + +### Methods + +- `get(key: string = null, defaultValue?: T = null): T`
+ Gets the value of a named property. + - `key: string = null` - Name of the property + - `defaultValue?: T = null` - (Optional) Value to return if the key is not found + - **Returns** `T` - Value of the property +- `getLocationHostname(): string`
+ Gets the location.hostname property. + - **Returns** `string` - Value of the property +- `getLocationPort(prefix: string = ""): string`
+ Gets the location.port property. + - `prefix: string = ""` - Text added before port value + - **Returns** `string` - Port with prefix +- `load(): Promise`
+ Loads the config file. + - **Returns** `Promise` - Notification when loading is complete +- `select(property: string = null): Observable`
+ Requests notification of a property value when it is loaded. + - `property: string = null` - The desired property value + - **Returns** `Observable` - Property value, when loaded + ## Details The `AppConfigService` service provides support for loading and accessing global application configuration settings that you store on the server side in the form of a JSON file. @@ -100,10 +125,10 @@ The supported variables are: | port | `location.port` | ## App Config onLoad Stream + When the app config is loaded correctly an onChange event is sent with the whole set app config properties. This comes in handy when a component wants to react to some property change or interact with the app config when it's correctly loaded. ```ts - appConfig.onLoad.subscribe((appConfig) => { console.log(appConfig); //this is the representation of the app-config }); @@ -122,4 +147,4 @@ We have added also the `select` method where the user can give the property name appConfig.select('logLevel').subscribe((logLevelValue) => { console.log(logLevelValue); //this will be 'trace'; }); -``` \ No newline at end of file +``` diff --git a/docs/core/bpm-user.service.md b/docs/core/bpm-user.service.md index 1f2d258e57..4d9eb7333e 100644 --- a/docs/core/bpm-user.service.md +++ b/docs/core/bpm-user.service.md @@ -1,7 +1,9 @@ --- Added: v2.0.0 Status: Active +Last reviewed: 2018-05-04 --- + # Bpm User service Gets information about the current Process Services user. @@ -10,11 +12,12 @@ Gets information about the current Process Services user. ### Methods -`getCurrentUserInfo(): Observable`
-Gets information about the current user. - -`getCurrentUserProfileImage(): string`
-Returns the current user's profile image as a URL. +- `getCurrentUserInfo(): Observable`
+ Gets information about the current user. + - **Returns** `Observable` - User information object +- `getCurrentUserProfileImage(): string`
+ Gets the current user's profile image as a URL. + - **Returns** `string` - URL string ## Details diff --git a/docs/core/card-view.component.md b/docs/core/card-view.component.md index fa6052106f..c3e4c6cb6e 100644 --- a/docs/core/card-view.component.md +++ b/docs/core/card-view.component.md @@ -2,12 +2,29 @@ Added: v2.0.0 Status: Active --- + # Card View component Displays a configurable property list renderer. ![adf-custom-view](../docassets/images/adf-custom-view.png) +## Contents + +- [Basic Usage](#basic-usage) + +- [Class members](#class-members) + + - [Properties](#properties) + +- [Details](#details) + + - [Editing](#editing) + - [Defining properties](#defining-properties) + - [Defining your custom card Item](#defining-your-custom-card-item) + +- [See also](#see-also) + ## Basic Usage ```html @@ -21,11 +38,11 @@ Displays a configurable property list renderer. ### Properties -| Name | Type | Default | Description | -| ---- | ---- | ------- | ----------- | -| properties | [CardViewItem](#defining-properties)\[] | - | (**required**) The custom view to render | -| editable | boolean | - | If the component editable or not | -| displayEmpty | boolean | true | Whether to show empty properties in non-editable mode | +| Name | Type | Default value | Description | +| -- | -- | -- | -- | +| displayEmpty | `boolean` | true | Toggles whether or not to show empty items in non-editable mode. | +| editable | `boolean` | | Toggles whether or not the items can be edited. | +| properties | `CardViewItem[]` | | (**required**) Items to show in the card view. | ## Details @@ -145,7 +162,7 @@ const textItemProperty = new CardViewTextItemModel(options); | displayValue\* | string | --- | The value to render | | editable | boolean | false | Whether the property editable or not | | clickable | boolean | false | Whether the property clickable or not | -| icon | string | The material icon to show against the clickable property | +| icon | string | The material icon to show against the clickable property | | | multiline | string | false | Single or multiline text | | pipes | CardViewTextItemPipeProperty\[] | \[] | Pipes to be applied on the displayValue | diff --git a/docs/core/comment-content.service.md b/docs/core/comment-content.service.md index e46b32691f..c3bf912be9 100644 --- a/docs/core/comment-content.service.md +++ b/docs/core/comment-content.service.md @@ -12,12 +12,12 @@ Adds and retrieves comments for nodes in Content Services. ### Methods -- `addNodeComment(nodeId: string, message: string): Observable`
+- `addNodeComment(nodeId: string = null, message: string = null): Observable`
Adds a comment to a node. - - `nodeId: string` - ID of the target node - - `message: string` - Text for the comment + - `nodeId: string = null` - ID of the target node + - `message: string = null` - Text for the comment - **Returns** `Observable` - Details of the comment added -- `getNodeComments(nodeId: string): Observable`
+- `getNodeComments(nodeId: string = null): Observable`
Gets all comments that have been added to a node. - `nodeId: string = null` - ID of the target node - **Returns** `Observable` - Details for each comment diff --git a/docs/core/content.service.md b/docs/core/content.service.md index ec4f8e12ef..6567fa0fe2 100644 --- a/docs/core/content.service.md +++ b/docs/core/content.service.md @@ -12,46 +12,58 @@ Accesses app-generated data objects via URLs and file downloads. ### Methods -- `downloadBlob(blob: Blob, fileName: string)` - Invokes content download for a Blob with a file name. - - `blob` - Content to download. - - `fileName` - Name of the resulting file. -- `downloadData(data: any, fileName: string)` - Invokes content download for a data array with a file name. - - `data` - Data to download. - - `fileName` - Name of the resulting file. -- `downloadJSON(json: any, fileName)` - Invokes content download for a JSON object with a file name. - - `json` - JSON object to download. - - `fileName` - Name of the resulting file. -- `createTrustedUrl(blob: Blob): string` - Creates a trusted object URL from the Blob. WARNING: calling this method with untrusted user data exposes your application to XSS security risks! - - `blob` - Data to wrap into object URL -- `getDocumentThumbnailUrl(node: any, attachment?: boolean, ticket?: string): string` - Get thumbnail URL for the given document node. - - `node` - Node to get URL for. - - `attachment` - (Optional) Retrieve content as an attachment for download - - `ticket` - (Optional) Custom ticket to use for authentication -- `getContentUrl(node: any, attachment?: boolean, ticket?: string): string` - Get content URL for the given node. - - `node` - nodeId or node to get URL for. - - `attachment` - (Optional) Retrieve content as an attachment for download - - `ticket` - (Optional) Custom ticket to use for authentication -- `getNodeContent(nodeId: string): Observable` - Get content for the given node. - - `nodeId` - ID of the target node -- `createFolder(relativePath: string, name: string, parentId?: string): Observable` - Create a folder - - `relativePath` - Location to create the folder - - `name` - Folder name - - `parentId` - (Optional) Node ID of parent folder -- `hasPermission(node: any, permission: PermissionsEnum | string): boolean` - Check if the user has permissions on that node - - `node` - Node to check allowableOperations - - `permission` - Create, delete, update, updatePermissions, !create, !delete, !update, !updatePermissions -- `hasAllowableOperations(node: any): boolean` - Check if the node has the properties allowableOperations - - `node` - Node to check allowableOperations +- `createFolder(relativePath: string = null, name: string = null, parentId?: string = null): Observable`
+ Creates a folder. + - `relativePath: string = null` - Location to create the folder + - `name: string = null` - Folder name + - `parentId?: string = null` - (Optional) Node ID of parent folder + - **Returns** `Observable` - Information about the new folder +- `createTrustedUrl(blob: Blob = null): string`
+ Creates a trusted object URL from the Blob. WARNING: calling this method with untrusted user data exposes your application to XSS security risks! + - `blob: Blob = null` - Data to wrap into object URL + - **Returns** `string` - URL string +- `downloadBlob(blob: Blob = null, fileName: string = null)`
+ Invokes content download for a Blob with a file name. + - `blob: Blob = null` - Content to download. + - `fileName: string = null` - Name of the resulting file. +- `downloadData(data: any = null, fileName: string = null)`
+ Invokes content download for a data array with a file name. + - `data: any = null` - Data to download. + - `fileName: string = null` - Name of the resulting file. +- `downloadJSON(json: any = null, fileName: string = null)`
+ Invokes content download for a JSON object with a file name. + - `json: any = null` - JSON object to download. + - `fileName: string = null` - Name of the resulting file. +- `getContentUrl(node: any = null, attachment?: boolean = null, ticket?: string = null): string`
+ Gets a content URL for the given node. + - `node: any = null` - Node to get URL for. + - `attachment?: boolean = null` - (Optional) Toggles whether to retrieve content as an attachment for download + - `ticket?: string = null` - (Optional) Custom ticket to use for authentication + - **Returns** `string` - URL string +- `getDocumentThumbnailUrl(node: any = null, attachment?: boolean = null, ticket?: string = null): string`
+ Gets a thumbnail URL for the given document node. + - `node: any = null` - Node to get URL for. + - `attachment?: boolean = null` - (Optional) Toggles whether to retrieve content as an attachment for download + - `ticket?: string = null` - (Optional) Custom ticket to use for authentication + - **Returns** `string` - URL string +- `getNode(nodeId: string = null, opts?: any = null): Observable`
+ Gets a Node via its node ID. + - `nodeId: string = null` - ID of the target node + - `opts?: any = null` - (Optional) Options supported by JSAPI + - **Returns** `Observable` - Details of the folder +- `getNodeContent(nodeId: string = null): Observable`
+ Gets content for the given node. + - `nodeId: string = null` - ID of the target node + - **Returns** `Observable` - Content data +- `hasAllowableOperations(node: any = null): boolean`
+ Checks if the node has the properties allowableOperations + - `node: any = null` - Node to check allowableOperations + - **Returns** `boolean` - True if the node has the property, false otherwise +- `hasPermission(node: Node = null, permission: PermissionsEnum | string = null): boolean`
+ Checks if the user has permissions on that node + - `node: Node = null` - Node to check allowableOperations + - `permission: PermissionsEnum | string = null` - Create, delete, update, updatePermissions, !create, !delete, !update, !updatePermissions + - **Returns** `boolean` - True if the user has the required permissions, false otherwise ## Details diff --git a/docs/core/context-menu.directive.md b/docs/core/context-menu.directive.md index 68d4fce92e..4df63fef93 100644 --- a/docs/core/context-menu.directive.md +++ b/docs/core/context-menu.directive.md @@ -48,8 +48,8 @@ export class MyComponent implements OnInit { | Name | Type | Default value | Description | | -- | -- | -- | -- | -| context-menu-enabled | `boolean` | false | | -| context-menu | `any[]` | | | +| context-menu-enabled | `boolean` | false | Is the menu enabled? | +| context-menu | `any[]` | | Items for the menu. | ## Details diff --git a/docs/core/favorites-api.service.md b/docs/core/favorites-api.service.md index 69ebf7a589..51d253e618 100644 --- a/docs/core/favorites-api.service.md +++ b/docs/core/favorites-api.service.md @@ -1,7 +1,9 @@ --- Added: v2.0.0 Status: Active +Last reviewed: 2018-05-04 --- + # Favorites Api service Gets a list of items a user has marked as their favorites. @@ -10,8 +12,11 @@ Gets a list of items a user has marked as their favorites. ### Methods -`getFavorites(personId: string, options?: any): Observable`
-Gets the favorites for a user. +- `getFavorites(personId: string = null, options?: any = null): Observable`
+ Gets the favorites for a user. + - `personId: string = null` - ID of the user + - `options?: any = null` - (Optional) Options supported by JSAPI + - **Returns** `Observable` - List of favorites ## Details diff --git a/docs/core/form-rendering.service.md b/docs/core/form-rendering.service.md index da87555ec7..822b0ec618 100644 --- a/docs/core/form-rendering.service.md +++ b/docs/core/form-rendering.service.md @@ -2,6 +2,7 @@ Added: v2.0.0 Status: Active --- + # Form Rendering service Maps an APS form field type string onto the corresponding form widget component type. @@ -10,19 +11,21 @@ Maps an APS form field type string onto the corresponding form widget component ### Methods -- `getComponentTypeResolver(type: string, defaultValue: Type<{}> = this.defaultValue): DynamicComponentResolveFunction` - Gets the currently active ComponentTypeResolver function for a field type. - - `type` - The type whose resolver you want - - `defaultValue` - Default type returned for types that are not yet mapped -- `setComponentTypeResolver(type: string, resolver: DynamicComponentResolveFunction, override: boolean = false)` - Sets or optionally replaces a ComponentTypeResolver function for a field type. - - `type` - The type whose resolver you want to set - - `resolver` - The new resolver function - - `override` - The new resolver will only replace an existing one if this parameter is true -- `resolveComponentType(model: DynamicComponentModel, defaultValue: Type<{}> = this.defaultValue): Type<{}>` - Finds the component type that is needed to render a form field. - - `model` - [Form field model](form-field.model.md) for the field to render - - `defaultValue` - Default type returned for field types that are not yet mapped. +- `getComponentTypeResolver(type: string = null, defaultValue: Type<__type> = this.defaultValue): DynamicComponentResolveFunction`
+ Gets the currently active ComponentTypeResolver function for a field type. + - `type: string = null` - The type whose resolver you want + - `defaultValue: Type<__type> = this.defaultValue` - Default type returned for types that are not yet mapped + - **Returns** `DynamicComponentResolveFunction` - Resolver function +- `resolveComponentType(model: DynamicComponentModel = null, defaultValue: Type<__type> = this.defaultValue): Type<__type>`
+ Finds the component type that is needed to render a form field. + - `model: DynamicComponentModel = null` - (form-field.model.md) for the field to render + - `defaultValue: Type<__type> = this.defaultValue` - Default type returned for field types that are not yet mapped. + - **Returns** `Type<__type>` - Component type +- `setComponentTypeResolver(type: string = null, resolver: DynamicComponentResolveFunction = null, override: boolean = false)`
+ Sets or optionally replaces a ComponentTypeResolver function for a field type. + - `type: string = null` - The type whose resolver you want to set + - `resolver: DynamicComponentResolveFunction = null` - The new resolver function + - `override: boolean = false` - The new resolver will only replace an existing one if this parameter is true ## Details diff --git a/docs/core/form.service.md b/docs/core/form.service.md index 68f2983322..3a0e42208d 100644 --- a/docs/core/form.service.md +++ b/docs/core/form.service.md @@ -2,6 +2,7 @@ Added: v2.0.0 Status: Active --- + # Form service Implements Process Services form methods @@ -66,7 +67,6 @@ class MyComponent { - `formId` - ID of the form to save - `formModel` - Model data for the form - `addFieldsToAForm(formId: string, formModel: FormDefinitionModel): Observable` - - `formId` - ID of the form - `formModel` - Form definition - `searchFrom(name: string): Observable` diff --git a/lib/core/app-config/app-config.service.ts b/lib/core/app-config/app-config.service.ts index 276842329e..7b5a243a63 100644 --- a/lib/core/app-config/app-config.service.ts +++ b/lib/core/app-config/app-config.service.ts @@ -44,10 +44,21 @@ export class AppConfigService { this.onLoad = this.onLoadSubject.asObservable(); } + /** + * Requests notification of a property value when it is loaded. + * @param property The desired property value + * @returns Property value, when loaded + */ select(property: string): Observable { return this.onLoadSubject.map((config) => config[property]).distinctUntilChanged(); } + /** + * Gets the value of a named property. + * @param key Name of the property + * @param defaultValue Value to return if the key is not found + * @returns Value of the property + */ get(key: string, defaultValue?: T): T { let result: any = ObjectUtils.getValue(this.config, key); if (typeof result === 'string') { @@ -63,14 +74,27 @@ export class AppConfigService { return result; } + /** + * Gets the location.hostname property. + * @returns Value of the property + */ getLocationHostname(): string { return location.hostname; } + /** + * Gets the location.port property. + * @param prefix Text added before port value + * @returns Port with prefix + */ getLocationPort(prefix: string = ''): string { return location.port ? prefix + location.port : ''; } + /** + * Loads the config file. + * @returns Notification when loading is complete + */ load(): Promise { return new Promise(resolve => { this.http.get('app.config.json').subscribe( diff --git a/lib/core/card-view/components/card-view/card-view.component.ts b/lib/core/card-view/components/card-view/card-view.component.ts index d945c61cc8..a4453a2269 100644 --- a/lib/core/card-view/components/card-view/card-view.component.ts +++ b/lib/core/card-view/components/card-view/card-view.component.ts @@ -24,12 +24,15 @@ import { CardViewItem } from '../../interfaces/card-view-item.interface'; styleUrls: ['./card-view.component.scss'] }) export class CardViewComponent { + /** (**required**) Items to show in the card view. */ @Input() properties: CardViewItem []; + /** Toggles whether or not the items can be edited. */ @Input() editable: boolean; + /** Toggles whether or not to show empty items in non-editable mode. */ @Input() displayEmpty: boolean = true; } diff --git a/lib/core/context-menu/context-menu.directive.ts b/lib/core/context-menu/context-menu.directive.ts index f486c722bb..4e8dfe77e1 100644 --- a/lib/core/context-menu/context-menu.directive.ts +++ b/lib/core/context-menu/context-menu.directive.ts @@ -25,9 +25,11 @@ import { ContextMenuService } from './context-menu.service'; selector: '[adf-context-menu], [context-menu]' }) export class ContextMenuDirective { + /** Items for the menu. */ @Input('context-menu') links: any[]; + /** Is the menu enabled? */ @Input('context-menu-enabled') enabled: boolean = false; diff --git a/lib/core/form/services/form.service.ts b/lib/core/form/services/form.service.ts index 1a9c8890bb..57fbcb1c90 100644 --- a/lib/core/form/services/form.service.ts +++ b/lib/core/form/services/form.service.ts @@ -95,6 +95,7 @@ export class FormService { * @param json JSON to create the form * @param data Values for the form fields * @param readOnly Should the form fields be read-only? + * @returns Form model created from input data */ parseForm(json: any, data?: FormValues, readOnly: boolean = false): FormModel { if (json) { @@ -114,8 +115,9 @@ export class FormService { } /** - * Create a Form with a field for each metadata property. + * Creates a Form with a field for each metadata property. * @param formName Name of the new form + * @returns The new form */ createFormFromANode(formName: string): Observable { return Observable.create(observer => { @@ -138,6 +140,7 @@ export class FormService { /** * Create a Form. * @param formName Name of the new form + * @returns The new form */ createForm(formName: string): Observable { let dataModel = { @@ -156,6 +159,7 @@ export class FormService { * Saves a form. * @param formId ID of the form to save * @param formModel Model data for the form + * @returns Data for the saved form */ saveForm(formId: string, formModel: FormDefinitionModel): Observable { return Observable.fromPromise( @@ -177,8 +181,9 @@ export class FormService { } /** - * Search for a form by name. + * Searches for a form by name. * @param name The form name to search for + * @returns Form model(s) matching the search name */ searchFrom(name: string): Observable { let opts = { @@ -196,6 +201,7 @@ export class FormService { /** * Gets all the forms. + * @returns List of form models */ getForms(): Observable { let opts = { @@ -208,7 +214,8 @@ export class FormService { } /** - * Get Process Definitions + * Gets process definitions. + * @returns List of process definitions */ getProcessDefinitions(): Observable { return Observable.fromPromise(this.processApi.getProcessDefinitions({})) @@ -217,8 +224,9 @@ export class FormService { } /** - * Get instance variables for a process. + * Gets instance variables for a process. * @param processInstanceId ID of the target process + * @returns List of instance variable information */ getProcessVarablesById(processInstanceId: string): Observable { return Observable.fromPromise(this.processInstanceVariablesApi.getProcessInstanceVariables(processInstanceId)) @@ -228,6 +236,7 @@ export class FormService { /** * Gets all the tasks. + * @returns List of tasks */ getTasks(): Observable { return Observable.fromPromise(this.taskApi.listTasks({})) @@ -238,6 +247,7 @@ export class FormService { /** * Gets a task. * @param taskId Task Id + * @returns Task info */ getTask(taskId: string): Observable { return Observable.fromPromise(this.taskApi.getTask(taskId)) @@ -246,9 +256,10 @@ export class FormService { } /** - * Save Task Form. + * Saves a task form. * @param taskId Task Id * @param formValues Form Values + * @returns Null response when the operation is complete */ saveTaskForm(taskId: string, formValues: FormValues): Observable { let body = JSON.stringify({values: formValues}); @@ -258,10 +269,11 @@ export class FormService { } /** - * Complete Task Form + * Completes a Task Form. * @param taskId Task Id * @param formValues Form Values * @param outcome Form Outcome + * @returns Null response when the operation is complete */ completeTaskForm(taskId: string, formValues: FormValues, outcome?: string): Observable { let data: any = {values: formValues}; @@ -275,8 +287,9 @@ export class FormService { } /** - * Get Form related to a taskId - * @param taskId Task Id + * Gets a form related to a task. + * @param taskId ID of the target task + * @returns Form definition */ getTaskForm(taskId: string): Observable { return Observable.fromPromise(this.taskApi.getTaskForm(taskId)) @@ -285,8 +298,9 @@ export class FormService { } /** - * Get Form Definition - * @param formId Form Id + * Gets a form definition. + * @param formId ID of the target form + * @returns Form definition */ getFormDefinitionById(formId: string): Observable { return Observable.fromPromise(this.editorApi.getForm(formId)) @@ -295,8 +309,9 @@ export class FormService { } /** - * Returns form definition with a given name. + * Gets the form definition with a given name. * @param name The form name + * @returns Form definition */ getFormDefinitionByName(name: string): Observable { let opts = { @@ -311,8 +326,9 @@ export class FormService { } /** - * Get start form instance for a given processId + * Gets the start form instance for a given process. * @param processId Process definition ID + * @returns Form definition */ getStartFormInstance(processId: string): Observable { return Observable.fromPromise( @@ -324,6 +340,7 @@ export class FormService { /** * Gets a process instance. * @param processId ID of the process to get + * @returns Process instance */ getProcessIntance(processId: string): Observable { return Observable.fromPromise(this.processApi.getProcessInstance(processId)) @@ -332,8 +349,9 @@ export class FormService { } /** - * Get start form definition for a given process + * Gets the start form definition for a given process. * @param processId Process definition ID + * @returns Form definition */ getStartFormDefinition(processId: string): Observable { return Observable.fromPromise( @@ -346,6 +364,7 @@ export class FormService { * Gets values of fields populated by a REST backend. * @param taskId Task identifier * @param field Field identifier + * @returns Field values */ getRestFieldValues(taskId: string, field: string): Observable { return Observable.fromPromise(this.taskApi.getRestFieldValues(taskId, field)).catch(err => this.handleError(err)); @@ -355,6 +374,7 @@ export class FormService { * Gets values of fields populated by a REST backend using a process ID. * @param processDefinitionId Process identifier * @param field Field identifier + * @returns Field values */ getRestFieldValuesByProcessId(processDefinitionId: string, field: string): Observable { return Observable.fromPromise(this.processApi.getRestFieldValues(processDefinitionId, field)).catch(err => this.handleError(err)); @@ -365,6 +385,7 @@ export class FormService { * @param processDefinitionId Process identifier * @param field Field identifier * @param column Column identifier + * @returns Field values */ getRestFieldValuesColumnByProcessId(processDefinitionId: string, field: string, column?: string): Observable { return Observable.fromPromise(this.processApi.getRestTableFieldValues(processDefinitionId, field, column)).catch(err => this.handleError(err)); @@ -375,6 +396,7 @@ export class FormService { * @param taskId Task identifier * @param field Field identifier * @param column Column identifier + * @returns Field values */ getRestFieldValuesColumn(taskId: string, field: string, column?: string): Observable { return Observable.fromPromise(this.taskApi.getRestFieldValuesColumn(taskId, field, column)).catch(err => this.handleError(err)); @@ -383,6 +405,7 @@ export class FormService { /** * Returns a URL for the profile picture of a user. * @param userId ID of the target user + * @returns URL string */ getUserProfileImageApi(userId: number): string { return this.apiService.getInstance().activiti.userApi.getUserProfilePictureUrl(userId); @@ -392,6 +415,7 @@ export class FormService { * Gets a list of workflow users. * @param filter Filter to select specific users * @param groupId Group ID for the search + * @returns Array of users */ getWorkflowUsers(filter: string, groupId?: string): Observable { let option: any = {filter: filter}; @@ -413,6 +437,7 @@ export class FormService { * Gets a list of groups in a workflow. * @param filter Filter to select specific groups * @param groupId Group ID for the search + * @returns Array of groups */ getWorkflowGroups(filter: string, groupId?: string): Observable { let option: any = {filter: filter}; @@ -427,6 +452,7 @@ export class FormService { /** * Gets the ID of a form. * @param res Object representing a form + * @returns ID string */ getFormId(res: any): string { let result = null; @@ -441,6 +467,7 @@ export class FormService { /** * Creates a JSON representation of form data. * @param res Object representing form data + * @returns JSON data */ toJson(res: any) { if (res) { @@ -452,6 +479,7 @@ export class FormService { /** * Creates a JSON array representation of form data. * @param res Object representing form data + * @returns JSON data */ toJsonArray(res: any) { if (res) { @@ -463,6 +491,7 @@ export class FormService { /** * Reports an error message. * @param error Data object with optional `message` and `status` fields for the error + * @returns Error message */ handleError(error: any): Observable { let errMsg = FormService.UNKNOWN_ERROR_MESSAGE; diff --git a/lib/core/services/comment-content.service.ts b/lib/core/services/comment-content.service.ts index 3b042b417f..6e3ae4c7c7 100644 --- a/lib/core/services/comment-content.service.ts +++ b/lib/core/services/comment-content.service.ts @@ -31,6 +31,12 @@ export class CommentContentService { private logService: LogService) { } + /** + * Adds a comment to a node. + * @param nodeId ID of the target node + * @param message Text for the comment + * @returns Details of the comment added + */ addNodeComment(nodeId: string, message: string): Observable { return Observable.fromPromise(this.apiService.getInstance().core.commentsApi.addComment(nodeId, {content: message})) .map((response: any) => { @@ -43,6 +49,11 @@ export class CommentContentService { }).catch(err => this.handleError(err)); } + /** + * Gets all comments that have been added to a node. + * @param nodeId ID of the target node + * @returns Details for each comment + */ getNodeComments(nodeId: string): Observable { return Observable.fromPromise(this.apiService.getInstance().core.commentsApi.getComments(nodeId)) .map((response: any) => { diff --git a/lib/core/services/content.service.ts b/lib/core/services/content.service.ts index 450e37aa50..8060aeef31 100644 --- a/lib/core/services/content.service.ts +++ b/lib/core/services/content.service.ts @@ -79,11 +79,8 @@ export class ContentService { /** * Invokes content download for a Blob with a file name. - * * @param blob Content to download. * @param fileName Name of the resulting file. - * - * @memberOf ContentService */ downloadBlob(blob: Blob, fileName: string): void { this.saveData(blob, 'blob', fileName); @@ -91,11 +88,8 @@ export class ContentService { /** * Invokes content download for a data array with a file name. - * * @param data Data to download. * @param fileName Name of the resulting file. - * - * @memberOf ContentService */ downloadData(data: any, fileName: string): void { this.saveData(data, 'data', fileName); @@ -103,11 +97,8 @@ export class ContentService { /** * Invokes content download for a JSON object with a file name. - * * @param json JSON object to download. * @param fileName Name of the resulting file. - * - * @memberOf ContentService */ downloadJSON(json: any, fileName: string): void { this.saveData(json, 'json', fileName); @@ -117,8 +108,7 @@ export class ContentService { * Creates a trusted object URL from the Blob. * WARNING: calling this method with untrusted user data exposes your application to XSS security risks! * @param blob Data to wrap into object URL - * - * @memberOf ContentService + * @returns URL string */ createTrustedUrl(blob: Blob): string { let url = window.URL.createObjectURL(blob); @@ -130,11 +120,11 @@ export class ContentService { } /** - * Get thumbnail URL for the given document node. - * + * Gets a thumbnail URL for the given document node. * @param node Node to get URL for. - * @param [attachment] Retrieve content as an attachment for download - * @param [ticket] Custom ticket to use for authentication + * @param attachment Toggles whether to retrieve content as an attachment for download + * @param ticket Custom ticket to use for authentication + * @returns URL string */ getDocumentThumbnailUrl(node: any, attachment?: boolean, ticket?: string): string { @@ -146,11 +136,11 @@ export class ContentService { } /** - * Get content URL for the given node. - * - * @param nodeId or node to get URL for. - * @param [attachment] Retrieve content as an attachment for download - * @param [ticket] Custom ticket to use for authentication + * Gets a content URL for the given node. + * @param node Node to get URL for. + * @param attachment Toggles whether to retrieve content as an attachment for download + * @param ticket Custom ticket to use for authentication + * @returns URL string */ getContentUrl(node: any, attachment?: boolean, ticket?: string): string { @@ -162,9 +152,9 @@ export class ContentService { } /** - * Get content for the given node. + * Gets content for the given node. * @param nodeId ID of the target node - * + * @returns Content data */ getNodeContent(nodeId: string): Observable { return Observable.fromPromise(this.apiService.getInstance().core.nodesApi.getFileContent(nodeId).then((dataContent) => { @@ -173,10 +163,11 @@ export class ContentService { } /** - * Create a folder + * Creates a folder. * @param relativePath Location to create the folder * @param name Folder name * @param parentId Node ID of parent folder + * @returns Information about the new folder */ createFolder(relativePath: string, name: string, parentId?: string): Observable { return Observable.fromPromise(this.apiService.getInstance().nodes.createFolder(name, relativePath, parentId)) @@ -193,8 +184,8 @@ export class ContentService { /** * Gets a Node via its node ID. - * @param nodeId - * @param opts + * @param nodeId ID of the target node + * @param opts Options supported by JSAPI * @returns Details of the folder */ getNode(nodeId: string, opts?: any): Observable { @@ -202,10 +193,10 @@ export class ContentService { } /** - * Check if the user has permissions on that node + * Checks if the user has permissions on that node * @param node Node to check allowableOperations * @param permission Create, delete, update, updatePermissions, !create, !delete, !update, !updatePermissions - * + * @returns True if the user has the required permissions, false otherwise */ hasPermission(node: Node, permission: PermissionsEnum | string): boolean { let hasPermission = false; @@ -239,9 +230,9 @@ export class ContentService { } /** - * Check if the node has the properties allowableOperations + * Checks if the node has the properties allowableOperations * @param node Node to check allowableOperations - * + * @returns True if the node has the property, false otherwise */ hasAllowableOperations(node: any): boolean { return node && node.allowableOperations ? true : false; diff --git a/lib/core/services/dynamic-component-mapper.service.ts b/lib/core/services/dynamic-component-mapper.service.ts index c3fdd2f23b..b304a4c2f5 100644 --- a/lib/core/services/dynamic-component-mapper.service.ts +++ b/lib/core/services/dynamic-component-mapper.service.ts @@ -35,6 +35,7 @@ export abstract class DynamicComponentMapper { * Gets the currently active ComponentTypeResolver function for a field type. * @param type The type whose resolver you want * @param defaultValue Default type returned for types that are not yet mapped + * @returns Resolver function */ getComponentTypeResolver(type: string, defaultValue: Type<{}> = this.defaultValue): DynamicComponentResolveFunction { if (type) { @@ -70,6 +71,7 @@ export abstract class DynamicComponentMapper { * Finds the component type that is needed to render a form field. * @param model [Form field model](form-field.model.md) for the field to render * @param defaultValue Default type returned for field types that are not yet mapped. + * @returns Component type */ resolveComponentType(model: DynamicComponentModel, defaultValue: Type<{}> = this.defaultValue): Type<{}> { if (model) { diff --git a/lib/core/services/favorites-api.service.ts b/lib/core/services/favorites-api.service.ts index 930d4c3575..fa5817ffd8 100644 --- a/lib/core/services/favorites-api.service.ts +++ b/lib/core/services/favorites-api.service.ts @@ -62,6 +62,12 @@ export class FavoritesApiService { return this.apiService.getInstance().core.favoritesApi; } + /** + * Gets the favorites for a user. + * @param personId ID of the user + * @param options Options supported by JSAPI + * @returns List of favorites + */ getFavorites(personId: string, options?: any): Observable { const { favoritesApi, handleError } = this; const defaultOptions = { diff --git a/lib/core/userinfo/services/bpm-user.service.ts b/lib/core/userinfo/services/bpm-user.service.ts index 25a644b09b..ae956aa7d6 100644 --- a/lib/core/userinfo/services/bpm-user.service.ts +++ b/lib/core/userinfo/services/bpm-user.service.ts @@ -36,8 +36,8 @@ export class BpmUserService { } /** - * get Current User information for BPM - * @param userName - the user name + * Gets information about the current user. + * @returns User information object */ getCurrentUserInfo(): Observable { return Observable.fromPromise(this.apiService.getInstance().activiti.profileApi.getProfile()) @@ -45,6 +45,10 @@ export class BpmUserService { .catch(err => this.handleError(err)); } + /** + * Gets the current user's profile image as a URL. + * @returns URL string + */ getCurrentUserProfileImage(): string { return this.apiService.getInstance().activiti.profileApi.getProfilePictureUrl(); }