diff --git a/docIndex.md b/docIndex.md index 8e173ce482..c30d6e8534 100644 --- a/docIndex.md +++ b/docIndex.md @@ -42,12 +42,12 @@ Contains the Analytics component and other related items. See the library's [README file](ng2-components/ng2-activiti-analytics/README.md) for more information about installing and using the source code. - + **Documented** -- [Analytics component](ng2-components/ng2-activiti-analytics/README.md) -- [Analytics report list component](ng2-components/ng2-activiti-analytics/README.md) -- [Analytics generator component](ng2-components/ng2-activiti-analytics/README.md) +- [Analytics generator component](docs/analytics-generator.component.md) +- [Analytics report list component](docs/analytics-report-list.component.md) +- [Analytics component](docs/analytics.component.md) **Undocumented** @@ -70,10 +70,10 @@ Contains the Diagram component and other related items. See the library's [README file](ng2-components/ng2-activiti-diagrams/README.md) for more information about installing and using the source code. - + **Documented** -- [Diagram component](ng2-components/ng2-activiti-diagrams/README.md) +- [Diagram component](docs/diagram.component.md) **Undocumented** @@ -171,13 +171,13 @@ Contains the Form component and other related items. See the library's [README file](ng2-components/ng2-activiti-form/README.md) for more information about installing and using the source code. - + **Documented** -- [Form component](ng2-components/ng2-activiti-form/README.md) -- [Form list component](ng2-components/ng2-activiti-form/README.md) -- [Form service](ng2-components/ng2-activiti-form/README.md) -- [Content widget](ng2-components/ng2-activiti-form/README.md) +- [Form list component](docs/form-list.component.md) +- [Form component](docs/form.component.md) +- [Content widget](docs/content.widget.md) +- [Form service](docs/form.service.md) **Undocumented** diff --git a/docassets/images/analytics-without-parameters.png b/docassets/images/analytics-without-parameters.png new file mode 100644 index 0000000000..06146ecd33 Binary files /dev/null and b/docassets/images/analytics-without-parameters.png differ diff --git a/docassets/images/demo-validator.png b/docassets/images/demo-validator.png new file mode 100644 index 0000000000..e06d00b0c6 Binary files /dev/null and b/docassets/images/demo-validator.png differ diff --git a/docassets/images/form-service-sample-01.png b/docassets/images/form-service-sample-01.png new file mode 100644 index 0000000000..479144ac25 Binary files /dev/null and b/docassets/images/form-service-sample-01.png differ diff --git a/docs/analytics-generator.component.md b/docs/analytics-generator.component.md new file mode 100644 index 0000000000..8fe69e6bcd --- /dev/null +++ b/docs/analytics-generator.component.md @@ -0,0 +1,38 @@ +# Analytics Generator Component + +The component generates and shows the charts + + + + + +- [Basic Usage](#basic-usage) + * [Properties](#properties) + * [Events](#events) + + + + + +## Basic Usage + +```html + + +``` + +### Properties + +| Name | Type | Description | +| --- | --- | -- | +| reportId | string | The report id | +| reportParamQuery | ReportQuery | The object contains all the parameters that the report needs | + +### Events + +| Name | Description | +| --- | --- | +| onSuccess | Raised when the charts are loaded | +| onError | Raised when an error occurs during the loading | \ No newline at end of file diff --git a/docs/analytics-report-list.component.md b/docs/analytics-report-list.component.md new file mode 100644 index 0000000000..43165fb0ad --- /dev/null +++ b/docs/analytics-report-list.component.md @@ -0,0 +1,39 @@ +# Activiti Analytics List Component + +The component shows the list of all the available reports + + + + + +- [Basic Usage](#basic-usage) + * [Properties](#properties) + * [Events](#events) + + + + + +## Basic Usage + +```html + + +``` + +### Properties + +| Name | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| appId | string | optional | | The application id | +| layoutType | string | required | | Define the layout of the apps. There are two possible values: GRID or LIST. LIST is the default value| +| selectFirst | boolean | optional | false | Change the value to true if you want to select the first item in the list as default| + +### Events + +| Name | Description | +| --- | --- | +| onSuccess | The event is emitted when the report list is loaded | +| onError | The event is emitted when an error occurs during the loading | +| reportClick | The event is emitted when the report in the list is selected | diff --git a/docs/analytics.component.md b/docs/analytics.component.md new file mode 100644 index 0000000000..2a38d5706d --- /dev/null +++ b/docs/analytics.component.md @@ -0,0 +1,53 @@ +# Activiti Analytics Component + +The component shows the charts related to the reportId passed as input + + + + + +- [Basic Usage](#basic-usage) + * [Properties](#properties) + * [Events](#events) + + + + + +## Basic Usage + +```html + + +``` + +### Properties + +| Name | Type | Description | +| --- | --- | --- | +| appId | string | The application id | +| reportId | string | The report id | +| hideParameters | boolean | Toggle the analytics parameters | + +You can also hide chart parameters UI by setting the `hideParameters` to `true`: + +```html + + +``` + +![Analytics-without-parameters](../docassets/images/analytics-without-parameters.png) + +### Events + +| Name | Description | +| --- | --- | +| onSuccess | The event is emitted when the report parameters are loaded | +| onError | The event is emitted when an error occurs during the loading | +| reportSaved | The event is emitted when a report is saved | +| reportDeleted | The event is emitted when a report is deleted | \ No newline at end of file diff --git a/docs/content.widget.md b/docs/content.widget.md new file mode 100644 index 0000000000..f1fa2b000f --- /dev/null +++ b/docs/content.widget.md @@ -0,0 +1,37 @@ +# Activiti Content Component + +The component shows the content preview. + + + + + +- [Basic Usage](#basic-usage) + * [Properties](#properties) + * [Events](#events) + + + + + +## Basic Usage + +```html + + +``` + +### Properties + +The recommended set of properties can be found in the following table: + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| contentId | string | | The content id to show. | + +### Events + +| Name | Description | +| --- | --- | +| contentClick | Invoked when the content is clicked. | \ No newline at end of file diff --git a/docs/diagram.component.md b/docs/diagram.component.md new file mode 100644 index 0000000000..ac9cc9473b --- /dev/null +++ b/docs/diagram.component.md @@ -0,0 +1,49 @@ +# Activiti Diagram Component + + + + + +- [Basic Usage](#basic-usage) + * [Properties](#properties) + * [Events](#events) + + + + + +## Basic Usage + +This component shows the diagram of a process. + +```html + + +``` + +The below component shows the diagram of a running process instance with the activities highlighted according to their state (Active/Completed/Pending). + +```html + + +``` + +### Properties + +| Name | Type | Description | +| --- | --- | -- | +| metricPercentages | any | The array that contains the percentage of time for each element | +| processInstanceId | any | | +| metricColor | any | The array that contains the color for each element | +| metricType | any | The string that specifies the metric type | +| width | number | | +| height | number | | + +### Events + +| Name | Description | +| --- | --- | +| onSuccess | Raised when the diagrams elements are loaded | +| onError | Raised when an error occurs during loading | \ No newline at end of file diff --git a/docs/form-list.component.md b/docs/form-list.component.md new file mode 100644 index 0000000000..4a2c814c0e --- /dev/null +++ b/docs/form-list.component.md @@ -0,0 +1,30 @@ +# ADF Form List Component + +The component shows the activiti forms as a list. + + + + + +- [Basic Usage](#basic-usage) + * [Properties](#properties) + + + + + +## Basic Usage + +```html + + +``` + +### Properties + +The recommended set of properties can be found in the following table: + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| forms | any | | The array that contains the information to show inside the list. | \ No newline at end of file diff --git a/docs/form.component.md b/docs/form.component.md new file mode 100644 index 0000000000..d7f2023395 --- /dev/null +++ b/docs/form.component.md @@ -0,0 +1,406 @@ +# Activiti Form component + +The component shows a Form from Activiti (see it live: [Form Quickstart](https://embed.plnkr.co/YSLXTqb3DtMhVJSqXKkE/)) + + + + + +- [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) +- [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) + + + + + +## Basic Usage + +```html + + +``` + +**Display form instance by task id:** + +```html + + +``` + +For an existing Task both form and values will be fetched and displayed. + +**Display form definition by form id:** + +```html + + +``` + +Only form definition will be fetched. + +**Display form definition by form name:** + +```html + + +``` + +**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 + + +``` + +**Display form definition by form name, and store the form field as metadata:** + +The param nameNode is optional. + +```html + + +``` + +**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 + + +``` + +### Properties + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| taskId | string | | Task id to fetch corresponding form and values. | +| 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. | +| data | FormValues | | Custom form values map to be used with the rendered form. | +| showTitle | boolean | true | Toggle rendering of the form title. | +| showCompleteButton | boolean | true | Toggle rendering of the `Complete` outcome button. | +| disableCompleteButton | boolean | false | The `Complete` outcome button is shown but it will be disabled. | +| showSaveButton | boolean | true | Toggle rendering of the `Save` outcome button. | +| readOnly | boolean | false | Toggle readonly state of the form. Enforces all form widgets render readonly if enabled. | +| showRefreshButton | boolean | true | Toggle rendering of the `Refresh` button. | +| showValidationIcon | boolean | true | Toggle rendering of the validation icon next form title. | +| 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. | + +### 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 + + +``` + +**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 + + +
+

Empty 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 + + +``` + +**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 + +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 + +``` + +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 + + + + + + + +``` + +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: + +![](../docassets/images/demo-validator.png) + +## Other documentation + +### 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`). + +```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); +}); +``` + +## See also + +- [Form Stencils with Angular 2](stencils.md) +- [Form Extensibility and Customisation](extensibility.md). \ No newline at end of file diff --git a/docs/form.service.md b/docs/form.service.md new file mode 100644 index 0000000000..42ad4ed1cd --- /dev/null +++ b/docs/form.service.md @@ -0,0 +1,82 @@ +# FormService Service + + + + + +- [Basic Usage](#basic-usage) + * [Events](#events) + * [Methods](#methods) + + + + + +## Basic Usage + +```ts +import { FormService, FormEvent, FormFieldEvent } from 'ng2-activiti-form'; + +@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 + +| Name | Params | Returns | Description | +| --- | --- | --- | --- | +| createFormFromANode | (formName: string) | Observable\ | Create a Form with a fields for each metadata properties | +| createForm | (formName: string) | Observable\ | Create a Form | +| addFieldsToAForm | (formId: string, formModel: FormDefinitionModel) | Observable\ | Add Fileds to A form | +| searchFrom | (name: string) | Observable\ | Search For A Form by name | +| getForms | n/a | Observable\ | Get All the forms | +| getProcessDefinitions | n/a | Observable\ | Get Process Definitions | +| getTasks | n/a | Observable\ | Get All the Tasks | +| getTask | (taskId: string) | Observable\ | Get Task | +| saveTaskForm | (taskId: string, formValues: FormValues) | Observable\ | Save Task Form | +| completeTaskForm | (taskId: string, formValues: FormValues, outcome?: string) | Observable\ | Complete Task Form | +| getTaskForm | (taskId: string) | Observable\ | Get Form related to a taskId | +| getFormDefinitionById | (formId: string) | Observable\ | Get Form Definition | +| getFormDefinitionByName | (name: string) | Observable\ | Returns form definition by a given name. | +| getStartFormInstance | (processId: string) | Observable\ | Get start form instance for a given processId | +| getStartFormDefinition | (processId: string) | Observable\ | Get start form definition for a given process | +| createTemporaryRawRelatedContent | (file: any) | Observable\ | Save File | +| getRestFieldValues | (taskId: string, field: string) | Observable\ | | +| getRestFieldValuesByProcessId | (processDefinitionId: string, field: string) | Observable\ | | +| getRestFieldValuesColumnByProcessId | (processDefinitionId: string, field: string, column?: string) | Observable\ | | +| getRestFieldValuesColumn | (taskId: string, field: string, column?: string) | Observable\ | | +| getWorkflowGroups\ | (filter: string, groupId?: string) | Observable\ | | +| getWorkflowUsers\ | (filter: string, groupId?: string) | Observable\ | |