แนวทางสำหรับการพัฒนาปลั๊กอิน

มีคำถามและขั้นตอนต่อไปนี้เพื่อช่วยคุณวางแผนและพัฒนาปลั๊กอินเพื่อตอบสนองความต้องการที่กำหนดเอง

1. ปัญหาคืออะไร?

คุณมีข้อกำหนดที่กำหนดเองและคุณพบว่าไม่มีปลั๊กอินใดใน Joget Workflow หรือปลั๊กอินที่มีอยู่ใน Marketplace สามารถตอบสนองความต้องการของคุณได้

ตัวอย่างที่ 1: ดาวน์โหลดแบบฟอร์ม PDF เมื่อคลิกที่ปุ่มในรายการ

ตัวอย่างที่ 2: ระบุมุมมองแผนภูมิ Gantt ของข้อมูลฟอร์มที่คุณรวบรวม

ตัวอย่างที่ 3: ตัวแปร Hash variable สามารถใช้งานได้สะดวก แต่ไม่สามารถตรวจสอบได้

2. วิธีการแก้ไขปัญหา?

อ้างอิงถึง Plugin Types ที่สนับสนุนโดย Joget Workflow ค้นหาประเภทปลั๊กอินที่เหมาะสมที่สุดที่สามารถช่วยให้คุณปฏิบัติตามข้อกำหนดที่กำหนดเองได้

ตัวอย่างที่ 1: พัฒนาปลั๊กอินการกระทำดาต้าลิสต์เพื่อแสดงปุ่มสำหรับสร้างแบบฟอร์ม PDF

ตัวอย่างที่ 2: พัฒนาปลั๊กอินเมนู Userview ที่สามารถใช้เพื่อแสดงข้อมูลฟอร์มเป็นแผนภูมิ Gantt

ตัวอย่างที่ 3: พัฒนาปลั๊กอิน Hash Variable ที่สามารถเขียนสคริปต์ Bean Shell ได้

3. การป้อนข้อมูลที่จำเป็นสำหรับปลั๊กอินของคุณคืออะไร?

ค้นหาข้อมูลที่ปลั๊กอินของคุณต้องการเพื่อใช้งาน / ทำงาน ดูจากมุมมองของผู้ใช้ คุณจะใช้ปลั๊กอินอย่างไร จากนั้นดูจากมุมมองของนักพัฒนา เพื่อทำให้ปลั๊กอินสามารถใช้ซ้ำได้ในกรณีใช้งานมากขึ้น

คุณสามารถอ้างอิงถึง ตัวเลือกคุณสมบัติปลั๊กอิน ในประเภทของฟิลด์อินพุตที่คุณสามารถให้กับผู้ใช้ปลั๊กอินของคุณ

ตัวอย่างที่ 1: ในการพัฒนาปลั๊กอินการดาวน์โหลดดาต้าลิสต์แอ็คชั่น PDF เราสามารถพิจารณานำเสนอสิ่งต่อไปนี้เป็นอินพุต

1. รหัสแบบฟอร์ม: แบบฟอร์มที่จะใช้ในการสร้างไฟล์ PDF
2. ID เรคคอร์ด: ใช้ id ของแถวดาต้าลิสต์หรือค่าคอลัมน์เพื่อโหลดเรคคอร์ด
3. ชื่อไฟล์: ชื่อไฟล์ของไฟล์ PDF ที่สร้างขึ้น
4. ตัวเลือกการจัดรูปแบบ: ตัวเลือกในการจัดรูปแบบและปรับแต่งเอาต์พุต PDF

ตัวอย่างที่ 2: ในการพัฒนาปลั๊กอินเมนู Gantt Chat Userview เราสามารถพิจารณาให้สิ่งต่อไปนี้เป็นอินพุต

1. เครื่องผูกดาต้าลิสต์: เราสามารถใช้เครื่องผูกดาต้าลิสต์ในปลั๊กอินของเราเพื่อดึงข้อมูลที่ต้องการโดยแผนภูมิแกนต์
2. การแมป: ฟิลด์เพื่อแมปคอลัมน์ที่จะส่งคืนจากตัวยึดข้อมูลไปยังข้อมูลที่ต้องการโดยแผนภูมิแกนต์
3. จัดแต่งทรงผม: ตัวเลือกเพื่อจัดสไตล์แผนภูมิแกนต์

ตัวอย่างที่ 3 : ปลั๊กอิน Hash Variable ไม่มีส่วนต่อประสานสำหรับผู้ใช้ในการกำหนดค่า แต่เพื่อพัฒนาปลั๊กอิน Bean Shell Hash Variable เราต้องการที่อื่นเพื่อใส่สคริปต์ Bean Shell ของเรา เราสามารถนำตัวแปรสภาพแวดล้อมมาใช้ใหม่เพื่อจัดเก็บสคริปต์ของเรา ดังนั้นไวยากรณ์ Hash Variable จะเป็นคำนำหน้าด้วยคีย์ตัวแปรสภาพแวดล้อม

เช่น # beanshell.EnvironmentVariableKey #

แต่นี่อาจไม่เพียงพอ เราอาจต้องการวิธีอื่นในการส่งผ่านตัวแปรบางตัวเช่นกัน เราสามารถพิจารณาการใช้ไวยากรณ์พารามิเตอร์การสืบค้น URL เพื่อส่งผ่านตัวแปรของเราเพราะง่ายต่อการแยกวิเคราะห์ในภายหลัง

เช่น # beanshell.EnvironmentVariableKey [name=Joget&email=info@joget.org&message= {form.sample.message? url}] #

4. ผลลัพธ์และผลลัพธ์ที่คาดหวังของปลั๊กอินของคุณคืออะไร?

อย่างไรและผู้ใช้ปกติ (ไม่ใช่ผู้ใช้ผู้ดูแลระบบที่ใช้ปลั๊กอินเพื่อให้การทำงาน) จะใช้และดูผลลัพธ์ปลั๊กอินของคุณ

ตัวอย่างที่ 1 : เมื่อใช้ PDF Download การกระทำดาต้าลิสต์เป็นการกระทำของแถวดาต้าลิสต์หรือการกระทำคอลัมน์ผู้ใช้ปกติจะเห็นลิงค์เพื่อดาวน์โหลดไฟล์ PDF ในทุก ๆ แถวของดาต้าลิสต์ เมื่อคลิกที่ลิงค์จะมีการแจ้งให้ดาวน์โหลดไฟล์ PDF

เมื่อมีการใช้ปลั๊กอินเป็นการกระทำของดาต้าลิสต์ทั้งหมดไฟล์ซิปที่มีไฟล์ PDF ที่สร้างขึ้นทั้งหมดของทุกแถวที่เลือกจะได้รับแจ้งให้ดาวน์โหลด

ตัวอย่างที่ 2 : ผู้ใช้ทั่วไปสามารถเห็นแผนภูมิ Gantt เมื่อมีการคลิกเมนูโดยใช้ปลั๊กอินเมนู Userview เมนู Gantt แผนภูมิ ผู้ใช้สามารถนำทางหรือโต้ตอบกับแผนภูมิแกนต์

ตัวอย่างที่ 3 : ปลั๊กอิน Bean Shell Hash สำหรับผู้ดูแลระบบ เมื่อมีการใช้งาน Hash Variable จะถูกแทนที่ด้วยเอาต์พุตส่งคืนจากล่าม Bean Shell

5. มีทรัพยากร / API ใด ๆ ที่สามารถนำกลับมาใช้ใหม่ได้หรือไม่?

โปรดอ้างอิงปลั๊กอินและบทช่วยสอนที่มีอยู่เสมอเพื่อค้นหา ประเภทปลั๊กอิน / ปลั๊กอินที่คล้ายกันที่คุณสามารถอ้างถึงเมื่อใดก็ตามที่เป็นไปได้ ทีม Joget จะพยายามอย่างดีที่สุดเพื่อเพิ่มเนื้อหาในส่วนบทช่วยสอน

คุณอาจต้องตรวจสอบเอกสารของ Utility & Service Method , JSON API , Javascript APIและ คู่มือการเขียนโปรแกรม Bean Shellด้วย เอกสารเหล่านี้อาจมีวิธีการ / ตัวอย่างที่อาจช่วยคุณในการพัฒนา

ตัวอย่างที่ 1 : เพื่อพัฒนาปลั๊กอินการดาวน์โหลดดาต้าลิสต์แอ็คชัน PDF เราสามารถนำวิธีการใน FormPdfUtil มาใช้ใหม่ เพื่อสร้างฟอร์มเป็น PDF นอกจากนี้เรายังสามารถอ้างถึงซอร์สโค้ดของปลั๊กอินการกระทำการลบแบบฟอร์มข้อมูลดาต้าลิสต์ได้เช่นกัน นอกเหนือจากนั้นเราสามารถอ้างถึงเครื่องมือส่งออกอีเมลฟอร์ม ในตัวเลือกคุณสมบัติปลั๊กอินที่เราสามารถให้ในปลั๊กอินเนื่องจากเครื่องมือส่งออกฟอร์มอีเมลใช้วิธีการใน FormPdfUtil เช่นกัน

ตัวอย่างที่ 2 : ในการพัฒนาปลั๊กอินเมนู Userview เมนู Gantt เราสามารถอ้างถึงซอร์สโค้ดของปลั๊กอินเมนู Userview ทั้งหมด จากตรงนั้นเราสามารถทำความเข้าใจเกี่ยวกับวิธีสร้างเทมเพลตสำหรับปลั๊กอินโดยใช้ ไวยากรณ์ FreeMakerได้ดีขึ้น

ตัวอย่างที่ 3: To develop Bean Shell Hash Variable plugin, we can refer to the source code of all the Hash Variable plugin and Bean Shell plugin. Especially, we can refer to Environment Variable Hash Variable plugin on how to retrieve environment variable using a variable key. We can also refer to Bean Shell Tool or Bean Shell Form Binder plugin on what to execute the script with Bean Shell interpreter.

6. Prepare your development environment

a. You will need to have the Joget Workflow Open Source ready and built. We will use the "wflow-plugin-archetype" module to generate a maven project for our plugin.

b. Generate a maven project.

The project file generated will be placed at the directory specified in the command prompt, eg: running the command in "C:\" will place the project file in the root of C drive.

To get the correct jogetDependencyVersion in order to build a proper project file with correct dependencies, check the file name specified in the ".m2" folder under directory of, eg:

C:\Users\(your computer name)\.m2\repository\org\joget\wflow-core\"5.0.11"

- Run the following for Window

"C:\Joget Source Code\wflow-plugin-archetype\create-plugin.bat" packageName pluginFolderName jogetDependencyVersion

- Run the following for Linux or Mac

/joget_src/wflow-plugin-archetype/create-plugin.sh packageName pluginFolderName jogetDependencyVersion

- Sample Screenshot in Mac:

c. Open/Import the maven project with your favorite IDE. Joget team recommends NetBeans IDE.

7. Just code it!

a. Extending the abstract class of a plugin type

Refer to the document of the plugin type listed in Plugin Types. Find the abstract class and interface that need to be extended and implemented by your plugin.

Example: To develop a Userview Menu plugin, the plugin class need to extends the org.joget.apps.userview.model.UserviewMenu abstract class.

b. Implement all the abstract methods

A plugin will have to implements the abstract method of Plugin Base Abstract Class and Interface and also the abstract method of the individual abstract class and interface for the plugin type.

Example: To develop a Userview Menu plugin, the following methods have to be implemented by the plugin. Please refer to the plugin documents for the details of each methods.

getCategory
getClassName
getDecoratedMenu
getDescription
getIcon
getLabel
getName
getPropertyOptions
getRenderPage
getVersion
isHomePageSupported

c. Manage the dependency libraries of your plugin

The generated plugin folder by "wflow-plugin-archetype" module is a maven project. So, we will using the Dependency Mechanism provided by Maven.

d. Make your plugin internationalization (i18n) ready

To make the plugin i18n ready, we need to create a message resource bundle property file for the plugin.

Create a property file with the plugin class name in "[Plugin project directory]/src/main/resources/message" directory.
Example: For a plugin named "GanttChartMenu", we need to create a "GanttChartMenu.properties" file under "[Plugin project directory]/src/main/resources/message" directory.
Sample content for GanttChartMenu.properties file
```
org.joget.sample.GanttChartMenu.pluginLabel=Gantt Chart 
org.joget.sample.GanttChartMenu.pluginDesc=To display form data in Gantt Chart layout 
userview.ganttChart.label.title=Title 
userview.ganttChart.label.week=Week
```

Use getMessage(String key, String pluginName, String translationPath) of PluginManager or AppPluginUtil to retrieve i18n label.

Example: Use the getMessage method in getLabel and getDescription methods to return i18n label and description.

public String getLabel() { 
    return AppPluginUtil.getMessage("org.joget.sample.GanttChartMenu.pluginLabel", getClassName(), "message/GanttChartMenu"); 
} 
public String getDescription() { 
    return AppPluginUtil.getMessage("org.joget.sample.GanttChartMenu.pluginDesc", getClassName(), "message/GanttChartMenu"); 
}

Pass a translation file path to readPluginResource(String pluginName, String resourceUrl, Object[] arguments, boolean removeNewLines, String translationFileName) method of AppUtil to provide the plugin properties option with i18n label. We can use "@@message.key@@" in the JSON of ตัวเลือกคุณสมบัติปลั๊กอิน.

Example: For property options of a GanttChartMenu plugin, the following shows the sample code implementation of getPropertyOptions method and the GanttChartMenu.json file

public String getPropertyOptions() { 
    return AppUtil.readPluginResource(getClassName(), "/properties/GanttChartMenu.json", null, true, "message/GanttChartMenu"); 
}

[{ 
    title : '@@userview.ganttChart.edit@@', 
    properties : [{ 
        name : 'id', 
        label : 'Id', 
        type : 'hidden' 
    }, 
    { 
        name : 'customId', 
        label : '@@userview.ganttChart.customId@@', 
        type : 'textfield', 
        regex_validation : '^[a-zA-Z0-9_]+$', 
        validation_message : '@@userview.ganttChart.invalidId@@' 
    }, 
    { 
        name : 'label', 
        label : '@@userview.ganttChart.label@@', 
        type : 'textfield', 
        required : 'True', 
        value : '@@userview.ganttChart.label.value@@' 
    }] 
}]

Pass a translation file path to getPluginFreeMarkerTemplate(Map data, final String pluginName, final String templatePath, String translationPath) method of PluginManager whenever retrieving a HTML template. Once we passed a translation file path, we can use "@@message.key@@" in the freemarker template to retrieve i18n label.

Example: For getRenderPage method of a GanttChartMenu plugin, the following show the sample code implementation of getRenderPage method and the "GanttChartMenu.ftl" FreeMarker template.

    public String getRenderPage() { 
        Map model = new HashMap(); 
        model.put("request", getRequestParameters()); 
        model.put("element", this); 
         
        PluginManager pluginManager = (PluginManager)AppUtil.getApplicationContext().getBean("pluginManager"); 
        String content = pluginManager.getPluginFreeMarkerTemplate(model, getClasstName(), "/templates/GanttChartMenu.ftl", "message/GanttChartMenu"); 
        return content; 
    }

<div> 
    <h1>@@userview.ganttChart.label.title@@ : ${element.properties.title!}</h1> 
</div>

Postfix the plugin class name with an underscore and language code to create a message resource bundle property file for other language.

Example: GanttChartMenu_zh_CN.properties

e. Register your plugin to the Felix Framework

You will find that a class named "Activator.java" is auto generated in a package of your plugin maven project. The class is used to register your plugin class to the Felix Framework. You do not need to do this if your plugin is not an OSGI Plugin.

In the start method of the activator class, add your plugin class to the "registrationList" variable.

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

f. Build it and testing

Once you are done with all the steps above, you can build your project with your IDE using Maven. You can also run "mvn clean install" command in your project directory to build it. After building your project, a jar file is created under "target" folder in your plugin project folder. Upload the plugin jar to Manage Plugins to test your plugin.

Example: In NetBeans, right-click on the project name, then select "Clean and Build".

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

You have completed a very useful plugin. Don't just keep it to yourself, share or sell your plugin in the Joget Marketplace or even better, you can write a tutorial in our Knowledge Base to share your effort with others. To share or sell your plugin, please send an email to info@joget.org.

Page tree