User talk:VuongCT0711

Developing Plug-Ins - IFormFactory (ZK Webui)

This tutorial was brought to you by VuongCT0711. If you have any questions, criticism or suggestions for improvement, feel free to visit my page VuongCT0711 or write me an email

Goal of this tutorial

The goal of this tutorial is to show how to use the IFormFactory service in you plug-in project. Developing your own plug-in for iDempiere,when you want to create your own forms to do specific tasks and provide them on iDempiere server so that iDempiere can make use of them, IFormFactory service will help you achieve this through OSGI services.

Prerequisites

Before you start this tutorial, you should take a look at the following tutorials:

Developing Plug-Ins without affecting the Trunk

Developing Plug-Ins - Get your Plug-In started

Workflow

In this tutorial i will create my own plug-in named com.hdsoft.plugins.formcontroller. There are 2 ways of creating your own Form then register it using IFormFactory:

- Method 1: Create a Component Class that extends ADForm class and register it.

- Method 2: Create a Java Class that implements IFormController interface to define your custom Form then register it.

In this plug-in i will make a new Form using IFormController interface and provide my new Form on OSGI Service so that iDempiere can call it (Method 2).

* Create your own plug-in :

+ Uncheck "Use default location" and browse to your plug-in directory.

+ Check "an OSGI framework", choose Equinox.

+ Uncheck "Generate an activator..." , later we'll use the default provided AdempiereActivator in iDempiere.

* Configure plug-in META-INF/MANIFEST.MF :

+ Open MANIFEST.MF inside META-INF, navigate to tab Dependencies tab and add the Required Plug-ins:

org.adempiere.base

org.adempiere.plugin.utils

org.adempiere.ui.zk

org.zkoss.zk.library

+ Navigate to Overview tab and check "Activate this plug-in when one of its classes is loaded" and "This plug-in is a singleton".

+ Browse to org.adempiere.plugin.utils.AdempiereActivator on Activator field.

* Create your Form class :

In this tutorial i created WMyFormController.java that implements IFormController and EventListener to handle some function on the form and place it in com.hdsoft.webui.apps.form package.

* Create your Form Factory class :

In this step, we create a class that implements IFormFactory, you can name it according to your preferences. For example i named it HdSoftFormFactory and place it inside com.hdsoft.webui.factory package. This class is meant to be used as the default Form loader of your plug-in which will be called from OSGI service when there is a request to create a Form from client. At this stage it hasn't been defined to interact with OSGI service yet. Just add some code to it so that later it will function properly.

* Create Component Definition for your Form Factory class :

Create a folder in your plug-in and name it OSGI-INF then add component definition in the folder, browse to your Form Factory Class created in the previous step. The component name is required to be unique inside iDempiere scope, else OSGI service will fail to load it when server starts.

* Configure Component Definition :

+ Navigate to Services tab and add IFormFactory to Provided Services section.

+ Navigate to Overview tab and add property named service.ranking with Integer type and a positive value (1 for example) to Properties section.

service.ranking property help OSGI determine the priority to look for Classes providing services in plug-ins. For example, if i run 2 different plug-ins with 2 separate Factory Classes, OSGI will continuously execute methods in Service-providing Classes from high to low priority (from service.ranking 1 to 2 and higher...) until one of look-up methods return a legal Object (not null), the look-up process will stop. So make sure you use different service.ranking value to control OSGI look-up flow for the same type of Factory Service as you intend to.

Now when we start iDempiere Server on Eclipse,open Run Configurations and remember to check your plug-in to start with server, you can also set it as auto-start = true.

* Configure your form on iDempiere :

+ Launch iDempiere with your new plug-in. Log in as System Administrator Role.

+ Create new Form

+ Create new Menu

* Run your new custom Form :

+ Log in as Gardenworld Admin

+ Open the new custom Form from the Menu (in case it doesn't show up, open Role menu and add your role access to the new custom Form)

Summary

As i mentioned, there are 2 methods of providing iDempiere with your custom Forms in your own plug-in using IFormFactory service. And in this tutorial i demonstrate the steps to do it by implementing IFormController interface. The other method is pretty similar to what was described above, just instead of implementing IFormController, the component Class representing my custom Form must extends ADForm. Then it will be called by OSGI service using the same code in HDSoftFormFactory.

References

- Code snippet for HDSoftFormFactory recommended by Heng Sin : New zk Form in iDempiere: ClassNotFoundException

- For more understanding and tutorials on Plug-ins development on iDempiere, plz visit : Plug-ins Development

- For Seft-Studying on other OSGI services provided in iDempiere, plz refer to org.adempiere.base package in org.adempiere.base and org.adempiere.webui.factory package in org.adempiere.ui.zk