How to create a Regions Module
| Languages: |
English | Translate this article... |
Contents |
About this document
This document is part of the Localization Guide for Openbravo and describes the process of creating a module that includes the list of regions for a country.
Recommended articles
Before reading this howto, it is important to have a clear understanding about the Modularity Concepts, specially the process of creating and packing modules.
The main objective of a regions module is to provide a dataset with the list of regions for a concrete country. In case you haven't created yet a dataset, it is recommended to firstly read the How to create a Dataset article to get a general idea before moving to the particular scenario about regions.
From the functional side there is no special knowledge required, it is only recommended to read the Country and Region article.
Estimated effort
A regions module is probably the easiest module in a localization project. The final effort highly depends on the number of regions to be included into the module. In general the estimated duration for creating a regions module should be just a few hours.
Introduction
The list of countries is embedded in the Core module as part of what it is called Masterdata (which also includes, for example, currencies). However regions are not included and must be created for every country, making it a perfect candidate for a localization module.
A regions module just consists on a dataset with the list of regions for a particular country. When a user installs this module, his instance will automatically contain the regions for that country.
Apart from the evident benefit of making it faster for the user to define addresses, the regions module will be the base for developing new modules that depend on this regions definition, like the Taxes module, which may include different taxes settings based on these regions.
Register the regions
To define the regions for a country it is necessary to go to the Country and Region window and select the country. If your country is not listed in this window, please report an immediate issue and we will include it in the next MP.
Inside the Region tab you must enter the regions for that country:
Finally, in the country definition we should specify that this country has regions and set the name regions receive in the country's language. For example, in Spain a region is called Provincia
Module definition
As you already know, the regions module is like any other module that includes a dataset, so there are no special tricks for declaring it inside the Application Dictionary, but just some few considerations:
- You should try to follow the Naming guidelines for modules
- The flag Has reference data must be set. Remember to write any useful information inside the Reference Data Description field.
- Inside the Dependency tab, include the mandatory dependency to Core.
- Remember to register the module in case you want to publish it in the Forge
Dataset definition
Dataset definition is the key step in this process. A wrong dataset definition can waste all our previous work, so it is important to follow all these considerations:
- The dataset must belong to your regions module
- Try to avoid strange characters in the dataset name. This string is used for generating the XML file name that stores the dataset.
- The Data Access Level must be set to System only, which means the dataset will be automatically applied as system level when the user installs it.
- The Export allowed flag must be set.
- Inside the Table tab we must register all the tables to be included into the dataset. The tables are:
- C_Region, which stores the regions.
- C_Country, which stores the countries. It is not necessary to export all the columns for this table, but just the HasRegion and RegionName columns which we have previously modified. In case you want to include more modifications for the value of any other column for your country, you should also include them there.
- The HQL/SQL Where clause is a very important field, because it allows us to filter the records we want to include into the dataset. In our case we just want to include all the records related to our country, so the HQL/SQL Where clause can be:
- For the C_Country table: name='<country name>'
- For the C_Region table: country.name='<country name>'
The dataset definition is ready, so we just need to export it to a file pressing the Export Reference Data button. This process queries the previous tables and gets all the records that fulfill the HQL/SQL Where clause, generating a XML file inside the module's referencedata/standard directory. As a fast check, you can open this file using any plain text editor and you can verify that it contains several lines.
In case the file is empty, you should double check the dataset definition, specially the HQL/SQL Where clause used for each table.
Packaging the module
To generate the obx file we should follow the standard steps from the command line:
- Export the database:
ant export.database
- Package the module:
ant package.module -Dmodule=<regions module java package>
- We can now publish the module in the Central Repository
Testing the module
To properly test this module, we must to install it in a fresh Openbravo instance. The installation process will automatically insert all the regions for the country, because the dataset has defined at System level.
After a successfully installation, we just need to check all the regions for our country has been inserted.
Considerations when releasing new versions
If you plan to release new versions of the regions module, you must remember some important aspects related to the common behaviour of datasets.
The considerations explained on the How to create a Taxes module article can be directly extrapolated to this module, so please read this chapter before start working on the new version.