mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-07-24 17:32:15 +00:00
[ADF-1586] Added doc files for Form library (#2503)
* [ADF-1586] Added docs for Form library * [ADF-1586] Added updated doc index
This commit is contained in:
Andy Stark
committed by
Eugenio Romano
Eugenio Romano
parent
b7e00caee1
commit
de8fa02ef7
@@ -13,9 +13,7 @@ The component shows a Form from Activiti (see it live: [Form Quickstart](https:/
|
||||
- [Details](#details)
|
||||
* [Custom empty form template](#custom-empty-form-template)
|
||||
* [Controlling outcome execution behaviour](#controlling-outcome-execution-behaviour)
|
||||
* [Form Field Validators](#form-field-validators)
|
||||
+ [Custom set of validators](#custom-set-of-validators)
|
||||
+ [Custom validator example](#custom-validator-example)
|
||||
* [Field Validators](#field-validators)
|
||||
- [Other documentation](#other-documentation)
|
||||
* [Common scenarios](#common-scenarios)
|
||||
+ [Changing field value based on another field](#changing-field-value-based-on-another-field)
|
||||
@@ -122,7 +120,7 @@ and store the form field as metadata. The param nameNode is optional.
|
||||
| saveMetadata | boolean | false | Store the value of the form as metadata. |
|
||||
| path | string | | Path of the folder where to store the metadata. |
|
||||
| nameNode | string | true | Name to assign to the new node where the metadata are stored. |
|
||||
| fieldValidators | FormFieldValidator[] | See [Form Field Validators](#form-field-validators) section below | Contains a list of form field validator instances. |
|
||||
| fieldValidators | FormFieldValidator[] | See [Field Validators](#field-validators) section below | Contains a list of form field validator instances. |
|
||||
|
||||
### Advanced properties
|
||||
|
||||
@@ -233,135 +231,14 @@ There are two additional functions that can be of a great value when controlling
|
||||
**Please note that if `event.preventDefault()` is not called then default outcome behaviour
|
||||
will also be executed after your custom code.**
|
||||
|
||||
### Form Field Validators
|
||||
### Field Validators
|
||||
|
||||
The Form component provides you with access to all Form Field validators. By default the following instances are created automatically:
|
||||
|
||||
- RequiredFieldValidator
|
||||
- NumberFieldValidator
|
||||
- MinLengthFieldValidator
|
||||
- MaxLengthFieldValidator
|
||||
- MinValueFieldValidator
|
||||
- MaxValueFieldValidator
|
||||
- RegExFieldValidator
|
||||
- DateFieldValidator
|
||||
- MinDateFieldValidator
|
||||
- MaxDateFieldValidator
|
||||
|
||||
If needed, you can completely redefine the set of validators used by the form.
|
||||
|
||||
All changes to `fieldValidators` collection are automatically applied to all the further validation cycles.
|
||||
|
||||
#### Custom set of validators
|
||||
|
||||
You can provide your own set of field validators based on either custom validator instances, or a mixture of default and custom ones.
|
||||
|
||||
```html
|
||||
<adf-form [fieldValidators]="fieldValidators"></adf-form>
|
||||
```
|
||||
|
||||
The Form component exposes a special `FORM_FIELD_VALIDATORS` constant that allows you get a quick access to all system validator instances.
|
||||
|
||||
```ts
|
||||
import { FORM_FIELD_VALIDATORS } from 'ng2-activiti-form';
|
||||
|
||||
@Component({...})
|
||||
export class AppComponent {
|
||||
|
||||
fieldValidators = [
|
||||
// default set of ADF validators if needed
|
||||
...FORM_FIELD_VALIDATORS,
|
||||
|
||||
// custom validators
|
||||
new MyValidator1(),
|
||||
new MyValidator2()
|
||||
];
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
#### Custom validator example
|
||||
|
||||
A form field validator must implement the "FormFieldValidator" interface:
|
||||
|
||||
```ts
|
||||
export interface FormFieldValidator {
|
||||
|
||||
isSupported(field: FormFieldModel): boolean;
|
||||
validate(field: FormFieldModel): boolean;
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
There might be many different validators used for various field types and purposes,
|
||||
so the validation layer needs every validator instance to support "isSupported" call.
|
||||
|
||||
It is up to validator to declare support for a form field.
|
||||
If you want to check field types 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 can help you with the predefined constants and helper methods.
|
||||
|
||||
In addition every validator has access to all underlying APIs of the [FormFieldModel](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form-field.model.ts),
|
||||
including the reference to the Form instance and so other form fields.
|
||||
|
||||
Below is a source code for a demo validator that is executed for all the "TEXT" fields, and ensures the value is not "admin", otherwise the `field.validationSummary` value is set to an error.
|
||||
|
||||
```ts
|
||||
import { FormFieldModel, FormFieldTypes, FormFieldValidator } from 'ng2-activiti-form';
|
||||
|
||||
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;
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
Your component can extend the default validation set instead of replacing it entirely.
|
||||
In the example below we redefine a default validation set with an additional "DemoFieldValidator":
|
||||
|
||||
```ts
|
||||
import { DemoFieldValidator } from './demo-field-validator';
|
||||
|
||||
@Component({...})
|
||||
export class AppComponent {
|
||||
|
||||
fieldValidators = [
|
||||
...FORM_FIELD_VALIDATORS,
|
||||
new DemoFieldValidator()
|
||||
];
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
You can now use the 'fieldValidators' property with the Form or Task Details components to assign custom validator set for the underlying Form Model:
|
||||
|
||||
```html
|
||||
<activiti-task-details
|
||||
[fieldValidators]="fieldValidators"
|
||||
taskId="123">
|
||||
</<activiti-task-details>
|
||||
|
||||
<!-- OR -->
|
||||
|
||||
<adf-form
|
||||
[fieldValidators]="fieldValidators"
|
||||
taskI="123">
|
||||
</adf-form>
|
||||
```
|
||||
|
||||
Now if you run the application and try to enter "admin" in one of the text fields (either optional or required), you should see the following error:
|
||||
|
||||
|
||||
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](FormFieldValidator.md) class for full details and examples.
|
||||
|
||||
## Other documentation
|
||||
|
||||
@@ -401,7 +278,13 @@ formService.formEvents.subscribe((event: Event) => {
|
||||
});
|
||||
```
|
||||
|
||||
<!-- Don't edit the See also section. Edit seeAlsoGraph.json and run config/generateSeeAlso.js -->
|
||||
<!-- seealso start -->
|
||||
## See also
|
||||
|
||||
- [Form Stencils with Angular 2](stencils.md)
|
||||
- [Form Extensibility and Customisation](extensibility.md).
|
||||
- [Stencils](stencils.md)
|
||||
- [FormFieldValidator](FormFieldValidator.md)
|
||||
- [Extensibility](extensibility.md)
|
||||
- [Form rendering service](form-rendering.service.md)
|
||||
- [Form field model](form-field.model.md)
|
||||
<!-- seealso end -->
|
||||
Reference in New Issue
Block a user