mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-07-24 17:32:15 +00:00
[ADF-1453] Restructure README.md files (#2239)
* ADF-1453: Restructured Activiti Analytics readme * ADF-1453: Restructured Activiti Diagrams readme * ADF-1453: Restructured Activiti Form readme * ADF-1453: Restructured Activiti Process List readme * ADF-1453: Restructured Activiti Task List readme * ADF-1453: Restructured Alfresco Core readme * [ADF-1453] Restructured DataTable readme * [ADF-1453] Restructured Document List readme * [ADF-1453] Restructured Login readme * [ADF-1453] Restructured Alfresco Search readme * [ADF-1453] Restructured Alfresco Social readme * [ADF-1453] Restructured Alfresco Tag readme * [ADF-1453] Restructured Alfresco User Info readme * [ADF-1453] Restructured Alfresco Viewer readme * [ADF-1453] Restructured Alfresco Webscript readme * [ADF-1453] Fixed table display glitch * [ADF-1453] Fixed Markdown lint errors in readme files * [ADF-1453] Adding missing fileUploadDelete event to table in Upload readme * [ADF-1453] Resolved merge conflict with Upload readme * [ADF-1453] Changes from npm run doc
This commit is contained in:
Andy Stark
Mario Romano
@@ -1,4 +1,6 @@
|
||||
# APS Form Component
|
||||
# APS Form library
|
||||
|
||||
Contains the Activiti Form component and other related components and services.
|
||||
|
||||
<!-- markdown-toc start - Don't edit this section. npm run toc to generate it-->
|
||||
|
||||
@@ -7,40 +9,45 @@
|
||||
- [Library Contents](#library-contents)
|
||||
* [Components](#components)
|
||||
* [Services](#services)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Install](#install)
|
||||
- [Form Component](#form-component)
|
||||
* [Properties](#properties)
|
||||
- [Activiti Form component](#activiti-form-component)
|
||||
* [Basic Usage](#basic-usage)
|
||||
+ [Properties](#properties)
|
||||
+ [Advanced properties](#advanced-properties)
|
||||
+ [Events](#events)
|
||||
* [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)
|
||||
* [Advanced properties](#advanced-properties)
|
||||
* [Events](#events)
|
||||
* [Custom empty form template](#custom-empty-form-template)
|
||||
* [Controlling outcome execution behaviour](#controlling-outcome-execution-behaviour)
|
||||
- [Activiti Content Component](#activiti-content-component)
|
||||
* [Properties](#properties-1)
|
||||
* [Events](#events-1)
|
||||
* [Basic Usage](#basic-usage-1)
|
||||
+ [Properties](#properties-1)
|
||||
+ [Events](#events-1)
|
||||
- [ADF Form List Component](#adf-form-list-component)
|
||||
* [Properties](#properties-2)
|
||||
* [Basic Usage](#basic-usage-2)
|
||||
+ [Properties](#properties-2)
|
||||
- [FormService Service](#formservice-service)
|
||||
* [Events](#events-2)
|
||||
* [Methods](#methods)
|
||||
- [Common scenarios](#common-scenarios)
|
||||
* [Changing field value based on another field](#changing-field-value-based-on-another-field)
|
||||
* [Listen all form Events](#listen-all-form-events)
|
||||
* [Basic Usage](#basic-usage-3)
|
||||
+ [Events](#events-2)
|
||||
+ [Methods](#methods)
|
||||
- [Other documentation](#other-documentation)
|
||||
* [Common scenarios](#common-scenarios)
|
||||
+ [Changing field value based on another field](#changing-field-value-based-on-another-field)
|
||||
+ [Listen all form Events](#listen-all-form-events)
|
||||
- [See also](#see-also)
|
||||
- [Build from sources](#build-from-sources)
|
||||
- [NPM scripts](#npm-scripts)
|
||||
- [Demo](#demo)
|
||||
- [License](#license)
|
||||
- [Project Information](#project-information)
|
||||
* [Prerequisites](#prerequisites)
|
||||
* [Install](#install)
|
||||
* [Build from sources](#build-from-sources)
|
||||
* [NPM scripts](#npm-scripts)
|
||||
* [Demo](#demo)
|
||||
* [License](#license)
|
||||
|
||||
<!-- tocstop -->
|
||||
|
||||
<!-- markdown-toc end -->
|
||||
|
||||
See it live: [Form Quickstart](https://embed.plnkr.co/YSLXTqb3DtMhVJSqXKkE/)
|
||||
|
||||
## Library Contents
|
||||
|
||||
### Components
|
||||
@@ -57,22 +64,11 @@ See it live: [Form Quickstart](https://embed.plnkr.co/YSLXTqb3DtMhVJSqXKkE/)
|
||||
- NodeService
|
||||
- WidgetVisibilityService
|
||||
|
||||
## Prerequisites
|
||||
## Activiti Form component
|
||||
|
||||
Before you start using this development framework, make sure you have installed all required software and done all the
|
||||
necessary configuration, see this [page](https://github.com/Alfresco/alfresco-ng2-components/blob/master/PREREQUISITES.md).
|
||||
The component shows a Form from Activiti (see it live: [Form Quickstart](https://embed.plnkr.co/YSLXTqb3DtMhVJSqXKkE/))
|
||||
|
||||
> If you plan to use this component with projects generated by Angular CLI, you can read more in [Using ADF with Angular CLI](https://github.com/Alfresco/alfresco-ng2-components/wiki/Angular-CLI)
|
||||
|
||||
## Install
|
||||
|
||||
```sh
|
||||
npm install ng2-activiti-form
|
||||
```
|
||||
|
||||
## Form Component
|
||||
|
||||
The component shows a Form from Activiti
|
||||
### Basic Usage
|
||||
|
||||
```html
|
||||
<adf-form
|
||||
@@ -149,9 +145,7 @@ and store the form field as metadata. The param nameNode is optional.
|
||||
</adf-form>
|
||||
```
|
||||
|
||||
### Properties
|
||||
|
||||
The recommended set of properties can be found in the following table:
|
||||
#### Properties
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -169,7 +163,116 @@ The recommended set of properties can be found in the following table:
|
||||
| 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 below* | Contains a list of form field validator instances. |
|
||||
| fieldValidators | FormFieldValidator[] | See [Form Field Validators](#form-field-validators) section below | Contains a list of form field validator instances. |
|
||||
|
||||
#### Advanced properties
|
||||
|
||||
The following properties are for complex customisation purposes:
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| form | FormModel | | Underlying form model instance. |
|
||||
| showDebugButton | boolean | false | Toggle debug options. |
|
||||
| debugMode | boolean | false | Toggle debug mode, allows displaying additional data for development and debugging purposes. |
|
||||
|
||||
#### Events
|
||||
|
||||
| Name | Return Type | Description |
|
||||
| --- | --- | --- |
|
||||
| formLoaded | [FormModel](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form.model.ts) | Invoked when form is loaded or reloaded. |
|
||||
| formSaved | [FormModel](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form.model.ts) | Invoked when form is submitted with `Save` or custom outcomes. |
|
||||
| formCompleted | [FormModel](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form.model.ts) | Invoked when form is submitted with `Complete` outcome. |
|
||||
| formDataRefreshed | [FormModel](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form.model.ts) | Invoked when form values are refreshed due to a data property change |
|
||||
| executeOutcome | [FormOutcomeEvent](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form-outcome-event.model.ts) | Invoked when any outcome is executed, default behaviour can be prevented via `event.preventDefault()` |
|
||||
| onError | any | Invoked at any error |
|
||||
|
||||
### 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 'ng2-activiti-form';
|
||||
|
||||
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.**
|
||||
|
||||
#### Form Field Validators
|
||||
|
||||
@@ -301,124 +404,19 @@ Now if you run the application and try to enter "admin" in one of the text field
|
||||
|
||||
|
||||
|
||||
### Advanced properties
|
||||
|
||||
The following properties are for complex customisation purposes:
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| form | FormModel | | Underlying form model instance. |
|
||||
| showDebugButton | boolean | false | Toggle debug options. |
|
||||
| debugMode | boolean | false | Toggle debug mode, allows displaying additional data for development and debugging purposes. |
|
||||
|
||||
### Events
|
||||
|
||||
| Name | Return Type | Description |
|
||||
| --- | --- | --- |
|
||||
| formLoaded | [FormModel](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form.model.ts) | Invoked when form is loaded or reloaded. |
|
||||
| formSaved | [FormModel](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form.model.ts) | Invoked when form is submitted with `Save` or custom outcomes. |
|
||||
| formCompleted | [FormModel](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form.model.ts) | Invoked when form is submitted with `Complete` outcome. |
|
||||
| formDataRefreshed | [FormModel](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form.model.ts) | Invoked when form values are refreshed due to a data property change |
|
||||
| executeOutcome | [FormOutcomeEvent](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-activiti-form/src/components/widgets/core/form-outcome-event.model.ts) | Invoked when any outcome is executed, default behaviour can be prevented via `event.preventDefault()` |
|
||||
| onError | any | Invoked at any error |
|
||||
|
||||
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 'ng2-activiti-form';
|
||||
|
||||
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.**
|
||||
|
||||
## Activiti Content Component
|
||||
|
||||
The component shows the content preview.
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```html
|
||||
<adf-content
|
||||
<adf-content
|
||||
[contentId]="'1001'">
|
||||
</adf-content>
|
||||
```
|
||||
|
||||
### Properties
|
||||
#### Properties
|
||||
|
||||
The recommended set of properties can be found in the following table:
|
||||
|
||||
@@ -426,7 +424,7 @@ The recommended set of properties can be found in the following table:
|
||||
| --- | --- | --- | --- |
|
||||
| contentId | string | | The content id to show. |
|
||||
|
||||
### Events
|
||||
#### Events
|
||||
|
||||
| Name | Description |
|
||||
| --- | --- |
|
||||
@@ -436,13 +434,15 @@ The recommended set of properties can be found in the following table:
|
||||
|
||||
The component shows the activiti 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
|
||||
#### Properties
|
||||
|
||||
The recommended set of properties can be found in the following table:
|
||||
|
||||
@@ -452,6 +452,8 @@ The recommended set of properties can be found in the following table:
|
||||
|
||||
## FormService Service
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```ts
|
||||
import { FormService, FormEvent, FormFieldEvent } from 'ng2-activiti-form';
|
||||
|
||||
@@ -477,7 +479,7 @@ class MyComponent {
|
||||
}
|
||||
```
|
||||
|
||||
### Events
|
||||
#### Events
|
||||
|
||||
| Name | Args Type | Description |
|
||||
| --- | --- | --- |
|
||||
@@ -492,7 +494,7 @@ class MyComponent {
|
||||
| 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
|
||||
#### Methods
|
||||
|
||||
| Name | Params | Returns | Description |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -519,9 +521,11 @@ class MyComponent {
|
||||
| getWorkflowGroups\ | (filter: string, groupId?: string) | Observable\<GroupModel[]\> | |
|
||||
| getWorkflowUsers\ | (filter: string, groupId?: string) | Observable\<GroupUserModel[]\> | |
|
||||
|
||||
## Common scenarios
|
||||
## Other documentation
|
||||
|
||||
### Changing field value based on another field
|
||||
### Common scenarios
|
||||
|
||||
#### Changing field value based on another field
|
||||
|
||||
Create a simple Form with a dropdown widget (id: `type`), and a multiline text (id: `description`).
|
||||
|
||||
@@ -544,7 +548,7 @@ The result should be as following:
|
||||
|
||||
|
||||
|
||||
### Listen all form Events
|
||||
#### Listen all form Events
|
||||
|
||||
If you want to listen all the events fired in the form you can subscribe to this Subject :
|
||||
|
||||
@@ -560,7 +564,22 @@ formService.formEvents.subscribe((event: Event) => {
|
||||
- [Form Stencils with Angular 2](docs/stencils.md)
|
||||
- [Form Extensibility and Customisation](docs/extensibility.md).
|
||||
|
||||
## Build from sources
|
||||
## Project Information
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Before you start using this development framework, make sure you have installed all required software and done all the
|
||||
necessary configuration, see this [page](https://github.com/Alfresco/alfresco-ng2-components/blob/master/PREREQUISITES.md).
|
||||
|
||||
> If you plan to use this component with projects generated by Angular CLI, you can read more in [Using ADF with Angular CLI](https://github.com/Alfresco/alfresco-ng2-components/wiki/Angular-CLI)
|
||||
|
||||
### Install
|
||||
|
||||
```sh
|
||||
npm install ng2-activiti-form
|
||||
```
|
||||
|
||||
### Build from sources
|
||||
|
||||
You can build the component from sources with the following commands:
|
||||
|
||||
@@ -572,7 +591,7 @@ npm run build
|
||||
> The `build` task rebuilds all the code, runs tslint, license checks
|
||||
> and other quality check tools before performing unit testing.
|
||||
|
||||
## NPM scripts
|
||||
### NPM scripts
|
||||
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
@@ -581,7 +600,7 @@ npm run build
|
||||
| npm run test-browser | Run unit tests in the browser
|
||||
| npm run coverage | Run unit tests and display code coverage report |
|
||||
|
||||
## Demo
|
||||
### Demo
|
||||
|
||||
Please check the demo folder for a demo project
|
||||
|
||||
@@ -591,6 +610,6 @@ npm install
|
||||
npm start
|
||||
```
|
||||
|
||||
## License
|
||||
### License
|
||||
|
||||
[Apache Version 2.0](https://github.com/Alfresco/alfresco-ng2-components/blob/master/LICENSE)
|
||||
Reference in New Issue
Block a user