2018/11/16

Implement your own form renderer for KIE Server

As it was described in this article, KIE Server now provides form renderers for process and task forms built in jBPM Console (aka workbench). Out of the box there are two renderers provided

  • based on PatterFly to provide same look and feel as entire jBPM tooling - it's the default renderer
  • based on Bootstrap to provide a simple alternative that utilises well established framework for building web and mobile UIs
This obviously won't cover all possible needs of users and thus the renderers are actually pluggable. In this article we build a custom one from scratch to illustrate what it takes to have your own.

Create project with dependencies

First of all, a new maven project needs to be created. It should be most basic project with packaging jar. Then let's add required dependencies to pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.kie.server.samples</groupId>
  <artifactId>custom-form-renderer</artifactId>
  <version>1.0.0</version>
  <name>Custom Form Renderer</name>
  
  <properties>
    <version.org.kie>7.14.0.Final</version.org.kie>
  </properties>
  
  <dependencies>
    <dependency>
      <groupId>org.kie.server</groupId>
      <artifactId>kie-server-services-jbpm-ui</artifactId>
      <version>${version.org.kie}</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>
</project>

Create configuration folders

Create folders in the project that will configure the renderer - all should be done src/main/resources
  • form-templates-providers - folder that will contain templates, css and java script files used to render the form
  • META-INF/services/org.kie.server.services.jbpm.ui.form.render.FormRenderer - an empty file that will be used as discovery mechanism to find and register the renderer - it will be edited a bit later to provide actual implementation details

Create form renderer implementation

In src/main/java create a class (e.g. org.kie.server.samples.CustomFormRenderer) that will extend org.kie.server.services.jbpm.ui.form.render.AbstractFormRenderer and implement the required methods 
  • getName - provide the name of the template that shall be used as reference when rendering
  • loadTemplates - main implementation that loads different types of templates to be used by renderer
  • default constructor
IMPORTANT: this new class must be configured as the implementation of the renderer so add its fully qualified class name into 
META-INF/services/org.kie.server.services.jbpm.ui.form.render.FormRenderer

There are several types of templates that renderer must provide (and load on startup)
  • master - main template that builds the HTML page
  • header - header template that creates header of the form
  • form-group - form input fields template
  • case-layout - layout for case forms
  • process-layout - layout for process forms
  • task-layout - layout for user task forms
  • table - table to be build for multi subforms
The easiest way is to base your customisation on top of the out of the box templates (either patternfly or bootstrap). In this example I will use bootstrap templates that can be found here.

Copy all resources from the linked directory into 
src/main/resources/form-templates-providers/custom

and then implement the loadTemplates method of the CustomFormRenderer class
package org.kie.server.samples;

import org.kie.server.services.jbpm.ui.form.render.AbstractFormRenderer;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;


public class CustomFormRenderer extends AbstractFormRenderer {
    
    private static final Logger logger = LoggerFactory.getLogger(CustomFormRenderer.class);

    public CustomFormRenderer() {
        super(null,  null);
    }
    
    public CustomFormRenderer(String serverPath, String resources) {
        super(serverPath, resources);
    }
    
    public String getName() {
        return "custom";
    }

    @Override
    protected void loadTemplates() {
        loadTemplate(MASTER_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/master-template.html"));
        loadTemplate(PROCESS_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/process-layout-template.html"));
        loadTemplate(TASK_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/task-layout-template.html"));
        loadTemplate(FORM_GROUP_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/input-form-group-template.html"));
        loadTemplate(HEADER_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/header-template.html"));
        loadTemplate(CASE_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/case-layout-template.html"));
        loadTemplate(TABLE_LAYOUT_TEMPLATE, this.getClass().getResourceAsStream("/form-templates-providers/custom/table-template.html"));
        
        logger.info("Custom Form renderer templates loaded successfully.");
    }

}

Customise your templates

Since the templates where copied from another renderer we need to customise it, let's start with master template. Open it and replace ${serverPath}/bootstrap with ${serverPath}/custom  
This will ensure that our customised files will be loaded.

Make any additional changes to the master template as needed. I will just add custom text next to header.

Master template is the place where you can add additional scripts or stylesheets. There is main js file called kieserver-ui.js that provide all the logic required to manage and submit forms. It also includes validation, so in case you need extensions to that logic consider to create new file with your changes and replace the location of it to point to your new file.

Make additional customisation to other templates as needed.

Build and deploy renderer to KIE Server

Implementation is completed so now it's time to build the project and deploy to KIE Server.
  • Build the project with maven - mvn clean package
  • Deploy the project to KIE Server by coping the jar file to kie-server.war/WEB-INF/lib
Start the server and take advantage of your custom renderer by using following URL that works for one of the sample projects - Evaluation (make sure to deploy it before using the renderer).

http://localhost:8080/kie-server/services/rest/server/containers/evaluation/forms/processes/evaluation/content?renderer=custom

http://localhost:8080/kie-server/services/rest/server/containers/evaluation/forms/tasks/1/content?renderer=custom

As you can see new renderer is fully operational and customised to your needs.

That's it, you have now your custom form renderer. The sample described in this article can be found in GitHub.

10 comments:

  1. Hi, is it possible to send some data to the bpm process from this routes? For example, route get event from some PIID, do some work, send data to the PIID for resuming process flow?

    ReplyDelete
    Replies
    1. Herbal Penis Enlargement product is 100% guarantee to Enlarge and get a better ERECTION ,
      the reason why most people are finding it difficult
      to enlarge Penis is because they bedlieve on medical
      report, drugs and medical treatment which is not
      helpful for Penis Enlargement . Natural roots/herbs are the best remedy which can easily Enlarge your Penis permanently 
      Contact Dr Olu via Email : Drolusolutionhome@gmail.com or via WhatsApp : +2348140654426 for Natural root and herbal remedies put together to help you get Enlarge and Erect healthy. 
      Thank you. 



































      Herbal Penis Enlargement product is 100% guarantee to Enlarge and get a better ERECTION ,
      the reason why most people are finding it difficult
      to enlarge Penis is because they bedlieve on medical
      report, drugs and medical treatment which is not
      helpful for Penis Enlargement . Natural roots/herbs are the best remedy which can easily Enlarge your Penis permanently 
      Contact Dr Olu via Email : Drolusolutionhome@gmail.com or via WhatsApp : +2348140654426 for Natural root and herbal remedies put together to help you get Enlarge and Erect healthy. 
      Thank you. 

      Delete
    2. hello everyone Have you heard of this man, a spell caster and a herbal doctor ? DR HARRY what a great man, black magic really work, well I know this man must be giving a great regards due to what he have done in my life,Am from UK, I travel to Texas  for business I have to spend 2 months over there during to the business I meet this girl what a petty girl well she draw my attentions I was interest on her I decide to speak to her, how I felt for her, and I was having it in mind that I should propose to her, I spend time with this girl, and will were in love very tight, and will had sex together, all I was thinking about is how to introduce her to my parent before I propose to her because I really love her when it was time for me to go back to my country, but due to business my time do not permit me I have to go back fast, but all was already done, and she were to come after 2 weeks  to visit me so that I can introduce her to my parent when I was back my doctor decide to do his duty work and test me and give me some treatment but he found out that I have HIV, it was so surprised to me that she have HIV and she refused to tell me about it, and she allow me to have sex with her without condom, but I feel like crying I decide to behave like a man, all I think about is I will not be about to have children anymore then due to that I was force to look for help, I believe there is no cure in HIV, but I decide to try magic if it can work for me. I search for magic power men then I found a man called DR.HARRY  how it cured HIV within 7 days spell, well I did not conclude immediately because of who I Am I thinks this can work and it cannot also work, I give a try this man go according to the post I see, and his spell work within 3 weeks  I was cured totally, with the little I have i have to send a car to this man because of his good work but only God can tell who this man his, let me stop from here because I know there are many people who need his help that is why I have to write about him, He can cure all kinds sickness or illness and cast any spell likePENIS ENLARGEMENT PREMATURE EJACULATION LOW SPERM COUNT ERECTILE DYSFUNCTION HIV/AIDS HERPES ALS CANCER DIABETES GET YOUR EX LOVER BACK SPELL MONEY SPELL LOTTERY SPELL BREAKING CURSE SPELL PROTECTION FROM WITCH CRAFT SPIRITUAL ATTACK SPELL WIN COURT CASE SPELL  etc email him drharrysolution@gmail.com   visit His website  https://drharryherbaltempl.wixsite.com/solutiontemple or call.....whatsapp +2349036417079

      Delete
  2. Here is the wealth of one of a kind vocations and effortlessly accessible, and the other excellent young ladies here that influence your mind to charm with exceptionally whimsical. These Doha Escorts are mystical sets of faultless magnificence with whom you can likewise appreciate a wonderful affair.

    ReplyDelete
  3. Maciej,

    Thank you for the article - that's what I looked for. :) We are evaluating the possible use of jBPM and the tuning end user UI is one of unsolved [yet] problems.

    The question: I successfully build and install your demo custom renderer and I see the modified process and user forms when I invoke them directly via browser URL (as in your article). But if I start the process via KIE Workbench or start task via KIE Workbench, the original form renderer is used, not the custom one. What should be done to use custom renderer from Workbench?

    Thanks,
    Yuriy

    ReplyDelete
  4. Dear Maciej,

    Thanks for this amazing Article.

    Can you please suggest me the property to be added to change from default to bootstrap in jbpm workbench.

    In URL I know I can do it.

    Please advise.

    Thanks and Regards,
    Abhay

    ReplyDelete
  5. Hola Maciej

    Es posible cambiar el renderizador por defecto que usa Business Central (workbench)? sin usar los endpoints

    Es posible crear botones en los formularios creados en BusinessCentral con los que hacer funciones on-click?

    Es posible crear formularios en aplicaciones de terceros e incrustarlos en mi proyecto de jBPM? (como si fuesen los task-forms, que puedan interactuar con el proceso y con las variables de proceso)?

    Es posible que en las ListBox o RadioGroup usar imagenes en lugar de Strings para mostrar las diferentes opciones, por ejmeplo seleccionar entre marcas de coches, en lugar de Renault, Seat, BMW... se muestren sus logotipos?

    Muchas gracias

    Carlos

    ReplyDelete
  6. Hello Maciej

    Is it possible to change the default renderer used by Business Central (workbench)? without using the endpoints

    Is it possible to create buttons in the forms created in BusinessCentral with the functions to click on?

    Is it possible to create forms in third-party applications and embed them in my jBPM project? (as if they were the task forms, which can interact with the process and process variables)?

    It is possible that in the List or Radio Group box use images instead of Strings to show the different options, for example, to select between car brands, instead of Renault, Seat, BMW ... Are their logos displayed?

    thank you

    Carlos

    ReplyDelete

  7. الرائد افضل شركات تنظيف خزانات المياه يسعدنا ان نقدم لكم افضل خدمات
    شركة غسيل خزانات بالمدينة المنورة تنظيف خزانات بالمدينة المنورة
    افضل شركة تنظيف منازل بالمدينة المنورة شركة تنظيف بيوت بالمدينة المنورة

    ReplyDelete
  8. hello everyone Have you heard of this man, a spell caster and a herbal doctor ? DR HARRY what a great man, black magic really work, well I know this man must be giving a great regards due to what he have done in my life,Am from UK, I travel to Texas  for business I have to spend 2 months over there during to the business I meet this girl what a petty girl well she draw my attentions I was interest on her I decide to speak to her, how I felt for her, and I was having it in mind that I should propose to her, I spend time with this girl, and will were in love very tight, and will had sex together, all I was thinking about is how to introduce her to my parent before I propose to her because I really love her when it was time for me to go back to my country, but due to business my time do not permit me I have to go back fast, but all was already done, and she were to come after 2 weeks  to visit me so that I can introduce her to my parent when I was back my doctor decide to do his duty work and test me and give me some treatment but he found out that I have HIV, it was so surprised to me that she have HIV and she refused to tell me about it, and she allow me to have sex with her without condom, but I feel like crying I decide to behave like a man, all I think about is I will not be about to have children anymore then due to that I was force to look for help, I believe there is no cure in HIV, but I decide to try magic if it can work for me. I search for magic power men then I found a man called DR.HARRY  how it cured HIV within 7 days spell, well I did not conclude immediately because of who I Am I thinks this can work and it cannot also work, I give a try this man go according to the post I see, and his spell work within 3 weeks  I was cured totally, with the little I have i have to send a car to this man because of his good work but only God can tell who this man his, let me stop from here because I know there are many people who need his help that is why I have to write about him, He can cure all kinds sickness or illness and cast any spell likePENIS ENLARGEMENT PREMATURE EJACULATION LOW SPERM COUNT ERECTILE DYSFUNCTION HIV/AIDS HERPES ALS CANCER DIABETES GET YOUR EX LOVER BACK SPELL MONEY SPELL LOTTERY SPELL BREAKING CURSE SPELL PROTECTION FROM WITCH CRAFT SPIRITUAL ATTACK SPELL WIN COURT CASE SPELL  etc email him drharrysolution@gmail.com   visit His website  https://drharryherbaltempl.wixsite.com/solutiontemple or call.....whatsapp +2349036417079

    ReplyDelete