#572 basic documentation on form component

ng2-components/ng2-activiti-form/README.md

@@ -40,10 +40,88 @@ Also make sure you include these dependencies in your `index.html` file:
 <link rel="stylesheet" href="node_modules/material-design-icons/iconfont/material-icons.css">
 ```
 
-## Basic usage example
+## Basic usage examples
+
+### Display form instance by task id
 
 ```html
-<activiti-form [taskId]="selectedTask?.id"></activiti-form>
+<activiti-form 
+    [taskId]="selectedTask?.id">
+</activiti-form>
+```
+
+For an existing Task both form and values will be fetched and displayed.
+
+### Display form definition by form id
+
+```html
+<activiti-form 
+    [formId]="selectedFormDefinition?.id"
+    [data]="customData">
+</activiti-form>
+```
+
+Only form definition will be fetched
+
+### Display form definition by form name
+
+```html
+<activiti-form 
+    [formName]="selectedFormDefinition?.name"
+    [data]="customData">
+</activiti-form>
+```
+
+## 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
+<activiti-form 
+    [taskId]="selectedTask?.id"
+    formSaved="onFormSaved($event)">
+</activiti-form>
+```
+
+**MyView.component.ts**
+```ts
+onFormSaved(form: FormModel) {
+    console.log(form);
+}
 ```
 
 ## Build from sources

ng2-components/ng2-activiti-form/src/components/activiti-form.component.spec.ts

@@ -449,10 +449,10 @@ describe('ActivitiForm', () => {
         });
 
         let saved = false;
-        let eventValues = null;
+        let savedForm = null;
-        formComponent.formSaved.subscribe((values) => {
+        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', () => {

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<FormModel> = new EventEmitter<FormModel>();
 
     @Output()
-    formCompleted = new EventEmitter();
+    formCompleted: EventEmitter<FormModel> = new EventEmitter<FormModel>();
 
     @Output()
-    formLoaded = new EventEmitter();
+    formLoaded: EventEmitter<FormModel> = new EventEmitter<FormModel>();
 
     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
                 );
         }