Page History

Table of Contents

In this tutorial, we will follow the guideline for developing a plugin to develop our Mood Rating Form Field plugin. Please also refer to the very first tutorial 如何开发一个Bean Shell Hash Variable插件 for more details steps.

1. What is the problem?

We would like to have a rating field with some smiley images which can be reuse for other form.

2. How to solve the problem?

We will develop a Form Field Element Plugin to render our mood rating field.

3. What is the input needed for your plugin?

To develop a Mood Rating Form Field plugin, we will need to provide some standard inputs for a Form Field element.

Field Id
Field Label
Validator
Readonly
Workflow Variable

4. What is the output and expected outcome of your plugin?

A form field shown selection of smiley images and its radio button.

5. Are there any resources/API that can be reused?

To develop the Mood Rating Form Field plugin, we can extends the Radio field in core product then replace its template and plugin properties options.

6. Prepare your development environment

We need to always have our Joget Workflow Source Code ready and builded by following this guideline.

The following tutorial is prepared with a Macbook Pro and the Joget Source Code is version 5.0.1. Please refer to the 如何开发插件 article for other platform commands.

Let's say our folder directory is as follows.

Code Block
- Home - joget - plugins - jw-community -5.0.1

The "plugins" directory is the folder we will create and store all our plugins and the "jw-community" directory is where the Joget Workflow Source code is stored.

Run the following command to create a maven project in "plugins" directory.

Code Block

language	bash

cd joget/plugins/
~/joget/jw-community/5.0.1/wflow-plugin-archetype/create-plugin.sh org.joget mood_rating 5.0.1

Then, the shell script will ask us to key in a version number for the plugin and ask us for a confirmation before it generates the maven project.

Code Block

language	bash

Define value for property 'version':  1.0-SNAPSHOT: : 5.0.0
[INFO] Using property: package = org.joget
Confirm properties configuration:
groupId: org.joget
artifactId: mood_rating
version: 5.0.0
package: org.joget
Y: : y

We should get a "BUILD SUCCESS" message shown in our terminal and a "mood_rating" folder created in the "plugins" folder.

Open the maven project with your favourite IDE. I will be using NetBeans.

7. Just code it!

a. Extending the abstract class of a plugin type

Create a "MoodRatingField" class under "org.joget" package. Then, extend the class with org.joget.apps.form.lib.Radio class. The org.joget.apps.form.lib.Radio class is an implementation of org.joget.apps.form.model.Element abstract class. Please refer to Form Field Element Plugin.

b. Implement all the abstract methods

As usual, we have to implement all the abstract methods. We will using AppPluginUtil.getMessage method to support i18n and using constant variable MESSAGE_PATH for message resource bundle directory.

在本教程中，我们将遵循开发插件的指导方针来开发我们的表情评分的表单字段插件，有关更多详细信息步骤，请参阅第一个教程如何开发一个Bean Shell哈希变量插件。

1.什么问题？

我们希望有一个评级领域的一些笑脸图像，可以重用的其他形式。

2.如何解决问题？

我们将开发一个表单域元素插件来呈现我们的心情评价字段。

3.你的插件需要什么输入？

为了开发情绪分级表格字段插件，我们将需要为表格字段元素提供一些标准输入。

字段ID
字段标签
验证器
只读
工作流变量

4.你的插件的输出和预期结果是什么？

显示选择笑脸图像和单选按钮的表单域。

5.是否有任何资源/ API可以重复使用？

为了开发情绪分级表格字段插件，我们可以扩展核心产品中的无线电字段，然后替换它的模板和插件属性选项。

6.准备你的开发环境

我们需要始终准备好Joget Workflow Source Code，并按照这个指导方针建立起来。

下面的教程是用Macbook Pro编写的，Joget源代码是5.0.1版本。其他平台命令请参阅如何开发插件文章。

假设我们的文件夹目录如下所示。

Code Block
- Home - joget - plugins - jw-community -5.0.1

“插件”目录是我们将创建和存储我们所有插件的文件夹，“jw-community”目录是Joget Workflow源代码的存储位置。

运行以下命令在“plugins”目录下创建一个maven项目。

Code Block

language	bash

cd joget/plugins/
~/joget/jw-community/5.0.1/wflow-plugin-archetype/create-plugin.sh org.joget mood_rating 5.0.1

然后，shell脚本会要求我们输入插件的版本号，并在生成maven项目之前要求我们确认。

Code Block

language	bash

Define value for property 'version':  1.0-SNAPSHOT: : 5.0.0
[INFO] Using property: package = org.joget
Confirm properties configuration:
groupId: org.joget
artifactId: mood_rating
version: 5.0.0
package: org.joget
Y: : y

我们应该在终端上显示“BUILD SUCCESS”消息，在“plugins”文件夹中创建一个“mood_rating”文件夹。

用你最喜欢的IDE打开maven项目。我将使用 NetBeans。

7. Just code it!

a. 扩展插件类型的抽象类

在“org.joget”包下创建一个“MoodRatingField”类。然后，使用org.joget.apps.form.lib.Radio 类扩展该类。该 org.joget.apps.form.lib.Radio 类是一个实现 org.joget.apps.form.model.Element 抽象类。请参阅表单域元素插件。

b. 实现所有的抽象方法

像往常一样，我们必须执行所有的抽象方法。我们将使用AppPluginUtil.getMessage方法来支持i18n，并使用常量变量MESSAGE_PATH作为消息资源包目录。

Code Block

language	java
title	Implementation of all basic abstract methods
collapse	true

package org.joget;
 
import java.util.Map;
import org.joget.apps.app.service.AppPluginUtil;
import org.joget.apps.app.service.AppUtil;
import org.joget.apps.form.lib.Radio;
import org.joget.apps.form.model.FormBuilderPalette;
 
public class MoodRatingField extends Radio {
    
    private final static String MESSAGE_PATH = "message/form/MoodRatingField";
    
    @Override
    public String getName() {
        return "Mood Rating";
    }

    @Override
    public String getVersion() {
        return "5.0.0";
    }
    
    @Override
    public String getClassName() {
        return getClass().getName();
    }
    
    @Override
    public String getFormBuilderCategory() {
        return FormBuilderPalette.CATEGORY_CUSTOM;
    }
    
    @Override
    public String getLabel() {
        //support i18n
        return AppPluginUtil.getMessage("org.joget.MoodRatingField.pluginLabel", getClassName(), MESSAGE_PATH);
    }
 
    @Override
    public String getDescription() {
        //support i18n
        return AppPluginUtil.getMessage("org.joget.MoodRatingField.pluginDesc", getClassName(), MESSAGE_PATH);
    }

Code Block

language	java
title	Implementation of all basic abstract methods
collapse	true

package org.joget;
 
import java.util.Map;
import org.joget.apps.app.service.AppPluginUtil;
import org.joget.apps.app.service.AppUtil;
import org.joget.apps.form.lib.Radio;
import org.joget.apps.form.model.FormBuilderPalette;
 
public class MoodRatingField extends Radio {
    
    private final static String MESSAGE_PATH = "message/form/MoodRatingField";
    
    @Override
    public String getNamegetPropertyOptions() {
        return "Mood Rating";
    }

    @Override
    public String getVersion() {
        return "5.0.0"AppUtil.readPluginResource(getClass().getName(), "/properties/form/moodRatingField.json", null, true, MESSAGE_PATH);
    }
    
    @Override
    public String getClassNamegetFormBuilderTemplate() {
        return getClass().getName()"<label class='label'>"+getLabel()+"</label>";
    }
}

现在，我们必须为管理员用户创建一个UI，为我们的插件提供输入。在getPropertyOptions方法中，我们已经指定了我们的插件属性选项和配置定义文件位于“/properties/form/moodRatingField.json”。让我们在“mood_rating / src / main”目录下创建一个目录“resources / properties / form”。创建目录后，在“properties”文件夹中创建一个名为“moodRatingField.json”的文件。

在属性定义选项文件中，我们需要提供如下的选项。请注意，我们可以在我们的属性选项中使用“@@ message.key @@”语法来支持i18n。

Code Block

language	js

[{
    
title    @Override: '@@form.moodRating.config@@',
    publicproperties String getFormBuilderCategory() : [{
        name return FormBuilderPalette.CATEGORY_CUSTOM;: 'id',
    }
    
label    @Override: '@@form.radio.id@@',
    public String getLabel() {
 type       //support i18n: 'textfield',
        return AppPluginUtil.getMessage("org.joget.MoodRatingField.pluginLabel", getClassName(), MESSAGE_PATH);
    }
 
required : 'True',
      @Override
  regex_validation  public String getDescription() {
: '^[a-zA-Z0-9_]+$',
        validation_message : '@@form.radio.invalidId@@'
    },
    {
        name //support i18n: 'label',
        return AppPluginUtil.getMessage("org.joget.MoodRatingField.pluginDesc", getClassName(), MESSAGE_PATH);
label : '@@form.radio.label@@',
      }
  type : 'textfield',
    @Override
    publicvalue String getPropertyOptions() {: '@@org.joget.MoodRatingField.pluginLabel@@'
      }]
},
{
  return AppUtil.readPluginResource(getClass().getName(), "/properties/form/moodRatingField.json", null, true, MESSAGE_PATH); title : '@@form.radio.advancedOptions@@',
    }
properties : [{
  
    @Override
  label  public String getFormBuilderTemplate() {: '@@form.radio.data@@',
        returntype "<label: class='label'>"+getLabel()+"</label>";header'
    }
}

Now, we have to create a UI for admin user to provide inputs for our plugin. In getPropertyOptions method, we already specify our 插件属性选项与配置 definition file is located at "/properties/form/moodRatingField.json". Let us create a directory "resources/properties/form" under "mood_rating/src/main" directory. After creating the directory, create a file named "moodRatingField.json" in the "properties" folder.

In the properties definition options file, we will need to provide options as below. Please note that we can use "@@message.key@@" syntax to support i18n in our properties options.

Code Block

language	js

[{
    title : '@@form.moodRating.config@@',
    properties : [,
    {
        name : 'validator',
        label : '@@form.radio.validator@@',
        type : 'elementselect',
        options_ajax : '[CONTEXT_PATH]/web/property/json/getElements?classname=org.joget.apps.form.model.FormValidator',
        url : '[CONTEXT_PATH]/web/property/json[APP_PATH]/getPropertyOptions'
    },
    {
        namelabel : 'id@@form.radio.ui@@',
        labeltype : '@@form.radio.id@@',header'
    },
    {
        typename : 'textfieldreadonly',
        requiredlabel : 'True@@form.radio.readonly@@',
        regex_validationtype : '^[a-zA-Z0-9_]+$checkbox',
        validation_messagevalue : '@@form.radio.invalidId@@'
False',
     },
   options : [{
            namevalue : 'labeltrue',
            label : '@@form.radio.label@@',
        }]
  type : 'textfield',},
    {
        valuelabel : '@@org@@form.jogetradio.MoodRatingField.pluginLabel@@workflow@@',
    }]
},
{
    titletype : '@@form.radio.advancedOptions@@',
header'
    },
    {
        propertiesname : [{'workflowVariable',
        label : '@@form.radio.data@@workflowVariable@@',
        type : 'headertextfield'
    },
]
}]

完成属性选项以收集输入后，我们可以处理插件的主要方法，这些方法是renderTemplate和formatData方法。由于我们扩展了Radio类，所以我们不需要实现formatData方法。

Code Block

language	java

    {@Override
    public String renderTemplate(FormData formData, nameMap : 'validator',
dataModel) {
        String labeltemplate := '@@form.radio.validator@@',"moodRatingField.ftl";
        
        type// : 'elementselect',set value
        options_ajaxString : '[CONTEXT_PATH]/web/property/json/getElements?classname=org.joget.apps.form.model.FormValidator',value = FormUtil.getElementPropertyValue(this, formData);
        dataModel.put("value", value);
        urlString : '[CONTEXT_PATH]/web/property/json[APP_PATH]/getPropertyOptions'
    },
    {html = FormUtil.generateElementHtml(this, formData, template, dataModel);
        label : '@@form.radio.ui@@',return html;
    }

在renderTemplate中，我们将模板文件指定为“moodRatingField.ftl”。在“mood_rating / src / main / resources / templates”目录下创建这个文件。然后，使用 FreeMaker 语法来构建我们的模板，如下所示：

Code Block

language	xml

<div class="form-cell mood_rating" ${elementMetaData!}>    type : 'header'
    },
    {
        name : 'readonly',<label class="label">${element.properties.label} <span class="form-cell-validator">${decoration}</span><#if error??> <span class="form-error-message">${error}</span></#if></label>
        label : '@@form.radio.readonly@@',<div class="form-cell-value" id="${elementParamName!}${element.properties.elementUniqueKey!}">
    <#if !(request.getAttribute("org.joget.MoodRatingField")??) >
        type<style>
 : 'checkbox',
           value : 'False',
  .mood_rating .tdstyle {text-align:center;width:20%;border:0px none transparent !important;}
      options : [{</style>
    </#if>    
    value<table : 'true',style="width:150px">
            label : ''<tbody>
        }]
    },<tr>
    {
        label : '@@form.radio.workflow@@',
   <td class="tdstyle"><img height="25"   type : 'header'
    },width="25" src="${request.contextPath}/plugin/org.joget.MoodRatingField/images/smiley5.png"></td>
    {
        name : 'workflowVariable',
  <td class="tdstyle"><img height="25" width="25" src="${request.contextPath}/plugin/org.joget.MoodRatingField/images/smiley4.png"></td>
  label : '@@form.radio.workflowVariable@@',
        type : 'textfield'
  <td  }]
}]

After completing the properties option to collect input, we can work on the main methods of the plugin which are renderTemplate and formatData method. Since we extends Radio class, we do not need to implement formatData method.

Code Block

language	java

    @Overrideclass="tdstyle"><img height="25" width="25" src="${request.contextPath}/plugin/org.joget.MoodRatingField/images/smiley3.png"></td>
    public String renderTemplate(FormData formData, Map dataModel) {
        String template = "moodRatingField.ftl";
        
 <td class="tdstyle"><img height="25" width="25" src="${request.contextPath}/plugin/org.joget.MoodRatingField/images/smiley2.png"></td>
       // set value
        String value = FormUtil.getElementPropertyValue(this, formData);
<td class="tdstyle"><img height="25" width="25" src="${request.contextPath}/plugin/org.joget.MoodRatingField/images/smiley1.png"></td>
           dataModel.put("value", value); </tr>
        String html = FormUtil.generateElementHtml(this, formData, template, dataModel);
 <tr>
            return html;
    }

In the renderTemplate, we specify the template file to "moodRatingField.ftl". Let create this file under "mood_rating/src/main/resources/templates" directory. Then, using FreeMaker syntax to construct our template as below:

Code Block

language	xml

<div class="form-cell mood_rating" ${elementMetaData!}><#list ['5', '4', '3', '2', '1'] as i>
    <label class="label">${element.properties.label} <span class="form-cell-validator">${decoration}</span><#if error??> <span              <td class="form-error-message">${error}</span></#if></label>
tdstyle">
     <div class="form-cell-value                   <input grouping="${elementParamName!}" id="${elementParamName!}" name="${element.properties.elementUniqueKeyelementParamName!}">
    <#if !(request.getAttribute("org.joget.MoodRatingField")??) type="radio" value="${i}" <#if error??>class="form-error-cell"</#if> <#if element.properties.readonly! == 'true'> disabled</#if> <#if value?? && value == i>checked</#if> />
        <style>
            .mood_rating .tdstyle {text-align:center;width:20%;border:0px none transparent !important;}
</td>
                </style>#list>
    </#if>    
    <table style="width:150px"></tr>
        <tbody>
            <tr>
                <td class="tdstyle"><img height="25" width="25" src="${request.contextPath}/plugin/org.joget.MoodRatingField/images/smiley5.png"></td>
                <td class="tdstyle"><img height="25" width="25" src="${request.contextPath}/plugin/org.joget.MoodRatingField/images/smiley4.png"></td>
                <td class="tdstyle"><img height="25" width="25" src="${request.contextPath}/plugin/org.joget.MoodRatingField/images/smiley3.png"></td>
                <td class="tdstyle"><img height="25" width="25" src="${request.contextPath}/plugin/org.joget.MoodRatingField/images/smiley2.png"></td>
                <td class="tdstyle"><img height="25" width="25" src="${request.contextPath}/plugin/org.joget.MoodRatingField/images/smiley1.png"></td>
            </tr>
            <tr>
                <#list ['5', '4', '3', '2', '1'] as i>
                    <td class="tdstyle">
                        <input grouping="${elementParamName!}" id="${elementParamName!}" name="${elementParamName!}" type="radio" value="${i}" <#if error??>class="form-error-cell"</#if> <#if element.properties.readonly! == 'true'> disabled</#if> <#if value?? && value == i>checked</#if> />
                    </td>
                </#list>
            </tr>
        </tbody>
    </table>
    </div>
    <div style="clear:both;"></div>
</div>

There are some smiley image files will be used by the template, let put those image files under "mood_rating/src/main/resources/resources/image" directory.

c. Manage the dependency libraries of your plugin

There are no additional library needed.

d. Make your plugin internationalization (i18n) ready

We are using i18n message key in getLabel and getDescription method. We will use i18n message key in our properties options definition as well. Then, we will need to create a message resource bundle properties file for our plugin.

</tbody>
    </table>
    </div>
    <div style="clear:both;"></div>
</div>

有一些笑脸图像文件将被模板使用，让这些图像文件放在“mood_rating / src / main / resources / resources / image”目录下

c. 管理你的插件的依赖库

没有额外的库需要。

d. 让你的插件国际化（国际化）准备就绪

我们在getLabel和getDescription方法中使用i18n消息密钥。我们将在我们的属性选项定义中使用i18n消息密钥。然后，我们将需要为我们的插件创建一个消息资源包属性文件。

在“mood_rating / src / main”目录下创建一个目录“resources / message / form”。然后，在该文件夹中创建一个“MoodRatingField.properties”文件。在属性文件中，添加所有消息密钥及其标签，如下所示。Create a directory, "resources/message/form", under "mood_rating/src/main" directory. Then, create a "MoodRatingField.properties" file in the folder. In the properties file, add all the message keys and its label as below.

Code Block
org.joget.MoodRatingField.pluginLabel=Mood Rating org.joget.MoodRatingField.pluginDesc=Form Field for rating mood form.moodRating.config=Edit Mood Rating

e.

...

注册你的插件到Felix框架

接下来，我们将需要在Activator类（在同一个类包中自动生成）中注册我们的插件类，以告诉Felix框架这是一个插件。Next, we will have to register our plugin class in the Activator class (Auto generated in the same class package) to tell the Felix Framework that this is a plugin.

Code Block

language	java

    public void start(BundleContext context) {
        registrationList = new ArrayList<ServiceRegistration>();
        //Register plugin here
        registrationList.add(context.registerService(MoodRatingField.class.getName(), new MoodRatingField(), null));
    }

f

...

. 建立它并测试

让我们建立我们的插件。构建过程完成后，我们将在“mood_rating / target”目录下找到创建的“mood_rating-5.0.0.jar”文件。

然后，让我们上传插件jar到管理插件。上传jar文件后，再次检查插件是否正确上传并激活。

Image Added

然后，检查表单生成器中显示的情绪等级字段。

Image Added

将其拖到“窗体生成器画布”并设置其属性。

Image Added Image Added

保存属性并检查字段是否在画布中呈现，如下所示。

Image Added

检查并测试表单中的字段。

Image Added

8. 再进一步，分享或出售

你可以从

Let's build our plugin. Once the building process is done, we will find a "mood_rating-5.0.0.jar" file created under "mood_rating/target" directory.

Then, let's upload the plugin jar to Manage Plugins. After uploading the jar file, double check that the plugin is uploaded and activated correctly.

Image Removed

Then, check the Mood Rating field is shown in the Form Builder.

Image Removed

Drag it to the Form Builder Canvas and set its properties.

Image Removed Image Removed

Save the properties and check the field is render in canvas as following.

Image Removed

Check and test the field in form.

Image Removed

8. Take a step further, share it or sell it

You can download the source code from mood_rating_src.zip.下载源代码。

要下载现成的插件jar，请在To download the ready-to-use plugin jar, please find it in http://marketplace.joget.org/. (Coming Soon)上找到它。（快来了）

Page tree

Versions Compared

Old Version 1

New Version Current

Key

1. What is the problem?

2. How to solve the problem?

3. What is the input needed for your plugin?

4. What is the output and expected outcome of your plugin?

5. Are there any resources/API that can be reused?

6. Prepare your development environment

7. Just code it!

a. Extending the abstract class of a plugin type

b. Implement all the abstract methods

1.什么问题？

2.如何解决问题？

3.你的插件需要什么输入？

4.你的插件的输出和预期结果是什么？

5.是否有任何资源/ API可以重复使用？

6.准备你的开发环境

7. Just code it!

a. 扩展插件类型的抽象类

b. 实现所有的抽象方法

c. Manage the dependency libraries of your plugin

d. Make your plugin internationalization (i18n) ready

c. 管理你的插件的依赖库

d. 让你的插件国际化（国际化）准备就绪

e.

注册你的插件到Felix框架

f

. 建立它并测试

8. 再进一步，分享或出售

8. Take a step further, share it or sell it