A window provides create, read, update, and delete (CRUD) access to the data to a user. These functionalities are provided by the standard tools and menus. A standard layout of a window has the following parts:
- Title bar
- Menu bar
- Tool bar
- Tabs panel
- Status bar
The following screenshot shows the different parts:
Given the ADempiere architecture, as an author of a new window, you do not have to worry about how and what gets displayed in the Title, Menu bar, Tool bar, and Status bar. All we need to focus on is the Tabs panel. And, in this recipe, we will go through the steps required to create a complete working new window in ADempiere, which will act as the foundation for building our MOM window.
Connect to the database adempiere360 using adempiere as the user using your favorite PostgreSQL client (for example, phpPgAdmin or pgAdmin III or command based psql)
- Create the following table in your
adempiereschema:CREATE TABLE adempiere.c_mom ( c_mom_id numeric(10,0) NOT NULL, ad_client_id numeric(10,0) NOT NULL, ad_org_id numeric(10,0) NOT NULL, isactive character(1) DEFAULT 'Y'::bpchar NOT NULL, created timestamp without time zone DEFAULT now() NOT NULL, createdby numeric(10,0) NOT NULL, updated timestamp without time zone DEFAULT now() NOT NULL, updatedby numeric(10,0) NOT NULL, value character varying(30) NOT NULL, name character varying(255) NOT NULL, start_date date NOT NULL, start_time timestamp without time zone NOT NULL, end_time timestamp without time zone NOT NULL, chairperson character varying(80), participants character varying(4000), agenda character varying(4000), discussion_detail character varying(8000));
ADempiere requires the following standard columns to be present on the tables, which ADempiere populates on its own:
- ad_client_id: Client Identifier
ad_org_id: Organization Identifier
isactive: Flag to indicate whether the record is active
created: Time when the record was created
createdby: ID of the user who created the record
updated: Time when the record was last updated
updatedby: ID of the user who last updated the record
Additionally, every table must have a primary key, which must follow the naming convention of
<table name>_id. c_mom_idwhich is the primary key of thec_momtable. - ad_client_id: Client Identifier
- Run the desktop version of ADempiere and log in using System/System. Select the System Administrator as Role. After a successful login, You will see the Menu on the left-hand side of the window, and you will see the Application Dictionary related items:
- Click the Table and Column. It will pop up the Lookup Record: Table window where you click on the New Record
button on the bottom-left corner. - Enter the following details on to the Table tab as shown in the following screenshot:
- In the previous image, we used the default Data Access Level—All. This is only to make sure that we are able to access the window using any role so that we don't have to log out as the System Administrator and log in with another role to be able to access the window. But, in a real world scenario, you may have to use other options such as Client level, Client and Organization level, System level, and so on.
- Click Create Columns from the DB button. This will bring up the Create Columns from DB window where it prompts you to select the Entity Type.
- Select User maintained as the Entity Type, as shown in the following screenshot:
- Click the tick button. It will pop-up a window showing all the columns generated from the table, as shown in the following screenshot:
- Click the tick button. This completes the creation of the columns, which you can verify by clicking on the Column tab.
Based on the data type of the columns in your database table, ADempiere guesses the data type of the columns, which you may want to use to store and retrieve data. For example, the Date on the column defaults to Date+Time in ADempiere, which may not be appropriate always as you may want to only store the date part of the timestamp. So, it is worth spending some time reviewing the Reference for the generated columns and making the required changes, if any.
- Click on the Window, Tab, and Field menu option under Application Dictionary. This will pop-up the Lookup Record: Window window where you click on the New Record button in the bottom-left corner.
- Enter the values on the Window tab, as shown in the following screenshot:
- Verify the window access on the Access tab. By default, the access is given to all the roles in the system, as shown in the next screenshot. If you want, you can control the access using the Active field. However, for now, let us go ahead with the default.
- Now that we have created the window, we will move on to creating tabs within the window.
- Click on the Tab tab and click on the New Record toolbar button. Fill in the details about the first tab of MOM where we would display the following basic details of a MOM:
- MOM name
- Date
- Start time
- End time
- Chairperson
- Agenda
Table: Select the MOM table that we had created in the previous steps.
- Click on the Create Fields button to create tab fields from the table columns. This will pop-up an information window showing additional details about this process, as shown in the next screenshot. Click on the tick button.
- Click on the tick button. This will complete the process of creating fields from the table columns.
- Go to the Field Sequence tab to see the default sequence in which the fields will appear on the tab. In case you want to change the sequence, you can do it in the Sequence area. Select the field, whose sequence you want to change, and use the up and down arrow keys on the right to change the position of that field. Alternatively, you can also use the drag-n-drop for quicker re-ordering. The following screenshot shows our fields after ordering:
- Another thing you must have noticed is the field names. They do not look readable and do not conform to the human language. For example, names with '_' (underscore) is not something that we would like to use in our field labels on the UI. To correct this, go to the Field tab and correct the Name field values. As a good practice, also add in the Description for the fields. ADempiere automatically generates descriptions for various standard fields like Client, Organization, and so on. So, effectively, you will have to enter the description for the fields that are specific to your need.
- Alternatively, you can change the Name, Description, and Comment/Help of the fields on the Column tab of the Table and Column windows. This is the preferred way if you want the same name to appear on all the windows/tabs you create using the table. However, if you need to have different labels on the windows/tabs even though all the windows/tabs are generated from the same table, then you shall make the changes on the respective fields on the Window, Tab and Field. An important point to keep in perspective is that, when you regenerate the tab and fields, the Name, Description, and Comment/Help of the fields will be overwritten by the ones set on the fields.
- The following screenshot shows the fields after we have corrected the Name, Description, and Comment/Help.
- Click on Menu | System Admin | General Rules | System Rules | Menu. This pops up the Lookup Record: Menu window, as shown in the following screenshot:
- On Lookup Record: Menu window, click on the New Record button in the bottom-left corner. Fill in the details, as depicted in the following screenshot, and save it.
- Log out and log in as GardenAdmin/GardenAdmin. You will see the following Minutes Of Meeting menu item:
- Click on the Minutes Of Meeting menu item. This will bring up the Minutes Of Meeting window with one tab, MOM. You will now be able to enter your MOM details and save it, as shown in the following screenshot:
At this stage, we have got our basic MOM window ready where we are able to save/update the information. As a standard practice in ADempiere, the Search Key shall appear before the Name field. We will do this in the later part of this chapter. However, you may work with the field sequence to accomplish this.
ADempiere has a powerful, yet flexible, framework called Application Dictionary. It is called the core/kernel/heart of ADempiere. To generate the windows, tabs, and fields, ADempiere uses the dictionary. The following diagram depicts the steps involved in creating a new window in ADempiere (AD stands for Application Dictionary):
- The last step—Create Menu —allows us to access the window
In step 1, we created the database table, c_mom. step 2 through to 9 is where we created the AD table and columns using the c_mom table. In steps 10 through to 16, we created the AD window, tab, and fields using the AD table and columns created in the previous steps. After that we created a menu item and linked the window with it so that the same can be accessed by a click on the menu item.
ADempiere's Application Dictionary is not just about Table, Columns, Window, Tabs, and Fields; it is much more than this. There are other entities like Process, Report, Workflow, Reference, and so on. ADempiere uses a set of application code and database tables. All the dictionary related tables have the prefix AD_ (for example, AD_Window, AD_Table, and so on). You may learn more about the Application Dictionary at http://en.wikiversity.org/wiki/ADempiere_Application_Dictionary.