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.
That's it, you have now your custom form renderer. The sample described in this article can be found in GitHub.
Ref: https://mswiderski.blogspot.com/2018/11/implement-your-own-form-renderer-for.html
