Form Stencil Examples - Alfresco Process Services (APS)

[cjose]

“Stencils” provide a very powerful set of capabilities to Alfresco Process Services powered by Activiti (APS) and can be used within the BPMN 2.0 Editor, the Step Editor and the Forms Editor.  Within the context of Forms, Stencils provide the facilities to develop custom form field types. The idea of this blog is to point you to some working form stencil samples.

In the recent weeks I had to build a few of these custom form stencils and thought it would be valuable to share it with the community. If you are someone who are just starting on stencils, I recommend you first read a 101 (introductory) blog on form stencils, which is available at Form Stencils 101.

In this blog I’ll take you through the following 5 form stencils:

1. Custom Simple Text Input
2. Grouping Fields using stencil
3. Custom Grid/Table
4. Signature Pad
5. Rich Text Editor

Now let me try and explain these examples a bit more....

Simple Text Input Stencil

Source: github: simple-text-input-stencil

I built this component to demonstrate the implementation of a very simple custom input field using stencil. You might be wondering, why would I need to do this? Most often you may not need such a field in real life, however the idea of this stencil is to demonstrate the basic building blocks, or “Hello World” for a stencil implementation.

Grouping Fields using Stencil

Source: github: group-of-fields-stencil

One of the main use cases around this example is to build reusable domain specific field controls. Eg: Build a single form field called “Address” which will consist of fields such as Address Line, Town, State, Country, Zip Code etc. Building reusable form components very specific to your business data objects makes form modelling really easy. Given below is a screenshot of design time view and runtime view of my example.

Design Time View

At design time, the designer will select the custom stencil and configure it with some process data as shown below

Configuration

Run Time View

At runtime, the stencil will be displayed based on your configuration using your custom html, custom css etc

Custom Grid/Table

Source: github: angular-ui-grid-stencil

I built this component recently for a customer who wanted to display a list of records from a REST API in a tabular format. I have to say that it took only 15 minutes for me to do the research and implement this feature using the Angular UI Grid component. Since APS OOTB UI use this module for the dynamic table component, the angular modules I needed to implement this feature was already part of the product. That made my life easy! So, if you have complex table requirements that cannot be met by the OOTB table component, I recommend you to look at all the features available in this library at Angular UI Grid Tutorial and I’m pretty sure that a stencil component built using the features available in this library can meet most of your needs

Important - Since AngularJS doesn't allow module injection after application is bootstrapped, one cannot declare an external module as part of the stencil controller code.
One of the options is to include an external AngularJS module into the "activitiApp" is by modifying "activiti-app/workflow/scripts/<minified script>.js" the following way.
eg: to add ngMap module from ng-map, one should this activitiApp=angular.module("activitiApp",[.,.,.,.,.,.,"ngMap"]) in the main module js file.
Please refer the comments where Greg has provided another option to load an external module.

Signature Pad

Source: github: signature-pad-stencil

A signature stencil implementation based on Signature Pad

Thanks to Angular Signature for providing the AngularJS directive which I used in my Stencil implementation. My example app, demonstrates the following:

1. Capture a signature
2. Display of a signature captured in a previous task
3. Display the signature in a document that is generated in the process.

Rich Text Editor

Source: github: tinymce-rich-text-editor

A rich text editor stencil implementation based on TinyMCE

Thanks to TinyMCE AngularJS Integration for providing the AngularJS directive which I used in my Stencil implementation.

General instructions to run the above examples

The zip archive files available in the above mentioned github source folders are “App” exports. To to use them, you will need to import them via App Designer (Kickstart App) -> Apps -> Import App. Once the “App” is successfully imported, the stencils along with an example process and form will also get imported which will make it easy for you to see these examples in action!

Finally..

Hopefully this is a good set of examples to show the power of stencil component in Alfresco Process Services. If you happen to build any cool form components using stencils, feel free to share it here in the form of a blog or video...

There are more examples available on the product documentation page - APS Docs: Custom Form Fields & https://community.alfresco.com/community/bpm/blog/2016/11/23/activiti-enterprise-developer-series-cu... 

Note: I’m in the process of building Alfresco ADF (Application Development Framework) equivalent of these stencils and as soon as they are ready, I’ll make it available and update this blog with the reference. A 101 blog on implementing form stencil components in ADF can be found here - Custom stencils with Alfresco ADF

UPDATE:

• ADF Signature Stencil implementation:  github: adf-examples/aps-signature-stencil-sample
• ADF Richtext Stencil implementation:  github: adf-examples/aps-richtext-stencil-sample 

[gdharley]

Hi Ciju,

Great blog post.

One comment on your Module Dependency Injection statement:
"Currently the only option to include an external AngularJS module into the "activitiApp" is by modifying "activiti-app/workflow/scripts/<minified script>.js" the following way."

There is another, slightly cleaner, way of adding module dependencies.

The resource loader (activiti-app/scripts/resource-loader.js) is the file that actually "bootstraps" the different applications (activitiLanding, activitiModeler, activitiApp) in the suite.
By updating this file, we are able to add dependencies prior to bootstrap.

Example

if (angular && typeof angular.bootstrap == 'function') {     angular.element(document.body).ready(function() {         // Add custom module dependencies         if(angularModuleName == "activitiLanding"){             angular.module(angularModuleName).requires.push("ui.bootstrap");         }         // angular, all of our resources & the document body are ready, lets bootstrap the app         angular.bootstrap(document.body, [angularModuleName]);     });     window.clearInterval(interval); }

The above example adds the ui.bootstrap module dependency to the "activitiLanding" application module.
Yes, this is a bit of a hack, but it is probably safer than updating minified files.

One hopes that the resource-loader will be enhanced in the future to not only allow for addition of scripts and css libraries, but also to register dependencies.

Cheers,

Greg

‌

[cjose]

Thank you so much for providing the alternative Greg, good to know this! I'll try this option soon.

[cjose]

ADF version of some of these stencil components are available in GitHub - Alfresco/adf-examples: Collection of simple (and less simple) Alfresco ADF projects. 

[amruta_w]

Hi Ciju,

You have provided nice examples.

All examples working fine in APS 1.7, these stencils are not available in the ADF2.2.0 so for this i have referred the document alfresco-ng2-components/extensibility.md at master · Alfresco/alfresco-ng2-components · GitHub.

The tinymce-rich-text-editor example i have tried but it just displays the multi-line textbox and not the tinymce-rich-text-editor.

The Component code is

/* tslint:disable */

import { Component, NgModule } from '@angular/core';

import { WidgetComponent } from '@alfresco/adf-core';

@Component({

selector: 'custom-editor3',

template: `

<div ng-controller="TinyMceController">

<textarea ui-tinymce="tinymceOptions" ng-model="tinymceModel"></textarea>

</div>

`

})

export class CustomEditor3Component extends WidgetComponent {

constructor() {

super();

}

}

@Component({

selector: 'richtext',

template: `<div style="color: green">ADF version of custom Activiti stencil</div>`

})

export class CustomStencil04 extends WidgetComponent {

constructor() {

super();

}

}

@NgModule({

declarations: [

CustomEditor3Component,

CustomStencil04

],

exports: [

CustomEditor3Component,

CustomStencil04

],

entryComponents: [

CustomEditor3Component,

CustomStencil04

]

})

export class Stencils3Module {}

Kindly help me out what i am missing here.

[kgastaldo]

Tagging ‌ and ‌ for input!

[cjose]

Amruta Wandakar APS is AngularJS & ADF is Angular without the JS! It is not going to work by just moving the AngularJS code into ADF! I have a rich text editor example tested with ADF available at adf-examples/ADF_1.5.0/aps-richtext-stencil-sample at master · Alfresco/adf-examples · GitHub. However this was developed a while ago and I'm not sure how current that code is, you may need some tweaks to get it working in the latest ADF version.

Ciju

[mdtabrezmca]

Hi Ciju,

    I am waiting to see full fledged stencil example using ADF by passing the parameters from backend and using it in the ADF component. A good example would be to create a process instance list(using Data table) component along side displaying some process varaibles. This Grid also should have following functionalities

1. Add new button should create a new instance and redirect to the active task of that process instance

2. Delete a process instance by selecting a process instance using a check box

3. Edit should always take to the active task of the process instance.

The above is just a thought if it is possible to provide a good example with above case then it would be really uses full as your all posts......

[elangu]

Hi Ciju,

I tried to import the zip file as stencil in APS version 1.9.0.5, but all I get is empty stencil. Is there any way to import it, or should the stencil be updated to a recent version of activiti?

I tried to follow the instructions in:

https://github.com/cijujoseph/activiti-examples/tree/master/stencil-samples/angular-ui-grid-stencil

The link Form Stencil Examples - Alfresco Process Services (APS) in the git is broken, but I found similar in: https://hub.alfresco.com/t5/alfresco-process-services/form-stencil-examples-alfresco-process-service.... I followed also the instructions on Form Stencils 101 and I get how Form Stencil should work.

I'm looking for a solution to show multiple rows from a table (data model/Database) into a grid, preferably with filter (SELECT-FROM-WHERE), preferably with ability to decide which column is enabled/disabled-readonly etc.

Cheers,