Tutorial 2


Building an Application Module using the Wizard

This tutorial walks you through a build of a screen module using the JDesignerPro visual Application Builder. This section assumes you have completed Tutorial 1. Tutorial 2 will show you the basics of how to set up an application and deploy within JDesignerPro. We are going to build a simple search and detail screen for sales order information. You will not have to do any coding in Java. It uses the Tutorial database that is automatically installed with JDesignerPro. If you are not on Windows then you will need to follow this tutorial using your own database.

These steps do not explain in detail how each of the features works. For that information, please see the specific text under the section titled, Application Builder. We suggest going through the tutorial step by step before learning the details of the features.

Start: If you just completed Tutorial 1 and are still in the Application Builder, press the New Application button at the top left. Then skip to Step 4. Otherwise, start JDesignerPro and proceed to Step 1. You can Save the Tutorial project at any time by pressing the Save Application button. Please name it "SalesOrder" in the Users directory when you save it. When you return you can reopen it with the Open button and start where you left off.

Step 1. From the initial log in click on the main Application Builder tab.

Step 2. Click the next Application Builder tab to load the design features.

Step 3. When the Application Builder appears, you will see two panels on the left. The top panel has two tabs, Objects and Properties. The bottom panel is called the Layout View and it always starts with a panel on it called Main. The work space for the new form is the blank area to the right of the Objects, Properties and Layout View panels.

Step 4. Let’s add a Wizard component. From the Wizards folder in the Object Tree, drag a Grid object on to Main. In a few moments the Data Wizard will appear. Anytime you drop a Wizard or Data object on to the screen ,the Data Wizard specific to that object will appear.

Step 5. The Data Wizard is the set of screens that allows you to define how this component is to be connected to your database. In the Data Wizard we start at Select Database. Click on the "JDP Tutorial" database. You see here under Select Database a number of options for connecting to databases via JDBC. It is here that you will setup such connections for each data component you use (see Selecting a Database for help on setting up Databases). If you are not on Windows, please choose one of your own databases. You may need to define a New database on this screen to point to your required database. Because the JDPTutorial database is already setup with the default JDBC/ODBC settings, we’ll leave the fields as they are.

Press Connect. The Data Wizard will move you to the next tab, Select Table.

Step 6. JDesignerPro returns the names of the tables in the chosen database automatically. Now we're going to join two tables to access data from both on our finished form.

Click on dbo_sales in the Primary Table list. Then click on dbo_stores in the Secondary Tables list.
What this does: The Primary table is the table that will allow updates on the finished form, the secondary table(s) will allow viewing only. By selecting several tables we can show data from each on our screen and build a Master/Detail.

Step 7. Now let’s join the tables. Under Table Join Criteria, choose a.stor_id from the left-hand pull-down. Next choose b.stor_id from the right-hand pull-down. Press Add. The text "a.stor_id = b.stor_id" appears in the area below the pull-downs. We have now joined those two tables, giving us access to the columns in both.

What this does: The use of ‘a.’ and ‘b.’ to prefix the column names is to give you a way of differentiating between tables. This is known as an "alias." Aliases are used only in the Data Wizard and have no effect on the application or your database. Your Data Wizard Select Table screen should look like this:

Press Accept. The Data Wizard will move us to the Define Keys tab.

Step 8. Under Define Keys, the list on the left shows all the available columns from the primary table. Under Unique Key, select a.stor_id, a.ord_num and a.title_id. If you need to reorder the keys you can simply drag them to the required position. Press Accept and the Data Wizard will move to the Search Panel tab.

Step 9. Under the Search Panel tab, select a.ord_num, b.stor_name and b.stor_address in the left hand list. These are the fields by which Search Panel will be searchable for the end user of the application. The JDesignerPro Search Panel object will automatically offer a search text field for users to type search criteria.

Step 10. Now click on each of these three columns again and alter the text for Description in pulldown. Change Ord Num to Order Number, Stor name to Store name, Stor Address to Store Address. Press Accept.

Step 11. Under the Result List tab, select b.stor_name and b.stor_address in the left hand list. These are the fields by which Result List will be sortable.

Step 12. Click on the Tree Definition tab. Under Initial branch text, enter "Sales." For the Initial branch icon, choose Database. For First branch icon, choose Person.

Under "Select the branch structure of the tree and the icons", click a.ord_num and it will appear in the right-side list. Click a.ord_num in the right hand list and choose Document from the pull-down to the right. Notice that the unique key for a branch in the tree is correctly set to a.stor_id and a.ord_num.
What this does: By adding one or more column to the right side list, we are defining what column the tree structure will show first when expanded at run time by the end user.

Lastly deselect title_id in the Unique key list.

Your Tree Definition settings should look like this:

Step 13. Click the Ordering tab. Change Stor Address to Store Address. Click on a.stor_name then change the Sort pulldown text field to Store Name. This is how you can set the on-screen text for any field used in the Result List and is similar for all data objects.

Press Accept.

Step 14. Select a.qty, a.payterms, a.title_id to be displayed in the grid.

Let’s modify settings of the Grid. Select "qty" in the Columns list. Under the General tab, change Column Header Text to Quantity, Column Header Color to Blue and Column Text Color to Blue.

Now Select title_id in the Columns list and change Column Header Text to Title. Any combination of these settings can be made to enhance your applications.

Step 15. Let’s add a pull down list to appear in one of the grid cells. With title_id selected, click the Field Type tab and choose Choice from the Field Type pull down. Next choose "Database table/columns" from the Values Come From pulldown.

A list of the tables will appear. Select dbo_titles in the Table list, then select title in the Pulldown list and lastly, select title_id in the Actual list.

What this does: We just created a dynamic pull down for the Grid based on the title_id table. It will show the book’s title in the pulldown but return the Title ID to the record in the database when an update or insert is made.

Press Accept. The Wizard will now build all of the necessary Java code for the components along with the Interactions necessary to tie the components together. Once finished, the form with the Search Panel, Result List and Grid will appear on the design form.

With Grid1 highlighted in Layout View, increase the Title column width in the Grid by clicking and holding the edge of the column header and dragging it to the right. All the columns in the grid can be resized this way both at design time and at run time by the end user.

Now click and hold on the Title column header and slide it to the left using the mouse and drop it in the first position in the grid. You can always change the position of a column in a grid in this fashion. Note that by clicking on a title id in the grid you will see that the pulldown has already been populated with some data from the titles table. You can use this to determine the required width of the title column.

Step 16. If you now look at the Layout View tree you will see that the Wizard has created the following component. Inside the parentheses are shown the component's layout position and an "I" if there is an interaction associated with it.

The Wizard has also generated the interactions necessary to tie the components together. These include an interaction between the Search panel and the Result List, one between the Result List and the Grid and several between the Buttons and the Grid. In the next tutorial we will explore these interactions in more detail.

Let’s look at the Java source code that was created during this tutorial. Press the Source Editor button:

When the window appears, the source for the currently highlighted component will be viewable in the window. You should see something like the following:

The top part of the screen displays a list containing all of the methods that the Wizard has created to handle loading and unloading the components to the database. Notice that the Grid1LoadGrid(null) method has been commented out. If you would like the grid to automatically load the rows from the database when the screen first loads you would remove the comments from this line.

You may also click on each of the methods to see the code and SQL that JDP has generated. These may be modified to suit your needs.

Note: If you modify the generated methods in a Wizard or Data object and then go back through the Data Wizard the changes you made to methods that contain references to columns in your tables will be regenerated and your changes will be lost. However, other methods, including new methods that you create, will be unchanged. Generally you should place your own source in non-Data Wizard created methods or in your own new methods. One system to allow you to make Data Wizard changes with your own source is to always make a safe copy of your application. Then copy and paste your own code back into the Data Wizard object after regenerating it.

You can also edit the source for Interactions between components in the Interaction Manager. This is covered in detail in Tutorial 3.

Step 17. We are ready to save and compile our screen. Press the Preliminary Build button:

JDesignerPro will now save and compile the application module you have built. Select the Users folder and enter SalesOrder for the file name and press Save.

Once the Preliminary Build is complete the finished product will appear in Preview. You can now open a store in the Result List and populate the grid by clicking on an order number in the tree. Enter new records in the Grid and use the buttons to manipulate your data. To remove a row click on the row number header to highlight the row and then press the Delete button. It is possible to enter or change multiple rows at once.

We could now go back and add other components to this application or change any of the properties and/or interactions of the existing components. You may also go back and adjust the wizard settings of the Grid1 component simply by selecting it in the Layout View and pressing the Data Wizard Button:

 

Step 18. Now we decide we like the screen as is and prepare it for deployment. Step back to Application Builder and press the Final Build button:

The screen class is saved and compiled. JDesignerPro will move you automatically to the Deployment feature. Please keep JDesignerPro open for the Deployment in Tutorial 4, below. There you will learn how to get your newly-built screen module out to users.

This tutorial showed how to build and compile a data-driven interface over a sales table. You have learned how to layout components on the screen and to link components in the Interaction Manager. We also stepped through the Data Wizard to draw from the database and have those columns matched to their corresponding components.

Please go through Tutorials 3 & 4, Menu Maintenance and Deployment. Tutorial 3 you should do Tutorial 3 which walks you through creating a screen similar to this one without using the Wizard. It will help you become more familiar with the Interaction Manager.