Talk:Create your ADempiere customization environment

From ADempiere
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.

Copy of the old tutorial content.

Tutorial by CarlosRuiz_globalqss

This tutorial will show you how to make a customization project by making a customization.jar with your changes and deploy them in the ADempiere binary

Introduction:

Sometimes you realise that ADempiere does not perfectly suit your needs and you need to make some changes to parts of the sourcecode. Some customizations are not possible to achieve through ADempiere’s brilliant Application Dictionary and you have to modify the source code for that. The recommended way of doing customizations is to do it in a separate project. There you can do your customized classes and create customization.jar archive. For additional information you can also refer to: http://en.wikiversity.org/wiki/Adempiere_Technical_Training#Project_Customization_Management_Hints

I am going to walk you through an sample customization using ADempiere 3.2. It is mostly applicable to any version thereafter.

How to setup up your environment

Create the tag project (adempiere320)

  1. Check out Adempiere 3.2 (see Create_your_ADempiere_development_environment) or a newer Version/tag (see in german)
  2. Create a new project in eclipse
  3. Right click on the Package explorer pane choose New and then java project.
  4. Give your new project a name. For example custom_termo_adempiere320
  5. Choose create separate folders for sources and class files.
  6. Make sure that the jre is compatible (as of 28 Feb 2006 you should use java 1.5).
  7. Click finish

Create the project source directory

Create the source directory structure and package structure for the files you are going to customize exactly the same as the ones in ADempiere 3.2’s source you checked out earlier.

For this particular example I am going to modify the file ALoginRes_bg.java located in client/src in package org.compiere.apps. To do that do the following in custom_termo_adempiere320 project:

  1. Right click on custom_termo_adempiere320 and choose New->Source Folder
  2. Name it client/src and hit save
  3. Right click on the newly created source folder and choose New-> Package and name it org.compiere.apps
  4. Now copy the file ALoginRes_bg.java from the ADempiere 3.2’s source code you checked out earlier and paste it in package org.compiere.apps we just created in the project custom_termo_adempiere320.
  5. Make your modifications. In this case I am going to substitute the string "\u041f\u0440\u0438\u0432\u0438\u043b\u0435\u0433\u0438\u0438" located next to the string “Role” with the string “Rolia”.

Compile and export your customizations

  1. Right click on custom_termo_adempiere320 and choose export. Select Java->JAR file for the destination. Hit next.
  2. Choose the files you would like to export. In our case we do not want .classpath and .project so we uncheck those.
  3. Choose an export destination. Make sure you name your export file customization.jar. I choose D:\customization.jar. Click next.
  4. Uncheck export class files with compile errors.
  5. Click finish

Apply the customizations to your ADempiere installation

  1. Copy the customization.jar file that we just created to the ADEMPIERE_HOME\lib
  2. Run ADEMPIERE_HOME\RUN_silentsetup or ADEMPIERE_HOME\RUN_Setup

You have successfully deployed your customization.

Test your customization

  1. Start the ADempiere server by running ADEMPIERE_HOME\util\RUN_Server2
  2. Start the ADempiere client by running ADEMPIERE_HOME\RUN_Adempiere
  3. Choose Bulgarian (BG) for language and hit OK.

Now you should see the string “Rolia” instead of the Bulgarian translation for Role next to the drop-down allowing you to choose a Role.

Solving Dependencies

When you try to compile your customization source files you may run into missing dependency problems. You should resolve those by right clicking on your customization project and choosing properties to bring up the properties window of the project. Choose Java Build Path and add the missing references in the Libraries tab or the Projects tab. For any dependent classes located in the main project adding the main project(ADempiere 3.2 in our case) to the Projects tab should be sufficient.

Setup example within Eclipse

Eclipse setup

This is an example of a real life project, on the right side of eclipse you can see:

  • working set adempiere320 (I use working sets to work with projects of different versions)
    • project adempiere320 (from tags/adempiere320) this project can be considered read-only, never touched
    • project patches_321 (from branches/patches_321) this project have the officially released patches for 320
    • project Localization_Colombia (from contributions/Localizations/Colombia) this project have the customized classes for LCO
    • project QSS (from QSS private repository) this project have the customized classes for our private QSS installation
  • working set adempiere330
  • working set adempieretrunk

To construct patches.jar you can package the bin directory of patches_321 project.

To construct customization.jar you can package the bin directory of Localization_Colombia + QSS projects.

01 eclipse320.png

Project customization setup

The key is to make eclipse notice of the precedence of projects, on the project definition of QSS we define the dependent projects, in this case QSS (custom project) depends on Localization_Colombia, patches_321 and adempiere320 projects:

03 eclipse320 QSSdependent.png

And we need to let eclipse know the precedence where the classes are looked for (the classpath):

02 eclipse320 orderQSS.png

Running / Debugging within eclipse

You need to create a new runner for the project this way:

On the project QSS you define the runner for the project:

04 eclipse320 QSSrun debug.png

Please note that the search button may not be able to find the class org.compiere.Adempiere. In that case you just have to type it manually.

On the arguments section you can tell eclipse the properties to use - you can use one property file for each project:

05 eclipse320 QSSrun debug arg.png

Normally the classpath of the runner doesn't need modifications, just showing it here for documentation purposes:

06 eclipse320 QSSrun debug cp.png


References: http://en.wikiversity.org/wiki/Adempiere_Technical_Training#Project_Customization_Management_Hints

Enjoy !

See Also


All classes (even extend) in customization

Hi Kzmp, thanks a lot for documenting this.

About:
> "Please note that if you need to extend ADempiere
> you may simply place your files in the extend folder
> of the ADempiere source code. Use the customization.jar
> approach if you need to modify core classes"

I think is better to keep all your customizations on the project, I mean, I don't put customized classes in adempiere320/extend, but in my_project/extend

This have some advantages:

  • is easier to maintain all customization classes in just one project
  • is easier to have one eclipse adempiere320 combined with many customized projects
  • is easier to construct the customization.jar - currently I just make the jar from the bin eclipse directory of the project
  • after the adempiere320 installation I never need to RUN_build again - just changing the patches.jar and customization.jar and RUN_setup

CarlosRuiz_globalqss 14:08, 1 March 2008 (EST)



  • Thanks to the globalQSS(Carlos) team for this document.
  • But I wonder how to set-up the webUI using this pattern, wherein the packages were layered so as not to disturbed the standard release source codes.
  • Is there a way to set-up the WebUI in a way that only the touched source files are placed in a new customization folder?
  • Anyone knowledgeable, Please let us know.

--Ivanceras 12:12, 18 October 2008 (EDT)

Retrieved from "http://www.adempiere.com/index.php5?title=Talk:Create_your_ADempiere_customization_environment&oldid=32389"