View source for Developing Plug-Ins - IFormFactory (ZK Webui)

[[Category:Development|P]]
[[Category:Developer documentation‏‎]]
[[Category:Plug-In Development]]
[[Category:HowTo]]
[[Category:Updated2022]]
__TOC__
This How-To was brought to you by Vuong Chu. 

If you have any questions, criticism or suggestions for improvement, feel free to visit my page [[User:VuongCT0711|VuongCT0711]] or write me [mailto:vuong.chu@hungdao.com.vn an email]

== Goal of this How-To ==

The goal of this How-To 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 How-To, you should take a look at the following How-Tos:

* [http://wiki.idempiere.org/en/Developing_plug-ins_without_affecting_the_trunk Developing Plug-Ins without affecting the Trunk]
* [http://wiki.idempiere.org/en/Developing_Plug-Ins_-_Get_your_Plug-In_running Developing Plug-Ins - Get your Plug-In started]

== Workflow ==

In this How-To, 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 Java Class that implements IFormController interface to define your custom Form then register it '''(Recommended)'''.
* Method 2: Create a Component Class that extends ADForm class and register it.

In my sample 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 1).

== Since iDempiere 9: New Form Factory and Annotation ==
[[NF9_OSGi_New_Form_Factory]]

== Create your Form class ==

In this How-To, 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.

[[File:Form_Controller_07.JPG|800px]]


== 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. 
<br>
[[File:Form Controller 08.JPG|800px]]

== Create Component Definition for your Form Factory class ==

''We recommend that you do it automatically '''by adding''' '''an annotations to the CalloutFactory class you just created. Read more about it [[Developing plug-ins without affecting the trunk#Event%20handle|here]]''''''

If you want to do it manually you need to:

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.
<br>
[[File:Form_Controller_09.JPG|400px]]

=== Configure Component Definition ===

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

[[File:Form_Controller_11.JPG|800px]]

* 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 you 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.

[[File:Form_Controller_10.JPG|800px]]

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 activated. Log in as System Administrator Role.
* Create a new Form record

[[File:Form_Controller_06.JPG|800px]]

* Create a new Menu entry

[[File:Form_Controller_05.JPG|800px]]


=== Run your new custom Form ===

* Login 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)

[[File:Form_Controller_12.JPG|800px]]

== 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 How-To 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 your custom Form must extends ADForm. Then it will be called by OSGI service using the same code in HDSoftFormFactory.

== References ==

- Code snippet for Form Factory Class recommended by Heng Sin : [https://groups.google.com/forum/#!topic/idempiere/v7YXl32EWzY New zk Form in iDempiere: ClassNotFoundException]

- For more understanding and How-Tos on Plug-ins development on iDempiere, plz visit : [http://wiki.idempiere.org/en/Category:Plug-In_Development 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