Tutorial: Building the Customer and Orders Master-Detail Form

This tutorial will describe how to use the JBuilder wizards to create a new project and the framework for the various parts of the application. The Application Wizard automatically generates a Frame class for the application, which was used to create the Customer form. The JBuilder DataModule Wizard was used to create a DataModule for the application, and you'll learn how to use a DataModule in conjuction with other Frames in an application.

Customer UI

Step 1: Start your project with wizards

1. Choose File|New Project to create a new Java project.

2. Edit the File field to read:

   [d:]\JBuilder\myprojects\CustomerBrowser\CustomerBrowser.jpr

   where [d:] is the drive in which JBuilder is installed.

3. Choose Finish.

4. Choose File|New and double-click the Application icon to open the Application Wizard.
   Note: If you have no projects open when you start the Application Wizard, JBuilder automatically runs the Project Wizard first to create the project, then opens the Application Wizard.

5. Change the class field on Step 1 of the Application Wizard:
   Class: CustomerBrowser

6. Click the Next button and change the following fields on Step 2:
   Class: CustomerFrame
   Title: Customers

7. For this example you do not need a menu bar, a tool bar or an About Box. Check only the options "Generate status bar" and "Center frame on screen".

8. Click the Finish button.

9. Choose File|Save All to save the project and its files. (It's a good idea to save frequently during this tutorial, for example, at the end of each step.)

Before modifying the newly created CustomerFrame, now would be a good time to create the DataModule since the CustomerFrame will need to access two QueryDataSets from the DataModule.

Step 2: Create the Data Module

1. Choose File|New and double-click the Data Module icon to create a new data module.

2. Use the default values for the fields.

3. Click the OK button.

Next, the Database component must be added to the DataModule.

Step 3: Add the Database component

1. Put the DataModule into Design mode: select DataModule1.java in the Navigation pane (upper left) and click the Design tab at the bottom of the AppBrowser window. This displays the visual design tools.

2. Click the Data Access tab of the Component Palette.

3. Select the Database component.

4. Click on Data Access in the Component Tree to drop the Database component into the DataModule.

5. Select the Database component in the Component Tree, and click on connection property in the Inspector. Click on the ellipses button to bring up the connection property editor.

6. Click the Choose URL button to select the Connection URL of the data source for the application.

7. From the list of available Connection URLs, select jdbc:odbc:Cliffhanger.

   If jdbc:odbc:Cliffhanger is not available in the list, click on the Show data sources button to display a list of available ODBC data sources, and select jdbc:odbc:Cliffhanger.

8. Click on the OK button.

9. Edit the following fields:
   Username: SYSDBA
   Password: masterkey

10. Leave the "Prompt user password" option unchecked.

11. Click on the Test connection button to make sure you have configured the database connection correctly. If the test connection fails, see Installing and setting up in the Database Application Developer's Guide.

12. Click on the OK button.

Next you will add the necessary QueryDataSet components to the DataModule.

Step 4: Add the QueryDataSets

1. Click the Data Access tab of the Component Palette.

2. Select the QueryDataSet component.

3. Click on Data Access in the Component Tree to drop the QueryDataSet component into the DataModule.

4. Select the queryDataSet1 component in the Component Tree, and change the name property to customerDataSet.

5. Click on query property in the Inspector, and click on the ellipses button to bring up the query property editor.

6. Select "database1" from the database drop-down list.

7. Enter the following SQL statement in the SQL Statement text area:

     SELECT * FROM Customer
     

8. Click on the Test query button to test that the query executes.

9. Click on the OK button.

10. Add one more QueryDataSet component for the Orders dataset following the steps above.

11. Change the name property to orderDataSet.

12. Select "database1" and set the SQL statement to the following:

      SELECT ID, CUSTOMERID, ORDERDATE, STATUS
      FROM Orders
      WHERE CUSTOMERID = :ID
      

    Don't test the query until the master-detail link is defined in the following steps.

13. Click on masterLink property in the Inspector, and click on the ellipses button to bring up the masterLink property editor.

14. Select customerDataSet from the Master Dataset drop-down list, which will populate the Available Master Columns list, and default the ID column in the Master Link Column list.

15. Remove all columns from the Detail Link Columns list, and add the CUSTOMERID column from the Available Detail Columns list to the Detail Link Columns list.

16. Click on the Test link button to test the master-detail link.

17. Click on the OK button.

At this point, you have completed the necessary steps to establish the database connection, and to access the data from the database. Next you will setup the CustomerFrame to access the datasets from the DataModule.

Step 5: Access the DataModule

1. Select CustomerFrame.java in the Navigation pane of the AppBrowser.

2. At the top of the file, you will see this code:

       public class CustomerFrame extends DecoratedFrame {
         BorderLayout borderLayout1 = new BorderLayout();
         XYLayout xYLayout2 = new XYLayout();
         BevelPanel bevelPanel1 = new BevelPanel();
     

   Add the following line of code to get a handle to the DataModule so that the QueryDataSets can be retrieved:

         DataModule1 dm = DataModule1.getDataModule();
     

3. Click the Design tab of the Content pane, if it's not already selected.

Now you're ready to add data-aware JBCL controls to the CustomerFrame to display Customer records and related Order records. Although the DataModule isn't visible in the Designer, the QueryDataSets defined in it will be available when you're ready to bind controls to datasets.

Step 6: Add data aware controls

The navigator panel

1. Rename the original BevelPanel bevelPanel1 to pnlNavigator.
2. Set the constraints property of pnlNavigator to NORTH.
3. Add a new BevelPanel component to the CustomerFrame, name this BevelPanel pnlMain.
4. Set the constraints property of pnlMain to CENTER, if it isn't already.
5. Add a NavigatorControl and a ButtonControl to pnlNavigator.
6. Change the layout property of pnlNavigator to BorderLayout, and set the constraints property of the NavigatorControl and ButtonControl to WEST and EAST respectively.
7. Change the margins property of the pnlNavigator to 4, 4, 4, 4.
8. Change the label property of the ButtonContol to Close
9. Set the dataset property of the NavigatorControl to customerDataSet.
10. Go to the Inspector, select the Events page, and double-click the value field for the actionPerformed event. Add the following code in the event handler:

      void buttonControl1_actionPerformed(ActionEvent e) {
        this.setVisible(false);
        this.dispose();
      }
      

The main panel

1. Add two BevelPanels to pnlMain, one on top and the other on the bottom.
2. Rename the top panel pnlCustomer, and the other pnlOrders.
3. Change the layout property of pnlMain to BorderLayout, and set the constraints properties of pnlCustomer and pnlOrders, if necessary, to NORTH and CENTER respectively.

The customer panel

1. Add LabelControls and FieldControls and arrange them to look like the screen shot of the CustomerFrame at the beginning of this tutorial.
2. Give the controls meaningful names, like lblFirstName and txtFirstName for example.
3. Set the dataset property of the FieldControls to customerDataSet.
4. Set the columnName property of the FieldControls to the column names in the Customer table that you want to display in the UI.
5. You can leave the layout property of pnlCustomer to the default layout, which is the XY Layout. Optionally you can change it to the GridBag Layout, which requires a little more fine tuning of the constraints for each control on the panel to make the controls line up properly.

The orders panel

1. Add a LabelControl at the top of pnlOrders, and set the text property to Orders placed by this customer:
2. Add a GridControl in the middle of pnlOrders, and set the dataset property to orderDataSet.
3. Change the layout property of pnlOrders to BorderLayout, and set the constraints property of the LabelControl and the GridControl to NORTH and CENTER respectively.

Finally, set the dataset property of the StatusBar component to customerDataSet, so that all status messages from the customer dataset will be displayed in the status bar.

Now try it out and see if it works. Run your program and browse through the customers in the Cliffhanger database and see the corresponding order records for each customer.

You can enhance the application by adding a few more things. Refer to the source code of the Cliffhanger application for more implementation details:

• Add Persistent Columns for each of the QueryDataSets in the DataModule. Then add Display Masks and Edit Masks for some of the columns in the QueryDataSets, such as Date fields, Phone number fields etc.
• Add a new Frame for viewing and maintaining Orders, then add two buttons on the CustomerFrame, one to view a selected order, and the other to add a new order for the current customer.
• Add code in the WindowClosing event to check if there are pending edits yet to be posted and resolved, and prompt the user if they would like to save the changes made.
• Add an ImageControl with a graphic image to spice up the UI.