ERP 2.50:Developers Guide/Concepts/AD/Base References in Modules
This document aims to explain from a general point of view how to implement base references within modules. The concept of reference is explained in the Data Model article. Additionally there is a example where the technical aspects are explained in detail and illustrated with code.
Creating base references allows to define data types for columns and/or visualization widgets for fields in generated windows different to the ones defined in the base ones in core.
Once a base reference is created it is possible to add subreferences to this one if needed. The purpose of this is to be able to have a generic implementation for the base reference that behaves differently according with the subreference. For example let's suppose we want to have a new way to visualize fields of foreign key columns, which in core are displayed by default as a drop down list. We could create a new base reference, let's call it FK reference where we would implement all the logic for the new widget. Additionally we would create a new subreference with this FK reference as parent for each of the tables we want to use it with.
References are defined from Application Dictionary || Reference window.
A reference is set to be a base one by checking the Base Reference field. As there are 2 levels of references (base and subreferences), when a reference is not base, it is mandatory to set which is its parent one.
References define 3 implementators, they are java classes which implement the reference logic. These implementators can be defined at base reference level or at subreference. When the subreference has not implementation class, the ones in its parent's reference will be used, other case the ones in the subreference.
The implementations for references are:
- Model Implementation. Implements the logic used by DAL to generate hibernate mapping for the columns using this reference.
- WAD Implementation. Used to generate the visualization of the fields that use the reference in generated windows.
- Runtime UI Implementation. Implements the rest of UI components related to the reference, such as grid visualization, search poup, etc.
As explained in the previous section each reference can have 3 implementators which are java classes. In the following points it is described the purpose of each of them and the main methods they should implement.
It must implement org.openbravo.base.model.domaintype.DomainType interface.
It extends org.openbravo.wad.controls.WADControl class. This class must be in the src-wad directory of the module. When WAD is compiled (ant wad) this class will be part of the openbravo-wad.jar library and will be used to create the code for generated windows. As WAD does not depend on DAL, it is not possible to use DAL to access to database.
- public String editMode(). This method returns the HTML to represent the field in edition mode.
- public String newMode(). Returns the HTML for the field in edition mode when the record is new and has not been already saved, usually it returns the same than editMode method.
- public String toXml(). If the HTML returned by the previous methods is going to act as a template for xmlEngine, this method would return the xml to be used to populate that template, in this case it would be also necessary to implement toJava method.
- public String toJava(). Returns the Java code to be inserted in the generated Servlet. It can be used to add any logic that is needed, for example to populate the HTML with some info.
- public String columnIdentifier(String tableName, FieldsData fields, Vector<Object> vecCounters, Vector<Object> vecFields, Vector<Object> vecTable, Vector<Object> vecWhere, Vector<Object> vecParameters, Vector<Object> vecTableParameters). This method is in charge of generating the part of the SQL to be used in the XSQL regarding the columns using the reference. The parameters it has are:
- String tableName. Name of the tab's table.
- FieldsData field. FieldProvider with all the information about the current field.
- Vector<Object> vecCounters. It is a count of the number of parameters that have been added to the SQL.
- Vector<Object> vecFields. Vector containing all the fields in the SQL.
- Vector<Object> vecTable. Vector with the tables that participate in the from clause. Used to add left joins.
- Vector<Object> vecWhere. Elements that participate in the where clause.
- Vector<Object> vecParameter. Parameters in xsql format.
- public boolean isLink() When the reference is a foreign key to another table this method should return true. It is used to generate the link in the field's label.
- public String getLinkColumnId(). If it is a foreign key this method returns the ID of the column in the foreign table the reference links to.
This class extends org.openbravo.reference.ui.UIReference.