From d73f295033c0932464bfe6052d43d846ea6428b2 Mon Sep 17 00:00:00 2001 From: Denys Vuika Date: Thu, 18 Aug 2016 16:35:54 +0100 Subject: [PATCH] #572 basic documentation on form component --- ng2-components/ng2-activiti-form/README.md | 82 ++++++++++++++++++- .../activiti-form.component.spec.ts | 8 +- .../src/components/activiti-form.component.ts | 24 +++--- 3 files changed, 96 insertions(+), 18 deletions(-) diff --git a/ng2-components/ng2-activiti-form/README.md b/ng2-components/ng2-activiti-form/README.md index 77aab3526e..5f025df8a4 100644 --- a/ng2-components/ng2-activiti-form/README.md +++ b/ng2-components/ng2-activiti-form/README.md @@ -40,10 +40,88 @@ Also make sure you include these dependencies in your `index.html` file: ``` -## Basic usage example +## Basic usage examples + +### 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 + + +``` + +## Configuration + +### Properties + +The recommended set of properties can be found in the following table: + +| 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 hte 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. | +| 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. | + +#### Advanced properties + + The following properties are for complex customisation purposes: + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| form | `FormModel` | | Underlying form model instance. | +| debugMode | boolean | false | Toggle debug mode, allows displaying additional data for development and debugging purposes. | + +### Events + +| Name | Description | +| --- | --- | +| formLoaded | Invoked when form is loaded or reloaded. | +| formSaved | Invoked when form is submitted with `Save` or custom outcomes. | +| formCompleted | Invoked when form is submitted with `Complete` outcome. | + +All `form*` events recieve 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); +} ``` ## Build from sources diff --git a/ng2-components/ng2-activiti-form/src/components/activiti-form.component.spec.ts b/ng2-components/ng2-activiti-form/src/components/activiti-form.component.spec.ts index dbc9901062..a9b1ce5216 100644 --- a/ng2-components/ng2-activiti-form/src/components/activiti-form.component.spec.ts +++ b/ng2-components/ng2-activiti-form/src/components/activiti-form.component.spec.ts @@ -449,10 +449,10 @@ describe('ActivitiForm', () => { }); let saved = false; - let eventValues = null; - formComponent.formSaved.subscribe((values) => { + let savedForm = null; + formComponent.formSaved.subscribe(form => { saved = true; - eventValues = values; + savedForm = form; }); let formModel = new FormModel({ @@ -467,7 +467,7 @@ describe('ActivitiForm', () => { expect(formService.saveTaskForm).toHaveBeenCalledWith(formModel.taskId, formModel.values); expect(saved).toBeTruthy(); - expect(eventValues).toEqual(formModel.values); + expect(savedForm).toEqual(formModel); }); it('should handle error during form save', () => { diff --git a/ng2-components/ng2-activiti-form/src/components/activiti-form.component.ts b/ng2-components/ng2-activiti-form/src/components/activiti-form.component.ts index 266c1f622e..c01bd4ca7f 100644 --- a/ng2-components/ng2-activiti-form/src/components/activiti-form.component.ts +++ b/ng2-components/ng2-activiti-form/src/components/activiti-form.component.ts @@ -26,7 +26,7 @@ import { import { MATERIAL_DESIGN_DIRECTIVES } from 'ng2-alfresco-core'; import { FormService } from './../services/form.service'; -import { FormModel, FormOutcomeModel } from './widgets/core/index'; +import { FormModel, FormOutcomeModel, FormValues } from './widgets/core/index'; import { TabsWidget } from './widgets/tabs/tabs.widget'; import { ContainerWidget } from './widgets/container/container.widget'; @@ -88,7 +88,7 @@ export class ActivitiForm implements OnInit, AfterViewChecked, OnChanges { formName: string; @Input() - data: any; + data: FormValues; @Input() showTitle: boolean = true; @@ -106,13 +106,13 @@ export class ActivitiForm implements OnInit, AfterViewChecked, OnChanges { showRefreshButton: boolean = true; @Output() - formSaved = new EventEmitter(); + formSaved: EventEmitter = new EventEmitter(); @Output() - formCompleted = new EventEmitter(); + formCompleted: EventEmitter = new EventEmitter(); @Output() - formLoaded = new EventEmitter(); + formLoaded: EventEmitter = new EventEmitter(); form: FormModel; @@ -194,13 +194,13 @@ export class ActivitiForm implements OnInit, AfterViewChecked, OnChanges { } if (outcome.id === ActivitiForm.CUSTOM_OUTCOME_ID) { - this.formSaved.emit(this.form.values); + this.formSaved.emit(this.form); return true; } } else { // Note: Activiti is using NAME field rather than ID for outcomes if (outcome.name) { - this.formSaved.emit(this.form.values); + this.formSaved.emit(this.form); this.completeTaskForm(outcome.name); return true; } @@ -250,7 +250,7 @@ export class ActivitiForm implements OnInit, AfterViewChecked, OnChanges { .subscribe( form => { this.form = new FormModel(form, data, this.readOnly); - this.formLoaded.emit(this.form.values); + this.formLoaded.emit(this.form); }, this.handleError ); @@ -263,7 +263,7 @@ export class ActivitiForm implements OnInit, AfterViewChecked, OnChanges { form => { // console.log('Get Form By definition Id', form); this.form = this.parseForm(form); - this.formLoaded.emit(this.form.values); + this.formLoaded.emit(this.form); }, this.handleError ); @@ -278,7 +278,7 @@ export class ActivitiForm implements OnInit, AfterViewChecked, OnChanges { form => { // console.log('Get Form By Form definition Name', form); this.form = this.parseForm(form); - this.formLoaded.emit(this.form.values); + this.formLoaded.emit(this.form); }, this.handleError ); @@ -292,7 +292,7 @@ export class ActivitiForm implements OnInit, AfterViewChecked, OnChanges { this.formService .saveTaskForm(this.form.taskId, this.form.values) .subscribe( - () => this.formSaved.emit(this.form.values), + () => this.formSaved.emit(this.form), this.handleError ); } @@ -303,7 +303,7 @@ export class ActivitiForm implements OnInit, AfterViewChecked, OnChanges { this.formService .completeTaskForm(this.form.taskId, this.form.values, outcome) .subscribe( - () => this.formCompleted.emit(this.form.values), + () => this.formCompleted.emit(this.form), this.handleError ); }