diff --git a/docs/core/datatable.component.md b/docs/core/datatable.component.md index 49f640d05c..a69329b4b2 100644 --- a/docs/core/datatable.component.md +++ b/docs/core/datatable.component.md @@ -1,7 +1,9 @@ --- Added: v2.0.0 Status: Active +Last reviewed: 2018-03-21 --- + # DataTable component Displays data as a table with customizable columns and presentation. @@ -25,7 +27,7 @@ See it live: [DataTable Quickstart](https://embed.plnkr.co/80qr4YFBeHjLMdAV0F6l/ - [Card view](#card-view) - [Custom Empty content template](#custom-empty-content-template) - [Loading content template](#loading-content-template) - - [Events](#events-1) + - [Using events](#using-events) - [See also](#see-also) @@ -123,33 +125,33 @@ export class DataTableDemo { ### Properties -| Name | Type | Default | Description | -| ---- | ---- | ------- | ----------- | -| selectionMode | string | 'single' | Row selection mode. Can be none, `single` or `multiple`. For `multiple` mode you can use Cmd (macOS) or Ctrl (Win) modifier key to toggle selection for multiple rows. | -| rowStyle | string | | The inline style to apply to every row, see [NgStyle](https://angular.io/docs/ts/latest/api/common/index/NgStyle-directive.html) docs for more details and usage examples | -| rowStyleClass | string | | The CSS class to apply to every row | -| data | DataTableAdapter | instance of **ObjectDataTableAdapter** | data source | -| rows | Object\[] | \[] | The rows that the datatable should show | -| multiselect | boolean | false | Toggles multiple row selection, renders checkboxes at the beginning of each row | -| actions | boolean | false | Toggles data actions column | -| actionsPosition | string (left\|right) | right | Position of the actions dropdown menu. | -| fallbackThumbnail | string | | Fallback image for row where thumbnail is missing | -| contextMenu | boolean | false | Toggles custom context menu for the component | -| allowDropFiles | boolean | false | Toggle file drop support for rows (see **ng2-alfresco-core/UploadDirective** for more details) | -| loading | boolean | false | Flag that indicates if the datatable is in loading state and needs to show the loading template. Read the documentation above to see how to configure a loading template | -| showHeader | boolean | true | Toggles header visibility | -| display | string | 'list' | change the display mode can be one of the values provided by the enum : **list**, **gallery** | -| selection | DataRow\[] | \[] | Contains selected rows | - +| Name | Type | Default value | Description | +| ---- | ---- | ------------- | ----------- | +| data | `DataTableAdapter` | | Data source for the table | +| display | `string` | `DisplayMode.List` | Selects the display mode of the table. Can be "list" or "gallery". | +| rows | `any[]` | `[]` | The rows that the datatable will show. | +| selectionMode | `string` | `'single'` | Row selection mode. Can be none, `single` or `multiple`. For `multiple` mode, you can use Cmd (macOS) or Ctrl (Win) modifier key to toggle selection for multiple rows. | +| multiselect | `boolean` | `false` | Toggles multiple row selection, which renders checkboxes at the beginning of each row. | +| actions | `boolean` | `false` | Toggles the data actions column. | +| actionsPosition | `string` | `'right'` | Position of the actions dropdown menu. Can be "left" or "right". | +| fallbackThumbnail | `string` | | Fallback image for rows where the thumbnail is missing. | +| contextMenu | `boolean` | `false` | Toggles custom context menu for the component. | +| allowDropFiles | `boolean` | `false` | Toggles file drop support for rows (see [Upload directive](upload.directive.md) for further details). | +| rowStyle | `string` | | The inline style to apply to every row. See [NgStyle](https://angular.io/docs/ts/latest/api/common/index/NgStyle-directive.html) docs for more details and usage examples. | +| rowStyleClass | `string` | `''` | The CSS class to apply to every row. | +| showHeader | `boolean` | `true` | Toggles the header. | +| loading | `boolean` | `false` | Flag that indicates if the datatable is in loading state and needs to show the loading template (see the docs to learn how to configure a loading template). | +| noPermission | `boolean` | `false` | Flag that indicates if the datatable should show the "no permission" template. | + ### Events -| Name | Description | -| ---- | ----------- | -| [rowClick](#rowclick-event) | Emitted when user clicks the row | -| [rowDblClick](#rowdblclick-event) | Emitted when user double-clicks the row | -| [showRowContextMenu](#showrowcontextmenu-event) | Emitted before context menu is displayed for a row | -| [showRowActionsMenu](#showrowactionsmenu-event) | Emitted before actions menu is displayed for a row | -| [executeRowAction](#executerowaction-event) | Emitted when row action is executed by user | +| Name | Type | Description | +| ---- | ---- | ----------- | +| rowClick | `EventEmitter` | Emitted when the user clicks a row. | +| rowDblClick | `EventEmitter` | Emitted when the user double-clicks a row. | +| showRowContextMenu | `EventEmitter` | Emitted before the context menu is displayed for a row. | +| showRowActionsMenu | `EventEmitter` | Emitted before the actions menu is displayed for a row. | +| executeRowAction | `EventEmitter` | Emitted when the user executes a row action. | ## Details @@ -158,17 +160,17 @@ export class DataTableDemo { The column layout and row data are supplied to the table using an object that implements the DataTableAdapter interface. This interface hides the internal details of the class that provides the data, which gives a lot of flexibility in how the data can be stored and accessed. The DataTable -library includes a standard adapter class called ObjectDataTableAdapter that is useful for many -common uses. See the [DataTableAdapter](datatable-adapter.interface.md) for full details about the interface and -the ObjectDataTableAdapter class. +library includes a standard adapter class called `ObjectDataTableAdapter` that is useful in many +common cases. See the [DataTableAdapter](datatable-adapter.interface.md) for full details about the interface and the `ObjectDataTableAdapter` class. ### Customizing columns -You can define custom HTML templates for columns and also add tooltips, automatic column title translation and other features. See the DataColumn component page for more information. +You can define custom HTML templates for columns and also add tooltips, automatic column title translation and other features. See the [Data Column component](data-column.component.md) page +for more information. ### DataTable DOM Events -Below are the DOM events raised by DataTable component. +Below are the DOM events emitted by the DataTable component. These events bubble up the component tree and can be handled by any parent component. | Name | Description | @@ -200,7 +202,7 @@ onRowClick(event) { ### Card view -If you want to enable the card view mode you need to set to 'gallery' the input parameter [display] : +Set the `display` property to "gallery" to enable Card View mode: ```html ``` -You can use the empty list component if you want to show the default ADF empty template. +You can use the empty list component to show the default ADF empty template. -You can use any HTML layout or Angular component as a content of the empty template section by using the special `, , ` elements: +You can place any HTML layout or Angular component as content in the empty template section +by using the ``, ``, and `` +elements: ```html ` and `` can be used together +Note: the `` and `` can be used together. -### Events +### Using events #### row-keyup DOM event -Raised on the 'keyup' event for the focused row. +Emitted on the 'keyup' event for the focused row. -This is an instance of the `CustomEvent` with the `details` property containing the following object: +This is an instance of `CustomEvent` with the `details` property containing the following object: ```ts row: DataRow, @@ -326,7 +329,7 @@ sender: any #### rowClick event -Emitted when user clicks a row. +Emitted when the user clicks a row. Event properties: @@ -344,11 +347,11 @@ onRowClicked(event: DataRowEvent) { } ``` -This event is cancellable, you can use `event.preventDefault()` to prevent default behaviour. +This event is cancellable. You can use `event.preventDefault()` to prevent the default behavior. #### rowDblClick event -Emitted when user double-clicks a row. +Emitted when the user double-clicks a row. Event properties: @@ -366,14 +369,14 @@ onRowDblClicked(event: DataRowEvent) { } ``` -This event is cancellable, you can use `event.preventDefault()` to prevent default behaviour. +This event is cancellable. You can use `event.preventDefault()` to prevent the default behavior. #### showRowContextMenu event -Emitted before context menu is displayed for a row. +Emitted before the context menu is displayed for a row. -Note that DataTable itself does not populate context menu items, -you can provide all necessary content via handler. +Note that the DataTable itself does not populate the context menu with items. +You can provide all necessary content via the handler. Event properties: @@ -396,17 +399,17 @@ onShowRowContextMenu(event: DataCellEvent) { } ``` -This event is cancellable, you can use `event.preventDefault()` to prevent default behaviour. +This event is cancellable. You can use `event.preventDefault()` to prevent the default behavior. -DataTable will automatically render provided menu items. +The DataTable will automatically render the supplied menu items. See the [ContextMenu](https://www.npmjs.com/package/ng2-alfresco-core) -documentation for more details on context actions format and behaviour. +documentation for more details on the format and behavior of context actions. #### showRowActionsMenu event -Emitted before actions menu is displayed for a row. -Requires `actions` property to be set to `true`. +Emitted before the actions menu is displayed for a row. +Requires the `actions` property to be set to `true`. Event properties: @@ -417,19 +420,19 @@ value: { } ``` -Note that DataTable itself does not populate action menu items, -you can provide all necessary content via handler. +Note that the DataTable itself does not populate the action menu with items. +You can provide all necessary content via the handler. -This event is cancellable, you can use `event.preventDefault()` to prevent default behaviour. +This event is cancellable. You can use `event.preventDefault()` to prevent the default behavior. #### executeRowAction event -Emitted when a row action is executed by the user. +Emitted when the user executes a row action. -Usually accompanies `showRowActionsMenu` event. -DataTable itself does not execute actions but provides support for external -integration. If there were actions provided with `showRowActionsMenu` event -then `executeRowAction` will be automatically executed when user clicks +This usually accompanies a `showRowActionsMenu` event. +The DataTable itself does not execute actions but provides support for external +integration. If actions are provided using the `showRowActionsMenu` event +then `executeRowAction` will be automatically executed when the user clicks a corresponding menu item. ```html @@ -467,16 +470,12 @@ onExecuteRowAction(event: DataRowActionEvent) { ![](../docassets/images/datatable-actions-console.png) -Developers are allowed to use any payloads as row actions. -The only requirement for the objects is having `title` property. +You can use any payloads for row actions. The only requirement for the objects is that they +must have a `title` property. -Once corresponding action is clicked in the dropdown menu DataTable invokes `executeRowAction` event -where you can handle the process, inspect the action payload and all custom properties defined earlier, -and do corresponding actions. - - - - +When an action is selected in the dropdown menu, the DataTable invokes the `executeRowAction` event. +Use this to handle the response, inspect the action payload (and all custom properties defined +earlier), and perform the corresponding actions. ## See also @@ -484,4 +483,3 @@ and do corresponding actions. - [Pagination component](pagination.component.md) - [DataTableAdapter](datatable-adapter.interface.md) - [Document list component](../content-services/document-list.component.md) - diff --git a/docs/process-services/tasklist.service.md b/docs/process-services/tasklist.service.md index 5633dd06ed..484ba93393 100644 --- a/docs/process-services/tasklist.service.md +++ b/docs/process-services/tasklist.service.md @@ -1,28 +1,97 @@ --- Added: v2.0.0 Status: Active +Last reviewed: 2018-03-22 --- + # Tasklist Service -Manage Task Instances. - -## Importing - -```ts -import { TaskListService, TaskDetailsModel, TaskQueryRequestRepresentationModel, TaskListModel, Form } from '@alfresco/adf-process-services'; -import { TaskUpdateRepresentation } from 'alfresco-js-api'; - -export class SomePageComponent implements OnInit { - - constructor(private tasklistService: TaskListService) { - } -``` +Manages Task Instances. ## Methods -#### getTaskDetails(taskId: string): Observable`` +- `getFilterForTaskById(taskId: string, filterList: FilterRepresentationModel[]): Observable` + Gets all the filters in the list that belong to a task. + - `taskId` - ID of the target task + - `filterList` - List of filters to search through +- `isTaskRelatedToFilter(taskId: string, filter: FilterRepresentationModel): Observable` + Checks if a taskId is filtered with the given filter. + - `taskId` - ID of the target task + - `filter` - The filter you want to check +- `getTasks(requestNode: TaskQueryRequestRepresentationModel): Observable` + Gets all the tasks matching the supplied query. + - `requestNode` - Query to search for tasks +- `findTasksByState(requestNode: TaskQueryRequestRepresentationModel, state?: string): Observable` + Gets tasks matching a query and state value. + - `requestNode` - Query to search for tasks + - `state` - (Optional) Task state. Can be "open" or "completed". +- `findAllTaskByState(requestNode: TaskQueryRequestRepresentationModel, state?: string): Observable` + Gets all tasks matching a query and state value. + - `requestNode` - Query to search for tasks. + - `state` - (Optional) Task state. Can be "open" or "completed". +- `findAllTasksWithoutState(requestNode: TaskQueryRequestRepresentationModel): Observable` + Get all tasks matching the supplied query but ignoring the task state. + - `requestNode` - Query to search for tasks +- `getTaskDetails(taskId: string): Observable` + Gets details for a task. + - `taskId` - ID of the target task. +- `getTaskChecklist(id: string): Observable` + Gets the checklist for a task. + - `id` - ID of the target task +- `getFormList(): Observable` + Gets all available reusable forms. -Get Task Instance metadata for passed in Task Instance ID: +- `attachFormToATask(taskId: string, formId: number): Observable` + Attaches a form to a task. + - `taskId` - ID of the target task + - `formId` - ID of the form to add +- `addTask(task: TaskDetailsModel): Observable` + Adds a subtask (ie, a checklist task) to a parent task. + - `task` - The task to add +- `deleteTask(taskId: string): Observable` + Deletes a subtask (ie, a checklist task) from a parent task. + - `taskId` - The task to delete +- `completeTask(taskId: string): any` + Gives completed status to a task. + - `taskId` - ID of the target task +- `getTotalTasks(requestNode: TaskQueryRequestRepresentationModel): Observable` + Gets the total number of the tasks found by a query. + - `requestNode` - Query to search for tasks +- `createNewTask(task: TaskDetailsModel): Observable` + Creates a new standalone task. + - `task` - Details of the new task +- `assignTask(taskId: string, requestNode: any): Observable` + Assigns a task to a user or group. + - `taskId` - The task to assign + - `requestNode` - User or group to assign the task to +- `assignTaskByUserId(taskId: string, userId: number): Observable` + Assigns a task to a user. + - `taskId` - ID of the task to assign + - `userId` - ID of the user to assign the task to +- `claimTask(taskId: string): Observable` + Claims a task for the current user. + - `taskId` - ID of the task to claim +- `unclaimTask(taskId: string): Observable` + Unclaims a task for the current user. + - `taskId` - ID of the task to unclaim +- `updateTask(taskId: any, updated): Observable` + Updates the details (name, description, due date) for a task. + - `taskId` - ID of the task to update + - `updated` - Data to update the task (as a \`TaskUpdateRepresentation\` instance). +- `fetchTaskAuditPdfById(taskId: string): Observable` + Fetches the Task Audit information in PDF format. + - `taskId` - ID of the target task +- `fetchTaskAuditJsonById(taskId: string): Observable` + Fetch the Task Audit information in JSON format + - `taskId` - ID of the target task + +## Details + +### Task details + +Several of the methods return one or more `TaskDetailsModel` instances corresponding +to tasks or subtasks matched by a query of some kind. For example, `getTaskDetails` +could be used as shown below: ```ts const taskInstanceId = '15303'; @@ -33,9 +102,9 @@ this.tasklistService.getTaskDetails(taskInstanceId).subscribe( (taskInstance: Ta }); ``` -The `taskInstanceId` refers to a Task Instance identifier in APS. -The returned `taskInstance` object is of type `TaskDetailsModel` and looks like in this sample: +The resulting `TaskDetailsModel` object contains information like the following: +``` adhocTaskCanBeReassigned: false assignee: UserProcessModel {pictureId: null, id: 1, email: "admin@app.activiti.com", firstName: null, lastName: "Administrator"} category: null @@ -67,64 +136,12 @@ The returned `taskInstance` object is of type `TaskDetailsModel` and looks like processInstanceName: null processInstanceStartUserId: "1" taskDefinitionKey: "clarifyInvoice" - -#### getTaskChecklist(id: string): Observable`` - -Get all the sub-task instances for a Task Instance, also called the check list: - -```ts -const parentTaskId = '15303'; -this.tasklistService.getTaskChecklist(parentTaskId).subscribe( (subTasks: TaskDetailsModel[]) => { - console.log('Sub Tasks: ', subTasks); -}, error => { - console.log('Error: ', error); -}); ``` -The response is an array of `TaskDetailsModel` representing the sub-tasks: +### Queries - Sub Tasks: - 0: - adhocTaskCanBeReassigned: false - assignee: UserProcessModel {pictureId: null, id: 1, email: "admin@app.activiti.com", firstName: null, lastName: "Administrator"} - category: "2" - created: "2017-10-29T07:29:28.881+0000" - description: null - dueDate: null - duration: null - endDate: null - executionId: null - formKey: null - id: "74745" - initiatorCanCompleteTask: false - involvedPeople: undefined - managerOfCandidateGroup: false - memberOfCandidateGroup: false - memberOfCandidateUsers: false - name: "Double check invoice amount" - parentTaskId: "15303" - parentTaskName: "Clarify Invoice - Invoice-10292.pdf" - priority: 50 - processDefinitionCategory: null - processDefinitionDeploymentId: null - processDefinitionDescription: null - processDefinitionId: null - processDefinitionKey: null - processDefinitionName: null - processDefinitionVersion: 0 - processInstanceId: null - processInstanceName: null - processInstanceStartUserId: null - taskDefinitionKey: null - 1 : - {processDefinitionVersion: 0, id: "74746", name: "Verify with the person that did the purchase", priority: 50, assignee: UserProcessModel, …} - -Looking at the `TaskDetailsModel` for a sub-task we can see that it has a parent task ID that matches what we specified -when calling this method. - -#### getTasks(requestNode: TaskQueryRequestRepresentationModel): Observable`` - -Get tasks matching passed in query definition: +Some of the methods run a search query contained in a `TaskQueryRequestRepresentationModel` and +return the matched tasks. Below is an example of how you might run a query using `getTasks`: ```ts const taskQuery: TaskQueryRequestRepresentationModel = { @@ -146,22 +163,23 @@ this.tasklistService.getTasks(taskQuery).subscribe( (taskListModel: TaskListMode }); ``` -In the above example we query for all Task Instances associated with a Process Application with -ID 2. We set `size` to 5, which means that the query will return max 5 task instances. +In this example, the query specifies all Task Instances for the process app with +ID 2. Setting the `size` property to 5 ensures the query will return no more than +five task instances in the results. -We can mix and match the query parameters to narrow down the task list that is returned. -If you are just interested in Task Instances related to a specific Process Instance, -then set the `processInstanceId`. If you want to see all tasks related to a specific type of processes, -then you should set the `processDefinitionId` property. +You can use various query parameters to narrow down the scope of the results. +If you are only interested in task instances related to a specific process instance, +then you can set the `processInstanceId` accordingly. If you want all tasks related to +a type of process then you can use `processDefinitionId`. -You can use the `state` property to define if only `completed` or only `open` tasks should be returned. If you -specify `null` for state then `open` will be assumed. +Use the `state` property to indicate that you want only "completed" or "open" tasks (this +defaults to "open" if you leave it undefined). -The `assignment` property can be used to filter tasks based on how they are assigned (or not assigned yet). +The `assignment` property filters tasks based on how they are assigned (or not assigned yet). Use `assignee` if you are interested in tasks that are assigned to a user. If you want to see pooled tasks (i.e. tasks that needs to be claimed by a user), then use `candidate`. -A `TaskListModel` object is returned for a successful query and the `data` property is an array of +A successful query returns a `TaskListModel` with the `data` property set to an array of `TaskDetailsModel`: data: @@ -175,480 +193,17 @@ A `TaskListModel` object is returned for a successful query and the `data` prope start: 0 total: 10 -We can see that this query resulted in 10 tasks (see `total`), but only 5 were returned as we set `size` to `5`. +The `total` property indicates that actual number of tasks that were found, but the `size` property +limited the found set to five items. -#### getTotalTasks(requestNode: TaskQueryRequestRepresentationModel): Observable`` - -Get total number of tasks matching passed in query definition: +### Importing ```ts -const taskQuery: TaskQueryRequestRepresentationModel = { - appDefinitionId: '2', - processInstanceId: null, - processDefinitionId: null, - text: null, - assignment: null, - state: 'open', - sort: 'created_asc', - page: 0, - size: 5, - start: null -}; -this.tasklistService.getTotalTasks(taskQuery).subscribe( (response: any) => { - console.log('Total: ', response); -}, error => { - console.log('Error: ', error); -}); +import { TaskListService, TaskDetailsModel, TaskQueryRequestRepresentationModel, TaskListModel, Form } from '@alfresco/adf-process-services'; +import { TaskUpdateRepresentation } from 'alfresco-js-api'; + +export class SomePageComponent implements OnInit { + + constructor(private tasklistService: TaskListService) { + } ``` - -This is pretty much the same type of query as the `getTasks` method, except that here we just -return how many Task Instances it matched in the `total` property: - - data:[] - size: 0 - start: 0 - total: 10 - -When you call this method it always sets the `size` property to `0`. - -#### findTasksByState(requestNode: TaskQueryRequestRepresentationModel, state?: string): Observable`` - -Find and return Task Instances by state `open` or `completed` and query model: - -```ts -const taskState = 'open'; -const taskQuery: TaskQueryRequestRepresentationModel = { - appDefinitionId: '2', - processInstanceId: null, - processDefinitionId: null, - text: null, - assignment: null, - state: 'open', - sort: 'created_asc', - page: 0, - size: 5, - start: null -}; - -this.tasklistService.findTasksByState(taskQuery, taskState).subscribe( (taskList: TaskListModel) => { - console.log('Task list: ', taskList); -}, error => { - console.log('Error: ', error); -}); -``` - -The number of tasks that are returned is controlled by the `size` property. - -This is a convenience method on top of the `getTasks` method. It overwrites the `requestNode.state` property -with passed in `state` before making the call to `getTasks`. -For an example of the response see the `getTasks` method. - -#### findAllTaskByState(requestNode: TaskQueryRequestRepresentationModel, state?: string): Observable`` - -Find and return all Task Instances by state `open` or `completed` and query model: - -```ts -const taskState = 'open'; -const taskQuery: TaskQueryRequestRepresentationModel = { - appDefinitionId: '2', - processInstanceId: null, - processDefinitionId: null, - text: null, - assignment: null, - state: 'open', - sort: 'created_asc', - page: 0, - size: 5, - start: null -}; - -this.tasklistService.findAllTaskByState(taskQuery, taskState).subscribe( (taskList: TaskListModel) => { - console.log('Task list: ', taskList); -}, error => { - console.log('Error: ', error); -}); -``` - -This is a convenience method on top of the `getTasks` method. It overwrites the `requestNode.state` property with -passed in `state` before making any other calls. Before making the `getTasks` call it will first call the -`getTotalTasks` method to get the total number of tasks that match query and state. It then overwrite the -`requestNode.size` with the total so all matching tasks are returned when finnally making the `getTasks` call. - -**Note** that this can return a lot of data if you are not careful. - -#### findAllTasksWithoutState(requestNode: TaskQueryRequestRepresentationModel): Observable`` - -Find and return all Task Instances that matches query model, regardless of state: - -```ts -const taskQuery: TaskQueryRequestRepresentationModel = { - appDefinitionId: '2', - processInstanceId: null, - processDefinitionId: null, - text: null, - assignment: null, - state: null, - sort: 'created_asc', - page: 0, - size: 5, - start: null -}; - -this.tasklistService.findAllTasksWithoutState(taskQuery).subscribe( (taskList: TaskListModel) => { - console.log('Task list: ', taskList); -}, error => { - console.log('Error: ', error); -}); -``` - -This method can be used when you have a task query that should return all tasks regardless of the state they -are in. You cannot achieve this with the `getTasks` method. If you specify a `size` it is overwritten. -Internally it basically calls `findTasksByState(requestNode, 'open')` and -`findAllTaskByState(requestNode, 'completed')`. - -**Note** that this can return a lot of data if you are not careful. - -#### assignTaskByUserId(taskId: string, userId: number): Observable`` - -Assign a Task Instance to a user via the User ID: - -```ts -const taskId = '15303'; -const userId = 1; -this.tasklistService.assignTaskByUserId(taskId, userId).subscribe( (taskInstance: TaskDetailsModel) => { - console.log('Task instance: ', taskInstance); -}, error => { - console.log('Error: ', error); -}); -``` - -The user ID identifies a User in APS. - -#### assignTask(taskId: string, requestNode: any): Observable`` - -Assign a task to a user via a user object with an `id` property, for example: - -```ts -const taskId = '15303'; -const user = { id: 1, email: 'admin@app.activiti.com', firstName: 'APS', lastName: 'Admin' }; -this.tasklistService.assignTask(taskId, user).subscribe( (taskInstance: TaskDetailsModel) => { - console.log('Task instance: ', taskInstance); -}, error => { - console.log('Error: ', error); -}); -``` - -This method does the same as the `assignTaskByUserId` method, the only difference is that this -method can be used when you have an object where the User ID is contained in an `id` property. - -#### claimTask(taskId: string): Observable`` - -Claim a pooled task (i.e. candidate task) as current user so it can be worked on and later on completed: - -```ts -const taskId = '15368'; -this.tasklistService.claimTask(taskId).subscribe( (taskInstance: TaskDetailsModel) => { - console.log('Task instance: ', taskInstance); -}, error => { - console.log('Error: ', error); -}); -``` - -The response will be `null` if the task was claimed successfully. - -The task assignment changes from `candidate` to `assignee`. - -#### unclaimTask(taskId: string): Observable`` - -Return a claimed task to the pool (i.e. make it a candidate task): - -```ts -const taskId = '15368'; -this.tasklistService.unclaimTask(taskId).subscribe( (taskInstance: TaskDetailsModel) => { - console.log('Task instance: ', taskInstance); -}, error => { - console.log('Error: ', error); -}); -``` - -The task assignment changes from `assignee` to `candidate`. - -#### completeTask(taskId: string) - -Complete a Task Instance as current user and progress Process Instance: - -```ts -const taskId = '15176'; -this.tasklistService.completeTask(taskId); -``` - -This only works if the Task Instance has only one Outcome (i.e. the default `Complete` one). -If the Task Instance has multiple Outcomes, such as Approve and Reject, then this method does not -work, and the Task Instance has to be completed via its associated form. Otherwise you will see an error such as: - -_ERROR Error: Uncaught (in promise): Error: {"message":"Task must be completed using it's form","messageKey":"GENERAL.ERROR.BAD-REQUEST"}_ - -#### updateTask(taskId: any, updated): Observable`` - -Update name, description, and due date for a Task Instance: - -```ts -const taskId = '80002'; -const updateData: TaskUpdateRepresentation = { - description: 'Updated description', - dueDate: new Date(2018, 1, 10, 11, 0, 0, 0), - name: 'Updated name' -}; -this.tasklistService.updateTask(taskId, updateData).subscribe( (updatedTaskDetails: TaskDetailsModel) => { - console.log('Updated task: ', updatedTaskDetails); -}, error => { - console.log('Error: ', error); -}); -``` - -The response is all info about the updated Task Instance, in this example a stand-alone task was updated so there -is no associated process: - - adhocTaskCanBeReassigned: false - assignee: undefined - category: null - created: Mon Nov 13 2017 16:34:49 GMT+0000 (GMT) {} - description: "Updated description" - dueDate: Sat Feb 10 2018 11:00:00 GMT+0000 (GMT) {} - duration: NaN - endDate: null - executionId: null - formKey: "5005" - id: "80002" - initiatorCanCompleteTask: false - managerOfCandidateGroup: false - memberOfCandidateGroup: false - memberOfCandidateUsers: false - name: "Updated name" - parentTaskId: null - parentTaskName: null - priority: 50 - processDefinitionCategory: null - processDefinitionDeploymentId: null - processDefinitionDescription: null - processDefinitionId: null - processDefinitionKey: null - processDefinitionName: null - processDefinitionVersion: 0 - processInstanceId: null - processInstanceName: null - processInstanceStartUserId: null - taskDefinitionKey: null - -#### createNewTask(task: TaskDetailsModel): Observable`` - -Create a new stand-alone Task Instance that is not associated with a Process Instance: - -```ts -const taskDetails = new TaskDetailsModel({ - name: 'Some Task', - description: 'A new stand-alone task' -}); - -this.tasklistService.createNewTask(taskDetails).subscribe( (createdTaskDetails: TaskDetailsModel) => { - console.log('Created task details: ', createdTaskDetails); -}, error => { - console.log('Error: ', error); -}); -``` - -In this case we are creating a disconnected Task Instance that is not associated with a form (i.e. `formKey: null`) -and that is not assigned to a user (i.e. `assignee: null`). - -The response looks like this, we can see that an ID was generated for the Task Instance: - - Created task details: - adhocTaskCanBeReassigned: false - assignee: null - category: null - created: Mon Nov 13 2017 16:34:49 GMT+0000 (GMT) {} - description: "A new stand-alone task" - dueDate: null - duration: null - endDate: null - executionId: null - formKey: null - id: "80002" - initiatorCanCompleteTask: false - involvedPeople: undefined - managerOfCandidateGroup: false - memberOfCandidateGroup: false - memberOfCandidateUsers: false - name: "Some Task" - parentTaskId: null - parentTaskName: null - priority: 50 - processDefinitionCategory: null - processDefinitionDeploymentId: null - processDefinitionDescription: null - processDefinitionId: null - processDefinitionKey: null - processDefinitionName: null - processDefinitionVersion: 0 - processInstanceId: null - processInstanceName: null - processInstanceStartUserId: null - taskDefinitionKey: null - -See the `attachFormToATask` method for how to attach a form to the User Task. And see the `assignTaskByUserId` method -for how to assign a user to the new Task Instance. - -#### attachFormToATask(taskId: string, formId: number): Observable`` - -Attach a form to a User Task: - -```ts -const taskId = '80002'; -const formId = 5005; -this.tasklistService.attachFormToATask(taskId, formId).subscribe( (response: any) => { - console.log('Assign form response: ', response); -}, error => { - console.log('Error: ', error); -}); -``` - -In this case we need to have a task created and know the ID for it, such as with the `createNewTask` method. -We also need to have a form defined in APS and know the ID for it (you can see the ID for a form in the URL -in APS when you work with it). See the `getFormList` method for how fetch a list of available forms. - -The response will be `null` if form was attached successfully to task. - -#### getFormList(): Observable`
` - -Get a list of the available reusable forms: - -```ts -this.tasklistService.getFormList().subscribe( (formList: Form[]) => { - console.log('Available forms: ', formList); -}, error => { - console.log('Error: ', error); -}); -``` - -A successful response looks like this: - - Available forms: - - 0: - id: 5005 - name: "Name Info" - 1: {name: "cm:folder", id: 3012} - 2: {name: "Alfresco Node Form", id: 3011} - 3: {name: "Employee", id: 3010} - -The form id property can be used with the `attachFormToATask` method. - -**Note**. Referenced forms that are associated with specific tasks in a process are not included in this list. -Only reusable forms are included. - -#### addTask(task: TaskDetailsModel): Observable`` - -Add a Sub-Task (i.e. checklist task) to a parent Task Instance: - -```ts -const parentTaskId = '80002'; -const subTaskDetails = new TaskDetailsModel({ - parentTaskId: parentTaskId, - name: 'Check the invoice amount' -}); -this.tasklistService.addTask(subTaskDetails).subscribe( (updatedTaskDetails: TaskDetailsModel) => { - console.log('Sub-task info: ', updatedTaskDetails); -}, error => { - console.log('Error: ', error); -}); -``` - -The response includes the new sub-task id and also parent task name. -In this example the parent task was just a stand-alone task, so no process information is included: - - adhocTaskCanBeReassigned: false - assignee: null - category: null - created: Tue Nov 14 2017 13:32:41 GMT+0000 (GMT) {} - description: null - dueDate: null - duration: null - endDate: null - executionId: null - formKey: null - id: "80003" - initiatorCanCompleteTask: false - involvedPeople: undefined - managerOfCandidateGroup: false - memberOfCandidateGroup: false - memberOfCandidateUsers: false - name: "Check the invoice amount" - parentTaskId: "80002" - parentTaskName: "Some Task" - priority: 50 - processDefinitionCategory: null - processDefinitionDeploymentId: null - processDefinitionDescription: null - processDefinitionId: null - processDefinitionKey: null - processDefinitionName: null - processDefinitionVersion: 0 - processInstanceId: null - processInstanceName: null - processInstanceStartUserId:null - taskDefinitionKey: null - -#### deleteTask(taskId: string): Observable`` - -Delete a Sub-Task (i.e. checklist task): - -```ts -const taskId = '75100'; // Sub-task ID -this.tasklistService.deleteTask(taskId).subscribe( (taskDetails: TaskDetailsModel) => { - console.log('Deleted task info: ', taskDetails); -}, error => { - console.log('Error: ', error); -}); -``` - -**Note**. you can only delete so called checklist tasks with this method. - -#### fetchTaskAuditJsonById(taskId: string): Observable`` - -Fetch Task Audit log as JSON for a Task Instance ID: - -```ts -const taskId = '15368'; -this.tasklistService.fetchTaskAuditJsonById(taskId) - .subscribe( auditJson => { - console.log('Task Audit: ', auditJson); - }, error => { - console.log('Error: ', error); - }); -``` - -The response is JSON object with the Task Instance audit log: - - { - taskId: "15368", - taskName: "Approve by someone in Accounting", - processInstanceId: "15361", - processDefinitionName: "Process With Pooled task", - processDefinitionVersion: 1, - … - } - -#### fetchTaskAuditPdfById(taskId: string): Observable`` - -Fetch Task Audit log as JSON for a Task Instance ID: - -```ts -this.tasklistService.fetchTaskAuditPdfById(taskId) - .subscribe( (auditPdf: Blob) => { - console.log('Task Audit: ', auditPdf); - }, error => { - console.log('Error: ', error); - }); -``` - -The response is PDF with the Task Instance audit log. diff --git a/lib/config/DocProcessor/tools/tscProps.js b/lib/config/DocProcessor/tools/tscProps.js index 3aaaa1fb72..c594ef40a4 100644 --- a/lib/config/DocProcessor/tools/tscProps.js +++ b/lib/config/DocProcessor/tools/tscProps.js @@ -8,6 +8,10 @@ var unist = require("../unistHelpers"); var typescript_1 = require("typescript"); // Max number of characters in the text for the default value column. var maxDefaultTextLength = 20; +var nameExceptions = { + "datatable.component": "DataTableComponent", + "tasklist.service": "TaskListService" +}; function initPhase(aggData) { } exports.initPhase = initPhase; @@ -214,6 +218,8 @@ function initialCap(str) { return str[0].toUpperCase() + str.substr(1); } function fixAngularFilename(rawName) { + if (nameExceptions[rawName]) + return nameExceptions[rawName]; var name = rawName.replace(/\]|\(|\)/g, ''); var fileNameSections = name.split('.'); var compNameSections = fileNameSections[0].split('-'); diff --git a/lib/config/DocProcessor/tools/tscProps.ts b/lib/config/DocProcessor/tools/tscProps.ts index 514a59d533..acc8a16d70 100644 --- a/lib/config/DocProcessor/tools/tscProps.ts +++ b/lib/config/DocProcessor/tools/tscProps.ts @@ -12,6 +12,12 @@ import { JsxEmit, isClassDeclaration, PropertyDeclaration } from "typescript"; // Max number of characters in the text for the default value column. const maxDefaultTextLength = 20; +let nameExceptions = { + "datatable.component": "DataTableComponent", + "tasklist.service": "TaskListService" +} + + export function initPhase(aggData) { } @@ -301,6 +307,9 @@ function initialCap(str: string) { function fixAngularFilename(rawName: string) { + if (nameExceptions[rawName]) + return nameExceptions[rawName]; + var name = rawName.replace(/\]|\(|\)/g, ''); var fileNameSections = name.split('.'); diff --git a/lib/core/datatable/components/datatable/datatable.component.ts b/lib/core/datatable/components/datatable/datatable.component.ts index 550f9243a3..08502416b2 100644 --- a/lib/core/datatable/components/datatable/datatable.component.ts +++ b/lib/core/datatable/components/datatable/datatable.component.ts @@ -54,89 +54,92 @@ export class DataTableComponent implements AfterContentInit, OnChanges, DoCheck @ContentChild(DataColumnListComponent) columnList: DataColumnListComponent; - /* Data source for the table */ + /** Data source for the table */ @Input() data: DataTableAdapter; - /* change the display mode of the table list or gallery */ + /** Selects the display mode of the table. Can be "list" or "gallery". */ @Input() display: string = DisplayMode.List; - /* The rows that the datatable will show */ + /** The rows that the datatable will show. */ @Input() rows: any[] = []; - /* Row selection mode. Can be none, `single` or `multiple`. For `multiple` mode, + /** Row selection mode. Can be none, `single` or `multiple`. For `multiple` mode, * you can use Cmd (macOS) or Ctrl (Win) modifier key to toggle selection for multiple rows. */ @Input() selectionMode: string = 'single'; // none|single|multiple - /* Toggles multiple row selection, which renders checkboxes at the beginning of each row */ + /** Toggles multiple row selection, which renders checkboxes at the beginning of each row. */ @Input() multiselect: boolean = false; - /* Toggles data actions column */ + /** Toggles the data actions column. */ @Input() actions: boolean = false; - /* Position of the actions dropdown menu. Can be "left" or "right". */ + /** Position of the actions dropdown menu. Can be "left" or "right". */ @Input() actionsPosition: string = 'right'; // left|right - /* Fallback image for row where thumbnail is missing */ + /** Fallback image for rows where the thumbnail is missing. */ @Input() fallbackThumbnail: string; - /* Toggles custom context menu for the component */ + /** Toggles custom context menu for the component. */ @Input() contextMenu: boolean = false; - /* Toggle file drop support for rows (see Upload Directive for further details) */ + /** Toggles file drop support for rows (see + * [Upload directive](upload.directive.md) for further details). + */ @Input() allowDropFiles: boolean = false; - /* The inline style to apply to every row. See + /** The inline style to apply to every row. See * [NgStyle](https://angular.io/docs/ts/latest/api/common/index/NgStyle-directive.html) * docs for more details and usage examples. */ @Input() rowStyle: string; - /* The CSS class to apply to every row */ + /** The CSS class to apply to every row. */ @Input() rowStyleClass: string = ''; - /* Toggles the header */ + /** Toggles the header. */ @Input() showHeader: boolean = true; - /* Emitted when user clicks the row */ + /** Emitted when the user clicks a row. */ @Output() rowClick = new EventEmitter(); - /* Emitted when user double-clicks the row */ + /** Emitted when the user double-clicks a row. */ @Output() rowDblClick = new EventEmitter(); - /* Emitted before context menu is displayed for a row */ + /** Emitted before the context menu is displayed for a row. */ @Output() showRowContextMenu = new EventEmitter(); - /* Emitted before actions menu is displayed for a row */ + /** Emitted before the actions menu is displayed for a row. */ @Output() showRowActionsMenu = new EventEmitter(); - /* Emitted when row action is executed by user */ + /** Emitted when the user executes a row action. */ @Output() executeRowAction = new EventEmitter(); - /* Flag that indicates if the datatable is in loading state and needs to show the + /** Flag that indicates if the datatable is in loading state and needs to show the * loading template (see the docs to learn how to configure a loading template). */ @Input() loading: boolean = false; + /** Flag that indicates if the datatable should show the "no permission" template. */ @Input() noPermission: boolean = false; diff --git a/lib/process-services/task-list/services/tasklist.service.ts b/lib/process-services/task-list/services/tasklist.service.ts index b978e435a1..53695049ab 100644 --- a/lib/process-services/task-list/services/tasklist.service.ts +++ b/lib/process-services/task-list/services/tasklist.service.ts @@ -41,9 +41,9 @@ export class TaskListService { } /** - * Return all the filters in the list where the task id belong - * @param taskId - string - * @param filter - FilterRepresentationModel [] + * Gets all the filters in the list that belong to a task. + * @param taskId ID of the target task + * @param filterList List of filters to search through */ getFilterForTaskById(taskId: string, filterList: FilterRepresentationModel[]): Observable { return Observable.from(filterList) @@ -52,8 +52,8 @@ export class TaskListService { } /** - * Return the search node for query task based on the given filter - * @param filter - FilterRepresentationModel + * Gets the search query for a task based on the supplied filter. + * @param filter The filter to use */ private generateTaskRequestNodeFromFilter(filter: FilterRepresentationModel): TaskQueryRequestRepresentationModel { let requestNode = { @@ -66,9 +66,9 @@ export class TaskListService { } /** - * Check if a taskId is filtered with the given filter - * @param taskId - string - * @param filter - FilterRepresentationModel + * Checks if a taskId is filtered with the given filter. + * @param taskId ID of the target task + * @param filter The filter you want to check */ isTaskRelatedToFilter(taskId: string, filter: FilterRepresentationModel): Observable { let requestNodeForFilter = this.generateTaskRequestNodeFromFilter(filter); @@ -79,8 +79,8 @@ export class TaskListService { } /** - * Retrieve all the tasks filtered by filterModel - * @param filter - TaskFilterRepresentationModel + * Gets all the tasks matching the supplied query. + * @param requestNode Query to search for tasks */ getTasks(requestNode: TaskQueryRequestRepresentationModel): Observable { return Observable.fromPromise(this.callApiTasksFiltered(requestNode)) @@ -91,8 +91,9 @@ export class TaskListService { } /** - * Retrieve tasks filtered by filterModel and state - * @param filter - TaskFilterRepresentationModel + * Gets tasks matching a query and state value. + * @param requestNode Query to search for tasks + * @param state Task state. Can be "open" or "completed". */ findTasksByState(requestNode: TaskQueryRequestRepresentationModel, state?: string): Observable { if (state) { @@ -102,8 +103,9 @@ export class TaskListService { } /** - * Retrieve all tasks filtered by filterModel and state - * @param filter - TaskFilterRepresentationModel + * Gets all tasks matching a query and state value. + * @param requestNode Query to search for tasks. + * @param state Task state. Can be "open" or "completed". */ findAllTaskByState(requestNode: TaskQueryRequestRepresentationModel, state?: string): Observable { if (state) { @@ -116,8 +118,8 @@ export class TaskListService { } /** - * Retrieve all tasks filtered by filterModel irrespective of state - * @param filter - TaskFilterRepresentationModel + * Get all tasks matching the supplied query but ignoring the task state. + * @param requestNode Query to search for tasks */ findAllTasksWithoutState(requestNode: TaskQueryRequestRepresentationModel): Observable { return Observable.forkJoin( @@ -134,8 +136,8 @@ export class TaskListService { } /** - * Retrieve all the task details - * @param id - taskId + * Gets details for a task. + * @param taskId ID of the target task. */ getTaskDetails(taskId: string): Observable { return Observable.fromPromise(this.callApiTaskDetails(taskId)) @@ -146,8 +148,8 @@ export class TaskListService { } /** - * Retrieve all the task's checklist - * @param id - taskId + * Gets the checklist for a task. + * @param id ID of the target task */ getTaskChecklist(id: string): Observable { return Observable.fromPromise(this.callApiTaskChecklist(id)) @@ -162,7 +164,7 @@ export class TaskListService { } /** - * Retrieve all the form shared with this user + * Gets all available reusable forms. */ getFormList(): Observable { let opts = { @@ -181,13 +183,18 @@ export class TaskListService { }).catch(err => this.handleError(err)); } + /** + * Attaches a form to a task. + * @param taskId ID of the target task + * @param formId ID of the form to add + */ attachFormToATask(taskId: string, formId: number): Observable { return Observable.fromPromise(this.apiService.getInstance().activiti.taskApi.attachForm(taskId, {'formId': formId})).catch(err => this.handleError(err)); } /** - * Add a task - * @param task - TaskDetailsModel + * Adds a subtask (ie, a checklist task) to a parent task. + * @param task The task to add */ addTask(task: TaskDetailsModel): Observable { return Observable.fromPromise(this.callApiAddTask(task)) @@ -198,8 +205,8 @@ export class TaskListService { } /** - * Delete a task - * @param taskId - string + * Deletes a subtask (ie, a checklist task) from a parent task. + * @param taskId The task to delete */ deleteTask(taskId: string): Observable { return Observable.fromPromise(this.callApiDeleteTask(taskId)) @@ -207,8 +214,8 @@ export class TaskListService { } /** - * Make the task completed - * @param id - taskId + * Gives completed status to a task. + * @param taskId ID of the target task */ completeTask(taskId: string) { return Observable.fromPromise(this.apiService.getInstance().activiti.taskApi.completeTask(taskId)) @@ -217,8 +224,8 @@ export class TaskListService { } /** - * Return the total number of the tasks by filter - * @param requestNode - TaskFilterRepresentationModel + * Gets the total number of the tasks found by a query. + * @param requestNode Query to search for tasks */ public getTotalTasks(requestNode: TaskQueryRequestRepresentationModel): Observable { requestNode.size = 0; @@ -229,8 +236,8 @@ export class TaskListService { } /** - * Create a new standalone task - * @param task - TaskDetailsModel + * Creates a new standalone task. + * @param task Details of the new task */ createNewTask(task: TaskDetailsModel): Observable { return Observable.fromPromise(this.callApiCreateTask(task)) @@ -241,9 +248,9 @@ export class TaskListService { } /** - * Assign task to user/group - * @param taskId - string - * @param requestNode - any + * Assigns a task to a user or group. + * @param taskId The task to assign + * @param requestNode User or group to assign the task to */ assignTask(taskId: string, requestNode: any): Observable { let assignee = {assignee: requestNode.id}; @@ -254,6 +261,11 @@ export class TaskListService { }).catch(err => this.handleError(err)); } + /** + * Assigns a task to a user. + * @param taskId ID of the task to assign + * @param userId ID of the user to assign the task to + */ assignTaskByUserId(taskId: string, userId: number): Observable { let assignee = {assignee: userId}; return Observable.fromPromise(this.callApiAssignTask(taskId, assignee)) @@ -264,8 +276,8 @@ export class TaskListService { } /** - * Claim a task - * @param id - taskId + * Claims a task for the current user. + * @param taskId ID of the task to claim */ claimTask(taskId: string): Observable { return Observable.fromPromise(this.apiService.getInstance().activiti.taskApi.claimTask(taskId)) @@ -273,8 +285,8 @@ export class TaskListService { } /** - * Unclaim a task - * @param id - taskId + * Unclaims a task for the current user. + * @param taskId ID of the task to unclaim */ unclaimTask(taskId: string): Observable { return Observable.fromPromise(this.apiService.getInstance().activiti.taskApi.unclaimTask(taskId)) @@ -282,8 +294,9 @@ export class TaskListService { } /** - * Update due date - * @param dueDate - the new due date + * Updates the details (name, description, due date) for a task. + * @param taskId ID of the task to update + * @param updated Data to update the task (as a `TaskUpdateRepresentation` instance). */ updateTask(taskId: any, updated): Observable { return Observable.fromPromise(this.apiService.getInstance().activiti.taskApi.updateTask(taskId, updated)) @@ -291,8 +304,8 @@ export class TaskListService { } /** - * fetch the Task Audit information as a pdf - * @param taskId - the task id + * Fetches the Task Audit information in PDF format. + * @param taskId ID of the target task */ fetchTaskAuditPdfById(taskId: string): Observable { return Observable.fromPromise(this.apiService.getInstance().activiti.taskApi.getTaskAuditPdf(taskId)) @@ -300,8 +313,8 @@ export class TaskListService { } /** - * fetch the Task Audit information in a json format - * @param taskId - the task id + * Fetch the Task Audit information in JSON format + * @param taskId ID of the target task */ fetchTaskAuditJsonById(taskId: string): Observable { return Observable.fromPromise(this.apiService.getInstance().activiti.taskApi.getTaskAuditJson(taskId))