mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-05-12 17:04:57 +00:00
659805ab20
* [AAE-33090] Add optional checkbox for 'open next task' feature * [AAE-33090] move translation to LABEL property * [33090] add unit tests * add tests for checkbox value * [AAE-33090] remove some comments * [AAE-33090] update documentation * AAE-33090 kind of a typo * AAE-33090 remove all comments
349 lines
14 KiB
Markdown
349 lines
14 KiB
Markdown
---
|
|
Title: Form cloud component
|
|
Added: v3.2.0
|
|
Status: Active
|
|
Last reviewed: 2019-04-12
|
|
---
|
|
|
|
# [Form cloud component](../../../lib/process-services-cloud/src/lib/form/components/form-cloud.component.ts "Defined in form-cloud.component.ts")
|
|
|
|
Shows a [`form`](../../../lib/process-services-cloud/src/lib/form/models/form-cloud.model.ts) from Process Services.
|
|
|
|
## Contents
|
|
|
|
- [Basic Usage](#basic-usage)
|
|
- [Custom form outcomes template](#custom-form-outcomes-template)
|
|
- [Empty form template](#empty-form-template)
|
|
- [Class members](#class-members)
|
|
- [Properties](#properties)
|
|
- [Events](#events)
|
|
- [Details](#details)
|
|
- [Displaying a form](#displaying-a-form)
|
|
- [Controlling outcome execution behaviour](#controlling-outcome-execution-behaviour)
|
|
- [Field Validators](#field-validators)
|
|
- [Common scenarios](#common-scenarios)
|
|
- [See also](#see-also)
|
|
|
|
## Basic Usage
|
|
|
|
```html
|
|
<adf-cloud-form
|
|
[appName]="appName"
|
|
[taskId]="taskId"
|
|
[processInstanceId]="processInstanceId">
|
|
</adf-cloud-form>
|
|
```
|
|
|
|
### Custom form outcomes template
|
|
|
|
You can set the custom form outcomes using an `<adf-cloud-form-custom-outcomes>` element.
|
|
|
|
```html
|
|
<adf-cloud-form .... >
|
|
|
|
<adf-cloud-form-custom-outcomes>
|
|
<button mat-button (click)="onCustomOutcome1()">
|
|
Custom-outcome-1
|
|
</button>
|
|
<button mat-button (click)="onCustomOutcome2()">
|
|
Custom-outcome-2
|
|
</button>
|
|
<button mat-button (click)="onCustomOutcome3()">
|
|
Custom-outcome-3
|
|
</button>
|
|
</adf-cloud-form-custom-outcomes>
|
|
|
|
</adf-cloud-form>
|
|
```
|
|
|
|
### Empty form template
|
|
|
|
The template defined inside `empty-form` will be shown when no form definition is found:
|
|
|
|
```html
|
|
<adf-cloud-form .... >
|
|
|
|
<div empty-form >
|
|
<h2>Empty form</h2>
|
|
</div>
|
|
|
|
</adf-cloud-form>
|
|
```
|
|
|
|
## Class members
|
|
|
|
### Properties
|
|
|
|
| Name | Type | Default value | Description |
|
|
| ---- | ---- | ------------- | ----------- |
|
|
| appName | `string` | "" | App name to fetch corresponding form and values. |
|
|
| appVersion | `number` | | The application version to use when fetching data |
|
|
| data | [`TaskVariableCloud`](../../../lib/process-services-cloud/src/lib/form/models/task-variable-cloud.model.ts)`[]` | | Custom form values map to be used with the rendered form. |
|
|
| disableCompleteButton | `boolean` | false | If true then the `Complete` outcome button is shown but it will be disabled. |
|
|
| disableSaveButton | `boolean` | false | If true then the `Save` outcome button is shown but will be disabled. |
|
|
| disableStartProcessButton | `boolean` | false | If true then the `Start Process` outcome button is shown but it will be disabled. |
|
|
| fieldValidators | [`FormFieldValidator`](../../../lib/core/src/lib/form/components/widgets/core/form-field-validator.ts)`[]` | | [FormFieldValidator](../../../lib/core/src/lib/form/components/widgets/core/form-field-validator.ts) allow to override the form field validators provided. |
|
|
| form | [`FormModel`](../../../lib/core/src/lib/form/components/widgets/core/form.model.ts) | | Underlying form model instance. |
|
|
| formId | `string` | | Task id to fetch corresponding form and values. |
|
|
| isNextTaskCheckboxChecked | `boolean` | false | Whether the `Open next task` checkbox is checked by default or not. |
|
|
| nameNode | `string` | | Name to assign to the new node where the metadata are stored. |
|
|
| path | `string` | | Path of the folder where the metadata will be stored. |
|
|
| processInstanceId | `string` | | ProcessInstanceId id to fetch corresponding form and values. |
|
|
| readOnly | `boolean` | false | Toggle readonly state of the form. Forces all form widgets to render as readonly if enabled. |
|
|
| showCompleteButton | `boolean` | true | Toggle rendering of the `Complete` outcome button. |
|
|
| showNextTaskCheckbox | `boolean` | false | Toggle rendering of the `Open next task` checkbox. |
|
|
| showRefreshButton | `boolean` | true | Toggle rendering of the `Refresh` button. |
|
|
| showSaveButton | `boolean` | true | Toggle rendering of the `Save` outcome button. |
|
|
| showTitle | `boolean` | true | Toggle rendering of the form title. |
|
|
| showValidationIcon | `boolean` | true | Toggle rendering of the validation icon next to the form title. |
|
|
| taskId | `string` | | Task id to fetch corresponding form and values. |
|
|
| displayModeConfigurations | [`FormCloudDisplayModeConfiguration`](../../../lib/process-services-cloud/src/lib/services/form-fields.interfaces.ts)`[]` | | The available display configurations for the form |
|
|
|
|
### Events
|
|
|
|
| Name | Type | Description |
|
|
| ---- | ---- | ----------- |
|
|
| error | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<any>` | Emitted when any error occurs. |
|
|
| executeOutcome | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`FormOutcomeEvent`](../../../lib/core/src/lib/form/components/widgets/core/form-outcome-event.model.ts)`>` | Emitted when any outcome is executed. Default behaviour can be prevented via `event.preventDefault()`. |
|
|
| formCompleted | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`FormModel`](../../../lib/core/src/lib/form/components/widgets/core/form.model.ts)`>` | Emitted when the form is submitted with the `Complete` outcome. |
|
|
| formContentClicked | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`ContentLinkModel`](../../../lib/core/src/lib/form/components/widgets/core/content-link.model.ts)`>` | Emitted when form content is clicked. |
|
|
| formDataRefreshed | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`FormModel`](../../../lib/core/src/lib/form/components/widgets/core/form.model.ts)`>` | Emitted when form values are refreshed due to a data property change. |
|
|
| formError | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`FormFieldModel`](../../core/models/form-field.model.md)`[]>` | Emitted when the supplied form values have a validation error. |
|
|
| formLoaded | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`FormModel`](../../../lib/core/src/lib/form/components/widgets/core/form.model.ts)`>` | Emitted when the form is loaded or reloaded. |
|
|
| formSaved | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`FormModel`](../../../lib/core/src/lib/form/components/widgets/core/form.model.ts)`>` | Emitted when the form is submitted with the `Save` or custom outcomes. |
|
|
| displayModeOn | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`FormCloudDisplayModeConfiguration`](../../../lib/process-services-cloud/src/lib/services/form-fields.interfaces.ts)`>` | Emitted when a display mode configuration is turned on. |
|
|
| displayModeOff | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`FormCloudDisplayModeConfiguration`](../../../lib/process-services-cloud/src/lib/services/form-fields.interfaces.ts)`>` | Emitted when a display mode configuration is turned off. |
|
|
| nextTaskCheckboxCheckedChanged | [`EventEmitter`](https://angular.io/api/core/EventEmitter)`<`[`MatCheckboxChange`](https://material.angular.io/components/checkbox/api#MatCheckboxChange)`>` | Emitted when the `Open next task` checkbox was toggled. |
|
|
|
|
## Details
|
|
|
|
All `formXXX` events receive a [`FormCloudModel`](../../../lib/process-services-cloud/src/lib/form/models/form-cloud.model.ts) instance as their argument:
|
|
|
|
**MyView.component.html**
|
|
|
|
```html
|
|
<adf-cloud-form
|
|
[appName]="appName"
|
|
[taskId]="selectedTask?.id"
|
|
[processInstanceId]="selectedTask?.processInstanceId"
|
|
(formSaved)="onFormSaved($event)">
|
|
</adf-cloud-form>
|
|
```
|
|
|
|
**MyView.component.ts**
|
|
|
|
```ts
|
|
onFormSaved(form: FormCloudModel) {
|
|
console.log(form);
|
|
}
|
|
```
|
|
|
|
### Displaying a form
|
|
|
|
There are various ways to display a form. The common scenarios are detailed below.
|
|
|
|
#### Displaying a form instance by task id and processInstanceId
|
|
|
|
```html
|
|
<adf-cloud-form
|
|
[appName]="appName"
|
|
[taskId]="selectedTask?.id"
|
|
[processInstanceId]="selectedTask?.processInstanceId">
|
|
</adf-cloud-form>
|
|
```
|
|
|
|
For an existing Task both the form and its values will be fetched and displayed.
|
|
|
|
#### Displaying a form definition by form id
|
|
|
|
```html
|
|
<adf-cloud-form
|
|
[appName]="appName"
|
|
[formId]="selectedFormDefinition?.id"
|
|
[data]="customData">
|
|
</adf-cloud-form>
|
|
```
|
|
|
|
In this case, only the form definition will be fetched.
|
|
|
|
#### Enabling fullscreen display for the form
|
|
|
|
Provide a `displayModeConfiguration` array object containing the fullscreen configuration. You can use the configuration provided in the [`DisplayModeService`](../../../lib/process-services-cloud/src/lib/form/services/display-mode.service.ts) as a static member `DisplayModeService.IMPLEMENTED_DISPLAY_MODE_CONFIGURATIONS`, or configure your own if you want to customise the options for the fullscreen display mode.
|
|
|
|
**MyView.component.html**
|
|
|
|
```html
|
|
<button (click)="adfCloudForm.switchToDisplayMode('fullScreen')">Full screen</button>
|
|
|
|
<adf-cloud-form #adfCloudForm
|
|
[appName]="appName"
|
|
[taskId]="selectedTask?.id"
|
|
[showTitle]="false"
|
|
[showRefreshButton]="false"
|
|
[showValidationIcon]="false"
|
|
[displayModeConfigurations]="displayConfigurations">
|
|
</adf-cloud-form>
|
|
```
|
|
|
|
**MyView.component.ts**
|
|
|
|
```ts
|
|
import { DisplayModeService } from '@alfresco/adf-process-services-cloud';
|
|
|
|
export class MyView {
|
|
|
|
get displayConfigurations() {
|
|
return DisplayModeService.IMPLEMENTED_DISPLAY_MODE_CONFIGURATIONS;
|
|
}
|
|
|
|
}
|
|
```
|
|
|
|
When the `displayModeConfigurations` contains the configuration for the fullscreen display, in the header of the form, a button to switch to fullscreen is displayed. Keep in mind that the header of the form is visible only if any of the parameters `showTitle`, `showRefreshButton`or `showValidationIcon` is `true`, but it is also possible to switch to the fullscreen display using a button that you can place wherever you want as shown in the previous example.
|
|
|
|
### Controlling outcome execution behaviour
|
|
|
|
In unusual circumstances, you may need to take complete control of form outcome execution.
|
|
You can do this by implementing the `executeOutcome` event, which is emitted for both system
|
|
outcomes and custom ones.
|
|
|
|
Note that by default, the code in your `executeOutcome` handler is executed _before_ the default
|
|
behavior but you can switch the default behavior off using `event.preventDefault()`.
|
|
You might want to do this, for example, to provide custom form validation or to show a summary
|
|
of the form validation before it is submitted.
|
|
|
|
**MyView.component.html**
|
|
|
|
```html
|
|
<adf-cloud-form
|
|
[appName]="appName"
|
|
[taskId]="selectedTask?.id"
|
|
[processInstanceId]="selectedTask?.processInstanceId"
|
|
executeOutcome="validateForm($event)">
|
|
</adf-cloud-form>
|
|
```
|
|
|
|
**MyView.component.ts**
|
|
|
|
```ts
|
|
import { FormOutcomeEvent } from '@alfresco/adf-core';
|
|
|
|
export class MyView {
|
|
|
|
validateForm(event: FormOutcomeEvent) {
|
|
let outcome = event.outcome;
|
|
|
|
// you can also get additional properties of outcomes
|
|
// if you defined them within outcome definition
|
|
|
|
if (outcome) {
|
|
let form = outcome.form;
|
|
if (form) {
|
|
// check/update the form here
|
|
event.preventDefault();
|
|
}
|
|
}
|
|
}
|
|
|
|
}
|
|
```
|
|
|
|
There are two other functions that can be very useful when you need to control form outcomes:
|
|
|
|
- `saveTaskForm()` - Saves the current form
|
|
- `completeTaskForm(outcome?: string)` Saves and completes the form with a given outcome name
|
|
|
|
### Field Validators
|
|
|
|
You can supply a set of validator objects to the form using the `fieldValidators` property. To do this you must use Token `FORM_CLOUD_FIELD_VALIDATORS_TOKEN`. This is a A DI token that allows to inject additional form field validators. Each validator implements a check for a particular type of data (eg, a date validator might check that the date in the field falls between 1980 and 2017).
|
|
ADF supplies a standard set of validators that handle most common cases but you can
|
|
also implement your own custom validators to replace or extend the set. See the
|
|
[Form Field Validator](../../core/interfaces/form-field-validator.interface.md) interface for full details and examples.
|
|
|
|
```ts
|
|
import { NgModule } from '@angular/core';
|
|
import { FORM_SERVICE_FIELD_VALIDATORS_TOKEN } from '@alfresco/adf-core';
|
|
|
|
@NgModule({
|
|
imports: [
|
|
...Import Required Modules
|
|
],
|
|
providers: [
|
|
{
|
|
provide: FORM_SERVICE_FIELD_VALIDATORS_TOKEN,
|
|
useValue: [new AdditionalFormFieldValidator()]
|
|
}
|
|
]
|
|
})
|
|
export class ExampleModule {}
|
|
```
|
|
|
|
### Common scenarios
|
|
|
|
#### Rendering a form using form definition JSON
|
|
|
|
See the [demo-form](../../docassets/demo-cloud.form.json) file for an example of form definition JSON.
|
|
|
|
The component below (with the JSON assigned to the `formDefinitionJSON` property), shows how a
|
|
form definition is rendered:
|
|
|
|
```ts
|
|
@Component({
|
|
selector: 'sample-form',
|
|
template: `<div class="form-container">
|
|
<adf-cloud-form
|
|
[form]="form">
|
|
</adf-cloud-form>
|
|
</div>`
|
|
})
|
|
export class SampleFormComponent implements OnInit {
|
|
|
|
form: FormCloudModel;
|
|
formDefinitionJSON: any;
|
|
|
|
constructor(private formService: FormService) {
|
|
}
|
|
|
|
ngOnInit() {
|
|
this.form = this.formService.parseForm(this.formDefinitionJSON);
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Customizing the styles of form outcome buttons
|
|
|
|
You can use normal CSS selectors to style the outcome buttons of your form.
|
|
Every outcome has an CSS id value following a simple pattern:
|
|
|
|
adf-cloud-form-OUTCOME_NAME
|
|
|
|
In the CSS, you can target any outcome ID and change the style as in this example:
|
|
|
|
```css
|
|
#adf-cloud-form-complete {
|
|
background-color: blue !important;
|
|
color: white;
|
|
}
|
|
|
|
|
|
#adf-cloud-form-save {
|
|
background-color: green !important;
|
|
color: white;
|
|
}
|
|
|
|
#adf-cloud-form-customoutcome {
|
|
background-color: yellow !important;
|
|
color: white;
|
|
}
|
|
```
|
|
|
|
|
|
|
|
## See also
|
|
|
|
- [Form Field Validator interface](../../core/interfaces/form-field-validator.interface.md)
|
|
- [Extensibility](../../user-guide/extensibility.md)
|
|
- [Form rendering service](../../core/services/form-rendering.service.md)
|
|
- [Form field model](../../core/models/form-field.model.md)
|
|
- [Form cloud service](../services/form-cloud.service.md)
|