inteligr8/alfresco-ng2-components
1
0
Fork 0
mirror of https://github.com/Alfresco/alfresco-ng2-components.git synced 2025-07-24 17:32:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

[ADF-2463] Moved doc files to subfolders (#3073)

Browse Source
This commit is contained in:
Andy Stark
2018-03-13 17:29:07 +00:00
committed by Eugenio Romano
parent 766bb082f5
commit 6dc758889f
34 changed files with 103 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/core/accordion.component.md
View File

@@ -44,7 +44,7 @@ properties (title, selection status, etc).
### Example
You can use an accordion menu to wrap a [process filter](../process-filters.component.md), as shown in
You can use an accordion menu to wrap a [process filter](../process-services/process-filters.component.md), as shown in
the following example:
```html

153
docs/core/form-field-validator.interface.md Normal file
View File

@@ -0,0 +1,153 @@
---
Added: v2.0.0
Status: Active
---
# FormFieldValidator interface
Defines how the input fields of Form and Task Details components are validated.
## Basic Usage
```html
<adf-form [fieldValidators]="fieldValidators"></adf-form>
```
```ts
import { FORM_FIELD_VALIDATORS } from '@alfresco/adf-core';
@Component({...})
export class AppComponent {
fieldValidators = [
// default set of ADF validators if needed
...FORM_FIELD_VALIDATORS,
// custom validator
new MyValidator()
];
}
export class MyValidator implements FormFieldValidator {
isSupported(field: FormFieldModel): boolean {
// Check if this validation can be used with 'field'.
}
validate(field: FormFieldModel): boolean {
// Perform the validation.
}
}
```
### Methods
`isSupported(field: FormFieldModel): boolean;`
Does this validator support the type of data used in `field`?
`validate(field: FormFieldModel): boolean;`
Perform validation on `field`.
## Details
You can supply a set of validator objects for a form using its `fieldValidators` property.
ADF will determine if a validator should be used with a given field by calling its
`isSupported` method, passing the field's FormFieldModel as a parameter. If the validator
does support the field then its `validate` method will be called on the FormFieldModel
during the validation phase.
Several validator classes are predefined for you to use:
| Validator name | Checks that: |
| -------------- | ------------ |
| `RequiredFieldValidator` | Field is not left blank |
| `NumberFieldValidator` | Field contains numeric data |
| `MinLengthFieldValidator` | Field text has at least a minimum number of characters |
| `MaxLengthFieldValidator` | Field text has no more than a maximum number of characters |
| `MinValueFieldValidator` | Numeric field's value is greater than a lower limit |
| `MaxValueFieldValidator` | Numeric field's vaue is less than an upper limit |
| `RegExFieldValidator` | Field text matches a regular expression |
| `DateFieldValidator` | Field contains a date in the correct format |
| `MinDateFieldValidator` | Date within a field occurs after a certain starting point |
| `MaxDateFieldValidator` | Date within a field occurs before a certain end point |
The `FORM_FIELD_VALIDATORS` array contains an instance of each of these classes. You can assign this to the `fieldValidators` property of an Activiti Form or Activiti Task Details component to enable standard validation.
### Custom validators
You can implement your own custom validator classes if the standard set doesn't provide the
features you need. For example, you could check for consistency between separate fields on
the form (currency values adding up to a given total, say).
The `type` property of `FormFieldModel` is often used in the `isSupported` function, since
validation methods typically apply only to specific types of data.
The [FormFieldTypes](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form-field-types.ts)
class defines convenient constants for the type strings.
The validator in the example
below simply checks that "admin" is not entered into a text field:
```ts
import { FormFieldModel, FormFieldTypes, FormFieldValidator } from '@alfresco/adf-core';
export class DemoFieldValidator implements FormFieldValidator {
isSupported(field: FormFieldModel): boolean {
return field && field.type === FormFieldTypes.TEXT;
}
validate(field: FormFieldModel): boolean {
if (this.isSupported(field)) {
if (field.value && field.value.toLowerCase() === 'admin') {
field.validationSummary = 'Sorry, the value cannot be "admin".';
return false;
}
}
return true;
}
}
```
You will usually want to extend the existing `FORM_FIELD_VALIDATORS` set rather than replace
it entirely (although you can do this if necessary):
```ts
import { DemoFieldValidator } from './demo-field-validator';
@Component({...})
export class AppComponent {
fieldValidators = [
...FORM_FIELD_VALIDATORS,
new DemoFieldValidator()
];
}
```
You can now use the 'fieldValidators' property of the Form or Task Details components to assign your
custom validator set:
```html
<activiti-task-details
[fieldValidators]="fieldValidators"
taskId="123">
</<activiti-task-details>
<!-- OR -->
<adf-form
[fieldValidators]="fieldValidators"
taskI="123">
</adf-form>
```
If you now run the application and try to enter "admin" in one of the text fields (either optional or required), you should see the following error:
![](../docassets/images/demo-validator.png)
## See also
- [Form field model](form-field.model.md)
- [Form component](form.component.md)

57
docs/core/form-field.component.md Normal file
View File

@@ -0,0 +1,57 @@
---
Added: v2.0.0
Status: Active
---
# Form field component
A form field in an APS form.
## Basic Usage
All form field editors (aka widgets) on a Form are rendered by means of a `FormFieldComponent`
that takes an instance of a `FormFieldModel`:
```html
<adf-form-field [field]="field"></adf-form-field>
```
This component depends on the `FormRenderingService` to map the `FormFieldModel` to a Form Field UI component
based on the field type or the metadata information.
### Properties
| Name | Type | Default value | Description |
| ---- | ---- | ------------- | ----------- |
| field | `FormFieldModel` | `null` | Contains all the necessary data needed to determine what UI Widget to use when rendering the field in the form. You would typically not create this data manually but instead create the form in APS and export it to get to all the `FormFieldModel` definitions. |
## Details
You would typically not use this component directly but instead use the `<adf-form>` component, which under the hood
uses `<adf-form-field>` components to render the form fields. See next section for how each field in a form definition
is mapped to a form field component (i.e. UI widget) implementation.
### Field Type -> Form Field Component mappings
Forms defined in APS have the following default mappings for the form fields:
| APS Form Designer Widget | Field Type | Component Type |
| ------------------------ | ---------- | -------------- |
| Text | text | TextWidgetComponent |
| Multi-line text | multi-line-text | MultilineTextWidgetComponentComponent |
| Number | integer | NumberWidgetComponent |
| Checkbox | boolean | CheckboxWidgetComponent |
| Date | date | DateWidgetComponent |
| Dropdown | dropdown | DropdownWidgetComponent |
| Typeahead | typeahead | TypeaheadWidgetComponent |
| Amount | amount | AmountWidgetComponent |
| Radio buttons | radio-buttons | RadioButtonsWidgetComponent |
| People | people | PeopleWidgetComponent |
| Group of people | functional-group | FunctionalGroupWidgetComponent |
| Dynamic table | dynamic-table | DynamicTableWidgetComponent |
| Hyperlink | hyperlink | HyperlinkWidgetComponent |
| Header | group | ContainerWidgetComponent |
| Attach File | upload | AttachWidgetComponent or UploadWidgetComponent (based on metadata) |
| Display value | readonly | DisplayValueWidgetComponent |
| Display text | readonly-text | DisplayTextWidgetComponentComponent |
| N/A | container | ContainerWidgetComponent (layout component) |
| N/A | N/A | UnknownWidgetComponent |

99
docs/core/form-field.model.md Normal file
View File

@@ -0,0 +1,99 @@
---
Added: v2.0.0
Status: Active
---
# Form Field model
Contains the value and metadata for a field of a Form component.
## Properties
| Name | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| id | string | | Field ID |
| name | string | | Field name |
| type | string | | Field type (see [Form Rendering service](form-rendering.service.md) for a list of available type strings) |
| value | any | | Field value (implemented by get/set) |
| readOnly | boolean | | Is this a read-only field? (Implemented by get/set) |
| required | boolean | | Is the field required to have a value? (Implemented by get/set) |
| isValid | boolean | | Does the field pass its validation checks? (Implemented by get/set) |
| overrideId | boolean | | Should the auto-generated ID (from `name`) be overridden to let the user set a custom ID? |
| tab | string | | Name of the current form tab |
| rowspan | number | 1 | The number of container rows that the field spans |
| colspan | number | 1 | The number of container columns that the field spans |
| placeholder | string | null | Placeholder text shown before the field is edited |
| minLength | number | 0 | Minimum allowed number of characters in input data |
| maxLength | number | 0 | Maximum allowed number of characters in input data |
| minValue | string | | Minimum allowed value (eg, for number or date) |
| maxValue | string | | Minimum allowed value (eg, for number or date) |
| regexPattern | string | | Regular expression that text data should match |
| options | FormFieldOption\[] | \[] | Option items for a dropdown menu |
| restUrl | string | | URL for a REST call to populate a dropdown menu |
| restResponsePath | string | | Path within REST response JSON to the array of dropdown data |
| restIdProperty | string | | JSON property name to use for the `id` property of a dropdown item |
| restLabelProperty | string | | JSON property name to use for the `label` property of a dropdown item |
| hasEmptyValue | boolean | | Is the field's value empty? (eg, dropdown with no item selected) |
| className | string | | CSS class name for the field |
| optionType | string | | |
| params | FormFieldMetadata | {} | |
| hyperlinkUrl | string | | URL for Hyperlink widgets |
| displayText | string | | Displayed text for Hyperlink widgets |
| isVisible | boolean | true | Is the field shown on the form? |
| visibilityCondition | WidgetVisibilityModel | null | Defines a expression that determines whether the field is visible or not, based on its logical relation to values in other fields |
| enableFractions | boolean | false | Are numeric values allowed to contain a decimal point? |
| currency | string | null | Currency symbol for Amount widgets |
| dateDisplayFormat | string | | Date/time display format template |
| numberOfColumns | number | 1 | Number of columns defined by a container field |
| fields | FormFieldModel\[] | \[] | Fields contained within a container field |
| columns | ContainerColumnModel\[] | \[] | Column definitions for a container field |
| emptyOption | FormFieldOption | | Dropdown menu item to use when no option is chosen |
| validationSummary | string | | Error/information message added during field validation (see [FormFieldValidator](form-field-validator.interface.md) interface) |
## Details
Every field of a form has an associated `FormFieldModel` instance that contains the
field's value and metadata. The standard widgets use this information to render fields and you can also make use of it in your own custom widgets and field validators.
### Custom widgets
You will need to use the properties of `FormFieldModel` if you want to implement your own
custom widgets. Aside from the `value` property (which contains the data value entered into
the field), there are also a few other fields that are used for specific types of data. For
example, the `currency` property holds the currency symbol to be displayed next to the value
(such as the dollar sign $) and the `dateDisplayFormat` defines how the elements of a date/time will be arranged. See the [Form Extensibility and Customization](../extensibility.md) for more information about creating custom widgets.
### Validation
A [Form](form.component.md) or [Task Details](../task-details.component.md) component can
be supplied with a set of validator objects. Each validator applies a particular kind of
check to a field. A number of `FormFieldModel` properties are used by validators. For
example, `minValue` and `maxValue` are used to check that a numeric value falls within an
allowed range and `regexPattern` defines a regular expression that a text field should
match. Also, the `validationSummary` is used to send a message back from the validator
for the user to read. See the [FormFieldValidator](form-field-validator.interface.md) page for more information about implementing validators.
### REST properties
You can set the items shown on a dropdown menu using data returned by a REST call. The
properties used by the call are:
- `restUrl`: The URL for the REST service
- `restResponsePath`: Optional path to an array within the JSON object returned by
the REST call. Each element in the array corresponds to an item on the dropdown.
- `restIdProperty`: The name of a JSON property present in each element of the array
selected by `restResponsePath`. Its value will be used for the `id` property of the
dropdown item.
`restLabelProperty`: The name of a JSON property present in each element of the array
selected by `restResponsePath`. Its value will be used for the `label` property of the
dropdown item (ie, the text visible to the user).
The [REST Call Task 101](https://community.alfresco.com/community/bpm/blog/2016/08/31/rest-integration-101)
tutorial on the [APS community site](https://community.alfresco.com/community/bpm)
contains full details about how the REST calls work, along with a worked example.
## See also
- [Extensibility](../extensibility.md)
- [FormFieldValidator](form-field-validator.interface.md)
- [Form rendering service](form-rendering.service.md)
- [Form component](form.component.md)

21
docs/core/form-list.component.md Normal file
View File

@@ -0,0 +1,21 @@
---
Added: v2.0.0
Status: Active
---
# Form List Component
Shows APS forms as a list.
## Basic Usage
```html
<adf-form-list
[forms]="[{ name: 'My Name', lastUpdatedByFullName: 'My User Name', lastUpdated: '2017-06-01'}]">
</adf-form-list>
```
### Properties
| Name | Type | Default value | Description |
| ---- | ---- | ------------- | ----------- |
| forms | `any[]` | `[]` | The array that contains the information to show inside the list. |

100
docs/core/form-rendering.service.md Normal file
View File

@@ -0,0 +1,100 @@
---
Added: v2.0.0
Status: Active
---
# Form Rendering service
Maps an APS form field type string onto the corresponding form widget component type.
## 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.
## Details
The Form Field component uses this service to choose which widget to use to render an instance of a
form field. The Form Field model stores the field type name as a string (see the table below).
The Form Rendering service maintains a mapping between each type name and
a corresponding ComponentTypeResolver function. The function takes a FormFieldModel object as its argument and
uses the data from the object to determine which widget should be used to render the field.
In some cases, the field type string alone is enough to determine the widget type and so the function
just returns the type directly:
```ts
let customResolver: ComponentTypeResolver = () => CustomWidgetComponent;
formRenderingService.setComponentTypeResolver('text', customResolver, true);
```
In other cases, the function may need to choose the widget dynamically based on
specific values in the form data:
```ts
let customResolver: ComponentTypeResolver = (field: FormFieldModel): Type<{}> => {
if (field) {
let params = field.params;
}
return UnknownWidgetComponent;
};
formRenderingService.setComponentTypeResolver('text', customResolver, true);
```
### Default type mapping
The Form Rendering service is initialized with the mapping shown in the table below:
| Stencil name | Field type string | Component type |
| ------------ | ----------------- | -------------- |
| Amount | "amount" | AmountWidgetComponent |
| Attach | "upload" | AttachWidgetComponent or UploadWidgetComponent (based on metadata) |
| Checkbox | "boolean" | CheckboxWidgetComponent |
| Date | "date" | DateWidgetComponent |
| Display text | "readonly-text" | DisplayTextWidgetComponentComponent |
| Display value | "readonly" | DisplayValueWidgetComponent |
| Dropdown | "dropdown" | DropdownWidgetComponent |
| Dynamic table | "dynamic-table" | DynamicTableWidgetComponent |
| Group of people | "functional-group" | FunctionalGroupWidgetComponent |
| Header | "group" | ContainerWidgetComponent |
| Hyperlink | "hyperlink" | HyperlinkWidgetComponent |
| Multi-line text | "multi-line-text" | MultilineTextWidgetComponentComponent |
| Number | "integer" | NumberWidgetComponent |
| People | "people" | PeopleWidgetComponent |
| Radio buttons | "radio-buttons" | RadioButtonsWidgetComponent |
| Text | "text" | TextWidgetComponent |
| Typeahead | "typeahead" | TypeaheadWidgetComponent |
You can add new items to the mapping or replace existing items in order to customize the way
fields are rendered.
### Adding new or replacement items to the mapping
You can use the `setComponentTypeResolver` method to add a new ComponentTypeResolver function for a
particular type string. You can also replace the resolver for a type that already exists in the mapping
if you set the `override` parameter to 'true':
```ts
formRenderingService.setComponentTypeResolver('text', newResolver, true);
```
You would typically use this to replace an existing widget with your own custom version that
implements a modified layout or responds differently when the data is entered. See the
[Form Extensibility and Customisation](../extensibility.md) guide for further details and examples
of this technique.
## See also
- [Extensibility](../extensibility.md)
- [Form field model](form-field.model.md)
- [Form component](form.component.md)

343
docs/core/form.component.md Normal file
View File

@@ -0,0 +1,343 @@
---
Added: v2.0.0
Status: Active
---
# Form component
Shows a Form from APS (see it live: [Form Quickstart](https://embed.plnkr.co/YSLXTqb3DtMhVJSqXKkE/))
## Contents
- [Basic Usage](#basic-usage)
- [Properties](#properties)
- [Events](#events)
- [Details](#details)
- [Custom empty form template](#custom-empty-form-template)
- [Controlling outcome execution behaviour](#controlling-outcome-execution-behaviour)
- [Field Validators](#field-validators)
- [Other documentation](#other-documentation)
- [Common scenarios](#common-scenarios)
- [See also](#see-also)
## Basic Usage
```html
<adf-form
[taskId]="taskId">
</adf-form>
```
**Display form instance by task id:**
```html
<adf-form
[taskId]="selectedTask?.id">
</adf-form>
```
For an existing Task both form and values will be fetched and displayed.
**Display form definition by form id:**
```html
<adf-form
[formId]="selectedFormDefinition?.id"
[data]="customData">
</adf-form>
```
Only form definition will be fetched.
**Display form definition by form name:**
```html
<adf-form
[formName]="selectedFormDefinition?.name"
[data]="customData">
</adf-form>
```
**Display form definition by ECM nodeId:**
In this case the metadata of the node are showed in an activiti Form.
If there is no form definied in activiti for the type of the node,
a new form will be automaticaly created in Activiti.
```html
<adf-form
[nodeId]="'e280be3a-6584-45a1-8bb5-89bfe070262e'">
</adf-form>
```
**Display form definition by form name, and store the form field as metadata:**
The param nameNode is optional.
```html
<adf-form
[formName]="'activitiForms:patientFolder'"
[saveMetadata]="true"
[path]="'/Sites/swsdp/documentLibrary'"
[nameNode]="'test'">
</adf-form>
```
**Display form definition by ECM nodeId:**
In this case the metadata of the node are shown in an activiti Form,
and store the form field as metadata. The param nameNode is optional.
```html
<adf-form
[nodeId]="'e280be3a-6584-45a1-8bb5-89bfe070262e'"
[saveMetadata]="true"
[path]="'/Sites/swsdp/documentLibrary'"
[nameNode]="'test'">
</adf-form>
```
### Properties
| Name | Type | Default value | Description |
| ---- | ---- | ------------- | ----------- |
| form | `FormModel` | | Underlying form model instance. |
| taskId | `string` | | Task id to fetch corresponding form and values. |
| nodeId | `string` | | Content Services node ID for the form metadata. |
| formId | `string` | | The id of the form definition to load and display with custom values. |
| formName | `string` | | Name of the form definition to load and display with custom values. |
| saveMetadata | `boolean` | `false` | Toggle saving of form metadata. |
| data | `FormValues` | | Custom form values map to be used with the rendered form. |
| path | `string` | | Path of the folder where the metadata will be stored. |
| nameNode | `string` | | Name to assign to the new node where the metadata are stored. |
| showTitle | `boolean` | `true` | Toggle rendering of the form title. |
| showCompleteButton | `boolean` | `true` | Toggle rendering of the `Complete` outcome button. |
| disableCompleteButton | `boolean` | `false` | If true then the `Complete` outcome button is shown but it will be disabled. |
| disableStartProcessButton | `boolean` | `false` | If true then the `Start Process` outcome button is shown but it will be disabled. |
| showSaveButton | `boolean` | `true` | Toggle rendering of the `Save` outcome button. |
| showDebugButton | `boolean` | `false` | Toggle debug options. |
| readOnly | `boolean` | `false` | Toggle readonly state of the form. Forces all form widgets to render as readonly if enabled. |
| showRefreshButton | `boolean` | `true` | Toggle rendering of the `Refresh` button. |
| showValidationIcon | `boolean` | `true` | Toggle rendering of the validation icon next to the form title. |
| fieldValidators | `FormFieldValidator[]` | `[]` | Contains a list of form field validator instances. |
### Events
| Name | Type | Description |
| ---- | ---- | ----------- |
| formSaved | `EventEmitter<FormModel>` | Emitted when the form is submitted with the `Save` or custom outcomes. |
| formCompleted | `EventEmitter<FormModel>` | Emitted when the form is submitted with the `Complete` outcome. |
| formContentClicked | `EventEmitter<ContentLinkModel>` | Emitted when form content is clicked. |
| formLoaded | `EventEmitter<FormModel>` | Emitted when the form is loaded or reloaded. |
| formDataRefreshed | `EventEmitter<FormModel>` | Emitted when form values are refreshed due to a data property change. |
| executeOutcome | `EventEmitter<FormOutcomeEvent>` | Emitted when any outcome is executed. Default behaviour can be prevented via `event.preventDefault()`. |
| onError | `EventEmitter<any>` | Emitted when any error occurs. |
## Details
All `form*` events receive an instance of the `FormModel` as event argument for ease of development:
**MyView.component.html**
```html
<adf-form
[taskId]="selectedTask?.id"
(formSaved)="onFormSaved($event)">
</adf-form>
```
**MyView.component.ts**
```ts
onFormSaved(form: FormModel) {
console.log(form);
}
```
### Custom empty form template
You can add a template that will be show if no form definition has been found
```html
<adf-form .... >
<div empty-form >
<h2>Empty form</h2>
</div>
</adf-form>
```
### Controlling outcome execution behaviour
If absolutely needed it is possible taking full control over form outcome execution by means of `executeOutcome` event.
This event is fired upon each outcome execution, both system and custom ones.
You can prevent default behaviour by calling `event.preventDefault()`.
This allows for example having custom form validation scenarios and/or additional validation summary presentation.
Alternatively you may want just running additional code on outcome execution without suppressing default one.
**MyView.component.html**
```html
<adf-form
[taskId]="selectedTask?.id"
executeOutcome="validateForm($event)">
</adf-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 additional functions that can be of a great value when controlling outcomes:
- `saveTaskForm()` - saves current form
- `completeTaskForm(outcome?: string)` - save and complete form with a given outcome name
**Please note that if `event.preventDefault()` is not called then default outcome behaviour
will also be executed after your custom code.**
### Field Validators
You can supply a set of validator objects to the form using the `fieldValidators`
property. Each validator implements checks 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
[FormFieldValidator](form-field-validator.interface.md) class for full details and examples.
## Other documentation
### Common scenarios
#### Render form by using form definition JSON
Please give a look to the [demo-form](../docassets/demo-form.json) as a sample of form definition JSON.
The component below with the form definition JSON assigned to the variable `formDefinitionJSON`, shows how a form is rendered by using form definition JSON.
```ts
@Component({
selector: 'sample-form',
template: `<div class="form-container">
<adf-form
[form]="form">
</adf-form>
</div>`
})
export class SampleFormComponent implements OnInit {
form: FormModel;
formDefinitionJSON: any;
constructor(private formService: FormService) {
}
ngOnInit() {
this.form = this.formService.parseForm(this.formDefinitionJSON);
}
}
```
#### Changing field value based on another field
Create a simple Form with a dropdown widget (id: `type`), and a multiline text (id: `description`).
```ts
formService.formFieldValueChanged.subscribe((e: FormFieldEvent) => {
if (e.field.id === 'type') {
const fields: FormFieldModel[] = e.form.getFormFields();
const description = fields.find(f => f.id === 'description');
if (description != null) {
console.log(description);
description.value = 'Type set to ' + e.field.value;
}
}
});
```
You subscribe to the `formFieldValueChanged` event and check whether event is raised for the `type` widget, then you search for a `description` widget and assign its value to some simple text.
The result should be as following:
![](../docassets/images/form-service-sample-01.png)
#### Listen all form Events
If you want to listen all the events fired in the form you can subscribe to this Subject :
```ts
formService.formEvents.subscribe((event: Event) => {
console.log('Event fired:' + event.type);
console.log('Event Target:' + event.target);
});
```
#### Customize form outcomes (buttons) styles
If you want custtomize the outcoumes style of your form you can do it using plain css selectors.
Any outcome has an Id that is composed in the following way:
```
adf-form-YOUR_OUTCAME_NAME
```
Using the CSS you can target any outcome ID and change the style as in this example:
```css
#adf-form-complete {
background-color: blue !important;
color: white;
}
#adf-form-save {
background-color: green !important;
color: white;
}
#adf-form-customoutcome {
background-color: yellow !important;
color: white;
}
```
![](../docassets/images/form-style-sample.png)
## See also
- [FormFieldValidator](form-field-validator.interface.md)
- [Extensibility](../extensibility.md)
- [Form rendering service](form-rendering.service.md)
- [Form field model](form-field.model.md)

157
docs/core/form.service.md Normal file
View File

@@ -0,0 +1,157 @@
---
Added: v2.0.0
Status: Active
---
# Form service
Implements Process Services form methods
## Basic Usage
```ts
import { FormService, FormEvent, FormFieldEvent } from '@alfresco/adf-core';
@Component(...)
class MyComponent {
constructor(formService: FormService) {
formService.formLoaded.subscribe(
(e: FormEvent) => {
console.log(`Form loaded: ${e.form.id}`);
}
);
formService.formFieldValueChanged.subscribe(
(e: FormFieldEvent) => {
console.log(`Field value changed. Form: ${e.form.id}, Field: ${e.field.id}, Value: ${e.field.value}`);
}
);
}
}
```
### Events
| Name | Args Type | Description |
| ---- | --------- | ----------- |
| formLoaded | FormEvent | Raised when form has been loaded or reloaded |
| formFieldValueChanged | FormFieldEvent | Raised when input values change |
| taskCompleted | FormEvent | Raised when a task is completed successfully |
| taskCompletedError | FormErrorEvent | Raised when a task is completed unsuccessfully |
| taskSaved | FormEvent | Raised when a task is saved successfully |
| taskSavedError | FormErrorEvent | Raised when a task is saved unsuccessfully |
| executeOutcome | FormOutcomeEvent | Raised when a form outcome is executed |
| formEvents | Event | You can subscribe to this event to listen : ( click, blur, change, focus, focusin, focusout, input, invalid, select) of any elements in the form , see doc below |
| validateForm | ValidateFormEvent | Raised each time a form is validated. You can use it to provide custom validation or prevent default behaviour. |
| validateFormField | ValidateFormFieldEvent | Raised each time a form field is validated. You can use it to provide custom validation or prevent default behaviour. |
### Methods
- `parseForm(json: any, data?: FormValues, readOnly: boolean = false): FormModel`
Parses JSON data to create a corresponding Form model.
- `json` - JSON to create the form
- `data` - (Optional) Values for the form fields
- `readOnly` - Should the form fields be read-only?
- `createFormFromANode(formName: string): Observable<any>`
Create a Form with a field for each metadata property.
- `formName` - Name of the new form
- `createForm(formName: string): Observable<any>`
Create a Form.
- `formName` - Name of the new form
- `saveForm(formId: string, formModel: FormDefinitionModel): Observable<any>`
Saves a form.
- `formId` - ID of the form to save
- `formModel` - Model data for the form
- `addFieldsToAForm(formId: string, formModel: FormDefinitionModel): Observable<any>`
- `formId` - ID of the form
- `formModel` - Form definition
- `searchFrom(name: string): Observable<any>`
Search for a form by name.
- `name` - The form name to search for
- `getForms(): Observable<any>`
Gets all the forms.
- `getProcessDefinitions(): Observable<any>`
Get Process Definitions
- `getProcessVarablesById(processInstanceId: string): Observable<any[]>`
Get instance variables for a process.
- `processInstanceId` - ID of the target process
- `getTasks(): Observable<any>`
Gets all the tasks.
- `getTask(taskId: string): Observable<any>`
Gets a task.
- `taskId` - Task Id
- `saveTaskForm(taskId: string, formValues: FormValues): Observable<any>`
Save Task Form.
- `taskId` - Task Id
- `formValues` - Form Values
- `completeTaskForm(taskId: string, formValues: FormValues, outcome?: string): Observable<any>`
Complete Task Form
- `taskId` - Task Id
- `formValues` - Form Values
- `outcome` - (Optional) Form Outcome
- `getTaskForm(taskId: string): Observable<any>`
Get Form related to a taskId
- `taskId` - Task Id
- `getFormDefinitionById(formId: string): Observable<any>`
Get Form Definition
- `formId` - Form Id
- `getFormDefinitionByName(name: string): Observable<any>`
Returns form definition with a given name.
- `name` - The form name
- `getStartFormInstance(processId: string): Observable<any>`
Get start form instance for a given processId
- `processId` - Process definition ID
- `getProcessIntance(processId: string): Observable<any>`
Gets a process instance.
- `processId` - ID of the process to get
- `getStartFormDefinition(processId: string): Observable<any>`
Get start form definition for a given process
- `processId` - Process definition ID
- `getRestFieldValues(taskId: string, field: string): Observable<any>`
Gets values of fields populated by a REST backend.
- `taskId` - Task identifier
- `field` - Field identifier
- `getRestFieldValuesByProcessId(processDefinitionId: string, field: string): Observable<any>`
Gets values of fields populated by a REST backend using a process ID.
- `processDefinitionId` - Process identifier
- `field` - Field identifier
- `getRestFieldValuesColumnByProcessId(processDefinitionId: string, field: string, column?: string): Observable<any>`
Gets column values of fields populated by a REST backend using a process ID.
- `processDefinitionId` - Process identifier
- `field` - Field identifier
- `column` - (Optional) Column identifier
- `getRestFieldValuesColumn(taskId: string, field: string, column?: string): Observable<any>`
Gets column values of fields populated by a REST backend.
- `taskId` - Task identifier
- `field` - Field identifier
- `column` - (Optional) Column identifier
- `getUserProfileImageApi(userId: number): string`
Returns a URL for the profile picture of a user.
- `userId` - ID of the target user
- `getWorkflowUsers(filter: string, groupId?: string): Observable<UserProcessModel[]>`
Gets a list of workflow users.
- `filter` - Filter to select specific users
- `groupId` - (Optional) Group ID for the search
- `getWorkflowGroups(filter: string, groupId?: string): Observable<GroupModel[]>`
Gets a list of groups in a workflow.
- `filter` - Filter to select specific groups
- `groupId` - (Optional) Group ID for the search
- `getFormId(res: any): string`
Gets the ID of a form.
- `res` - Object representing a form
- `toJson(res: any): any`
Creates a JSON representation of form data.
- `res` - Object representing form data
- `toJsonArray(res: any): any`
Creates a JSON array representation of form data.
- `res` - Object representing form data
- `handleError(error: any): Observable<any>`
Reports an error message.
- `error` - Data object with optional \`message\` and \`status\` fields for the error

76
docs/core/start-form.component.md Normal file
View File

@@ -0,0 +1,76 @@
---
Added: v2.0.0
Status: Active
---
# Start Form component
Displays the Start Form for a process.
![Start Form screenshot](../docassets/images/ProcessStartForm.png)
## Basic Usage
```html
<adf-start-form
[processDefinitionId]="currentProcessDef.id"
(outcomeClick)="onOutcomeClick($event)">
</adf-start-form>
```
### Properties
| Name | Type | Default value | Description |
| ---- | ---- | ------------- | ----------- |
| processDefinitionId | `string` | | Definition ID of the process to start. |
| processId | `string` | | Process ID of the process to start. |
| showOutcomeButtons | `boolean` | `true` | Should form outcome buttons be shown? |
| showRefreshButton | `boolean` | `true` | Should the refresh button be shown? |
| readOnlyForm | `boolean` | `false` | Is the form read-only (ie, can't be edited)? |
| form | `FormModel` | | Underlying form model instance. |
| taskId | `string` | | Task id to fetch corresponding form and values. |
| nodeId | `string` | | Content Services node ID for the form metadata. |
| formId | `string` | | The id of the form definition to load and display with custom values. |
| formName | `string` | | Name of the form definition to load and display with custom values. |
| saveMetadata | `boolean` | `false` | Toggle saving of form metadata. |
| data | `FormValues` | | Custom form values map to be used with the rendered form. |
| path | `string` | | Path of the folder where the metadata will be stored. |
| nameNode | `string` | | Name to assign to the new node where the metadata are stored. |
| showTitle | `boolean` | `true` | Toggle rendering of the form title. |
| showCompleteButton | `boolean` | `true` | Toggle rendering of the `Complete` outcome button. |
| disableCompleteButton | `boolean` | `false` | If true then the `Complete` outcome button is shown but it will be disabled. |
| disableStartProcessButton | `boolean` | `false` | If true then the `Start Process` outcome button is shown but it will be disabled. |
| showSaveButton | `boolean` | `true` | Toggle rendering of the `Save` outcome button. |
| showDebugButton | `boolean` | `false` | Toggle debug options. |
| readOnly | `boolean` | `false` | Toggle readonly state of the form. Forces all form widgets to render as readonly if enabled. |
| showRefreshButton | `boolean` | `true` | Toggle rendering of the `Refresh` button. |
| showValidationIcon | `boolean` | `true` | Toggle rendering of the validation icon next to the form title. |
| fieldValidators | `FormFieldValidator[]` | `[]` | Contains a list of form field validator instances. |
### Events
| Name | Type | Description |
| ---- | ---- | ----------- |
| outcomeClick | `EventEmitter<any>` | Emitted when the user clicks one of the outcome buttons that completes the form. |
| formContentClicked | `EventEmitter<ContentLinkModel>` | Emitted when a field of the form is clicked. |
| formSaved | `EventEmitter<FormModel>` | Emitted when the form is submitted with the `Save` or custom outcomes. |
| formCompleted | `EventEmitter<FormModel>` | Emitted when the form is submitted with the `Complete` outcome. |
| formContentClicked | `EventEmitter<ContentLinkModel>` | Emitted when form content is clicked. |
| formLoaded | `EventEmitter<FormModel>` | Emitted when the form is loaded or reloaded. |
| formDataRefreshed | `EventEmitter<FormModel>` | Emitted when form values are refreshed due to a data property change. |
| executeOutcome | `EventEmitter<FormOutcomeEvent>` | Emitted when any outcome is executed. Default behaviour can be prevented via `event.preventDefault()`. |
| onError | `EventEmitter<any>` | Emitted when any error occurs. |
## Details
The [Start Process component](../start-process.component.md) uses the Start Form component
to display the
[start form](http://docs.alfresco.com/process-services1.6/topics/none_start_event.html)
for the process.
The `outcomeClick` event is passed a string containing the ID of the outcome button that
the user clicked. You can pass this value to the `startProcess` method (defined in the
[Process service](../process-services/process.service.md)) when activating the process, if necessary.
## See also
- [Process service](../process-services/process.service.md)