View source | Discuss this page | Page history | Printable version   

How To Create and Package a Module

Contents

Objective

Openbravo ERP 2.50 introduced the concept of Modularity. Modularity provides developers with the means to be able to develop, package and distribute their work in a structured and controlled manner. For users of Openbravo ERP, Modularity makes it possible to download, install and update custom developments.

This how-to describes how to create and package a new module. It is of particular interest as it describes the first steps which should be followed in all of the other how-to in this developer's guide and in Openbravo ERP custom development in general.

Introduction to Modularity

The objectives of modularity are:

A module is a piece of additional functionality that can be deployed optionally and independently on top of Openbravo ERP. Examples of modules are: additional reports, additional windows, connectors, content packs (translations, chart of accounts, list of tax codes, product categories, etc).

For a detailed description on the Openbravo ERP modularity concept, see the Modularity Guide.

This how-to will explain only the standard module type, because that is most relevant for the other how-tos. The two other module types, Industry Templates and Packs, are not covered here.

All new development should be done as a part of a module. Only modules which are marked as In Development can be used in the development process. A module can consist of the following software artifacts:

The process of developing a module has three main steps:

  1. Register your module in the Application Dictionary and in the central repository.
  2. Develop the artifacts included in your module. Depending on the functional specification and technical design of your module it might include only one type of artifacts or a combination of them. In following sections each type of artifact is described in detail.
  3. Extract the .obx file of your Module and publish it in the central repository.

Steps 1 and 3 are common to all types of modules and straightforward. Step 2 depends on the requirements of your module. It has not significantly changed from the way you have developed Openbravo ERP code in previous releases to 2.50 but a few details that you need to know and that are described throughout later in this document. In particular the development tasks (create/update the database, build and compile the system, etc.) have been slightly modified to fit the modularity paradigm.

From now on, every piece of Openbravo ERP code belongs to a module, including Openbravo ERP core itself. You should do all your new developments through modules, including customizations. You can still make changes directly in other modules -including Openbravo ERP core- but it is highly recommended not to do that. It makes it much easier to maintain Openbravo ERP if you restrict code changes to modules.

A module can be distributed and downloaded by other Openbravo ERP users via the central repository.For more information about the central repository and distribution of modules, see the Modularity Guide.

The following sections will discuss the main topic of this how-to: create and setup a module and package it for distribution.

Creating a Module

The first step in the development process is to create a new module. From the Application menu, select Application Dictionary || Module.


FieldModule 30.png


Note the following important fields: (for more details see the AD_Module table description):

The tabs at the bottom of the window enable you to define the module further:


In this how-to, we will create an example module, called Openbravo Howtos'. We will define the module using the following three tabs of the Application Dictionary || Module window:

The result of this howto will be a module which can be used as the basis for all subsequent developments within the howto articles in the developers guide.

Dependency: Openbravo ERP core functionality is in itself a module, called core. All modules have a dependency on User Interface Application and in turn, it has a dependency on Openbravo core. In the Dependency window, specify that the module is dependent on User Interface Application. (see also the AD_Module_Dependency description):

ModuleClientApplicationDependency 30.png


DB Prefix:at least one db prefix is required when a module also contains database artifacts (table, column, constraints, etc.). Openbravo ERP determines the module of a database artifact by checking to see if its name starts with one of the defined db_prefixes. As other howto's in the developers guide will add database artifacts, let's specify at least one DB prefix.

Bulbgraph.png   DB Prefix can only contain uppercase [A-Z0-9] and the first letter is required to be from [A-Z] only.
Module dbprefix 30.png

For more information see the AD_Module_Dbprefix table description.


Data Package: Tables are linked to a module through the Data Package. The generated business object for the new table will use the Java Package defined in the Data Package. Other howto's in the developers guide will add new tables so there is a need to specify a data package as illustrated in the image below.

Datapackage 30.png


Develop your software artifacts

At this point you are ready to develop the software artifacts required for the functionality of the module. While developing the relation to the module is maintained in different ways:

When you are ready with your custom development the next step is to export the module.


Exporting a Module

Exporting a module creates a directory for your module under Openbravo ERP root directory and the appropriate XML files for inclusion in the finished module. Modules that are not flagged as being in development are not exported - remember that you must select the In Development checkbox when you define a new module, otherwise it will not be exported.

When the development of the module is finished (or to deliver intermediate results), open a command window/shell and navigate to the Openbravo ERP development project execute the ant export.database command.

Bulbgraph.png   Export database task will export all and only the modules set as in Development
ant export.database

Since we do not have any additional developments yet, only the corresponding folder structure and the module descriptor XML files have been created at this point.


Module directory.png


Openbravo ERP validates the database and module artifacts of a module when the module is exported and packaged. See more information on the database validation step.

For a detailed description of this export.database task and other relevant Module related ant task see the database ant tasks and module ant task descriptions.


Creating a Source Directory

To develop manual Java code you need a src directory inside of your specific module:


Module src.png


The Java package in the source directory should start with the Java package of the module. So for this case org.openbravo.howtos.test and org.openbravo.howtos.app would both be valid packages.

If using Eclipse, add the newly created module's src folder to the build path of the Eclipse project (Java Build Path):

Src build path.png

This makes it possible for Eclipse to build the code and have a full-functional Java editor when editing the source code of your module.

Including Documentation

Documentation for the module can be included within module's project in Openbravo Forge. When setting up the project that will hold the module check "Wiki" as a service to be included in the project. Documentation can be written in that wiki. This information will be publicly available if the project is public, or restricted to the users which can access the project if it is private.

Another way of attaching documentation to a module is by including it in the module itself. In this way documentation will be only available from Openbravo instances that have this module installed.

This second option can be achieved by writing the documentation in files stored in the module's web/org.openbravo.howtos/docs directory (or any subdirectory of it). Here can be placed any desired resource. It is also possible to include in this directory an index.html HTML file with links to the rest of the documentation making in this way the information easier to be accessed by the user.

In our case we would have the following file path modules/org.openbravo.howtos/web/org.openbravo.howtos/docs/index.hml. After compiling and deploying the application these documents will be available from the browser in the following URL http://yourserver/openbravocontext/web/org.openbravo.hotows/docs where yourserver is the server name where Openbravo is hosted and openbravocontext the context name for Openbravo application.

An example of an actual module including documentation in this way is User Interface Client Kernel module. It includes documentation accessible from the Forge, as well as in the module itself.

Packaging a module

The last step in the process is to package the module and distribute it through the central repository or sending it to an interested party directly.

To package a module, execute the command ant package.module -Dmodule=<modulePackageName>. In the case of the howto module, the command would be:

ant package.module -Dmodule=org.openbravo.howtos

If you are using Windows, you could need to add quotes on when specifying the module: -Dmodule="org.openbravo.howtos"

The output of the package.module task would roughly look like this:

$ ant package.module -Dmodule=org.openbravo.howtos
Buildfile: build.xml

package.module:
     [echo] Validating Module...
[validateModules] 0    [main] WARN  SystemValidation  - Validation successfull no warnings or errors

obx.export.database:

obx.export.config.script:

BUILD SUCCESSFUL
Total time: 48 seconds

As you can see in the output, the package step validates the module definition itself.

If the packaging process was successful, a new obx file is created in the directory in which this ant task was executed. The name of the example module crated in this how-to is org.openbravo.howtos-1.0.0.obx. Note the obx file is in zip format so you can open it with any archive manager. (Perhaps by first renaming it to org.openbravo.howtos-1.0.0.zip)

Deploying/Compiling a module

Once you have created an .obx file, the final step is to compile and deploy it. Installing a module compiles the Java sources, copies relevant files to the web application directory (images, etc.) and also updates the database.

You can install a module from within Openbravo ERP:

  1. Log in as System Administrator.
  2. From the Application menu, select General Setup || Application || Module Management.
  3. Select the module you want and click Install Now.
  4. Follow the on-screen instruction to rebuild the application and restart the Tomcat server.

You can also install a module from the command line, using the ant task

ant smartbuild -Dlocal=no

after manually unzipping the .obx file into the OpenbravoERP/modules folder.

The Result

The result of this how-to is a correctly set up and packaged module which you can then use as the basis for the other how-tos in this Developers Guide.

Retrieved from "http://wiki.openbravo.com/wiki/How_To_Create_and_Package_a_Module"

This page has been accessed 55,244 times. This page was last modified on 1 July 2012, at 12:13. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.