From 3e76581cc6938498f23cc49d40aebcd5f7954a54 Mon Sep 17 00:00:00 2001
From: Denys Vuika <denis.vuyka@gmail.com>
Date: Thu, 24 Nov 2016 12:32:10 +0000
Subject: [PATCH] readme updates

---
 ng2-components/ng2-activiti-form/README.md    |   5 +-
 .../ng2-activiti-form/docs/stencils.md        | 143 ++++++++++++++++++
 2 files changed, 146 insertions(+), 2 deletions(-)
 create mode 100644 ng2-components/ng2-activiti-form/docs/stencils.md

diff --git a/ng2-components/ng2-activiti-form/README.md b/ng2-components/ng2-activiti-form/README.md
index 0f1b938059..a3f9ec4b1b 100644
--- a/ng2-components/ng2-activiti-form/README.md
+++ b/ng2-components/ng2-activiti-form/README.md
@@ -328,9 +328,10 @@ 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.**
 
-## Extensibility and customisation
+## See also
 
-Please refer to [Form Extensibility and Customisation](docs/extensibility.md).
+- [Form Stencils with Angular 2](docs/stencils.md)
+- [Form Extensibility and Customisation](docs/extensibility.md).
 
 ## Build from sources
 
diff --git a/ng2-components/ng2-activiti-form/docs/stencils.md b/ng2-components/ng2-activiti-form/docs/stencils.md
new file mode 100644
index 0000000000..fda713636b
--- /dev/null
+++ b/ng2-components/ng2-activiti-form/docs/stencils.md
@@ -0,0 +1,143 @@
+# Form Stencils with Angular 2
+
+Form component provides basic support for custom stencils created with Activiti stencil editor.
+
+## Installing
+
+Configuring support for stencils requires the following configuration for your `index.html` file:
+
+```html
+<!-- Stencils integration -->
+<script src="node_modules/ng2-activiti-form/stencils/runtime.ng1.js"></script>
+<script src="node_modules/ng2-activiti-form/stencils/runtime.adf.js"></script>
+<script src="http://<activiti-app-root>/app/rest/script-files/controllers"></script>
+```
+
+Where `<activiti-app-root>` should be replaced with a valid url pointing to your Activiti installation, for example:
+
+```html
+<script src="http://localhost:9999/activiti-app/app/rest/script-files/controllers"></script>
+```
+- `/app/rest/script-files/controllers`
+    provides all stencil controllers stored within Activiti
+
+- `runtime.ng1.js`
+    provides a compatibility layer for controllers created with Angular 1
+    (this is to avoid runtime errors when loading Angular 1 code into `<activiti-form>` component)
+
+- `runtime.adf.js`
+    provides API for stencil management and registration,
+    i.e. mapping html templates with corresponding controller classes
+
+## Creating new stencil
+
+Create a new stencil and add a new item called `ng2 component 01`.
+
+The internal identifier in this case should be `ng2_component_01`.
+This value will be used as field type when form gets rendered.
+
+## Form runtime template
+
+This should be a valid Angular 2 component template that you want to render in `<activiti-form>` component:
+
+```html
+<div>
+    <div>Angular2 Component</div>
+    <div>Created by: {{name}}</div>
+</div>
+```
+
+## Form editor template
+
+This can be any html layout to be rendered as a component placeholder in Activiti Form Designer.
+
+```html
+<div>
+    <div style="color: blue">
+        Angular2 Component 01
+    </div>
+</div>
+```
+
+## Custom component controller
+
+This field should contain JavaScript code for Angular 2 component class.
+
+_Note: If you are using TypeScript then you should be putting transpiled JavaScript code here,
+you can try official [TypeScript playground](http://www.typescriptlang.org/play/)
+to see how TS code gets transpiled into JS._
+
+### JavaScript code
+
+```js
+var SampleClass1 = (function () {
+    function SampleClass1() {
+        this.name = 'Denys';
+        console.log('ng2_component_01 ctor');
+    }
+    SampleClass1.prototype.ngOnInit = function () {
+      console.log('OnInit called');
+    };
+    return SampleClass1;
+}());
+```
+
+### TypeScript code
+
+The TypeScript version of the code above is:
+
+```ts
+import { OnInit } from '@angular/core';
+
+class Component1 implements OnInit {
+
+  constructor() {
+    console.log('ctor called');
+  }
+
+  ngOnInit() {
+    console.log('OnInit called');
+  }
+
+}
+```
+
+
+In order to map **form runtime template** with the corresponding component class
+you will need registering both parts with `adf.registerComponent` api:
+
+```js
+if (adf) {
+    adf.registerComponent('ng2_component_01', SampleClass1);
+}
+```
+
+### Final result
+
+```js
+var SampleClass1 = (function () {
+    function SampleClass1() {
+        this.name = 'Denys';
+        console.log('ng2_component_01 ctor');
+    }
+    SampleClass1.prototype.ngOnInit = function () {
+      console.log('OnInit called');
+    };
+    return SampleClass1;
+}());
+
+if (adf) {
+    adf.registerComponent('ng2_component_01', SampleClass1);
+}
+```
+
+## Runtime result
+
+When rendered on the form this stencil item should look like the following:
+
+```html
+Angular2 Component
+Created by: Denys
+```
+
+ADF Form component will automatically assemble and compile a valid Angular 2 component on the fly.
\ No newline at end of file