Tutorial 3
Building an Application Module From Scratch
This tutorial walks you through a build of a screen module using the JDesignerPro visual Application Builder using separate Data objects instead of a form Wizard object. This tutorial 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 2 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 "SalesOrder1" in the Users directory when you do. 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. Lets add some components. From the Data folder in the Object Tree, drag a Result List object on to Main. In a few moments the Data Wizard 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. Because the JDPTutorial database is already setup with the default JDBC/ODBC settings, well leave the fields as they are. Press Connect. If you are not on Windows choose one of your own databases. You may need to define a New database on this screen to point to your required database. See Selecting a Database for help on setting up Databases. 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. Click on dbo_sales in the Primary Table list. Then click on dbo_stores in the Secondary Tables list.
Step 7. Now lets 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.
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, SQL or your database.
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 and a.ord_num. The reason we choose these two is that we want to create a tree with stores at the first level and orders underneath each one. The unique key for each branch in the tree would then be a.stor_id and a.ord_num combined.
What this does: Generally the keys must be defined identically for two data components that will be interacting. However, in many cases the key for the Result List will only be a partial key of the component that it will interact with. This is acceptable as JDP will just pass whatever key that it has from one component to another. The receiving component will simply use only the number of columns it receives when creating a SQL. In this tutorial the Grid that we will add next will have a key of stor_id, ord_num and title_id. Therefore stor_id and ord_num is in fact a partial key.
Press Accept and the Data Wizard will move to the Result List tab.
Step 9. 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 by the end user at run time.
Step 10. 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 ", 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.
Your Tree Definition settings should look like this:
Step 11. 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.
When the Result List is displayed it will take the whole screen. Change its position to West under the Properties list. Your form should now look like this:
Step 12. From the Data folder, drag a Detail Grid to Main. It will load the Data Wizard. Select the JDP Tutorial database, press Connect. Then select dbo_sales in the Primary Table list, Press Accept.
Only one Primary Table can be chosen per Data object. Multiple Secondary Tables can be chosen. The Primary table is the one that will show the detail in a master/detail type of screen.
Step 13. Under Define Keys, select stor_id, ord_num and title_id as the Unique Keys.
If you need to reorder the keys you can simply drag them to the required position up or down, like this:
It is important to make sure the columns used in the key definitions match the columns defined in other components that you wish to interact with this one.
Press Accept.
Step 14. On the next screen, check the columns qty, payterms, title_id to be displayed in the grid.
We'll also modify the 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 and Column Text Color to Magenta. Any combination of these settings can be made to enhance your applications.
Step 15. Lets add a date pull down list to the grid. With a.ord_date selected, click the Field Type tab and choose JDPDate from the Field Type pull down. We just created a calendar pop-up object for the Order Date field in the Grid. End users will be able to easily select a date from the pop-up or by typing.
Press Accept. The Detail Grid will build itself and appear on the screen.
With the Grid highlighted in Layout View, be sure its position is Center. 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 drag the Title column header 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. Our application screen lacks buttons. From the Extended Objects list, drag and drop a JDPButtons object on Main.
What this does: The JDPButtons component is an expandable set of buttons that accept both text and graphics. You drop one component and set the number of buttons desired in Properties. These buttons are easy to work with because they automatically line up flush with each other and expand when text or graphics are added.
Step 17. Click on the properties tab and set the #Btns property to 3, press Enter. The JDPButtons component will expand to three buttons. Change the Btn#0 field from "JDPButtons1" to "Save". Change Icon#0 to Save. Change the Btn#1 label to "Reset" and its icon to Undo. Change Btn#2 label and icon to "Delete". If the buttons need to be redrawn, click on the JDPButtons component in Layout View and choose Refresh.
That completes the first half of this tutorial. At this point we will save our application. Click on the Save Application button, the third from left at the top. When the dialogue appears, click on the Users folder, then enter "SalesOrder1" in the filename field and press Save. If you want to take a break, you can open the SalesOrder1 file and restart the tutorial later at this point.
TIP: You can also Save As by clicking two times in a row (not double-clicking) on Main and selecting Save Application As from the pop up menu. Clicking two times on a component in Layout View will bring up the command menu. Single clicking on a component that is already highlighted will also bring it up. Use the Refresh feature to force the whole screen to redraw.
Now we will use the JDesignerPro Interaction Manager. The Interaction Manager is a technology innovation from BulletProof. JDesignerPro is the first tool to have visual selection of the all the events, methods and parameters for a set of components. This allows you to link them together to determine their interactions, build logic, etc. In the process you create an application with very little hand coding.
We are going to link the JDPButtons, Result List and Grid in our SalesOrder1 module. To do this we select the component that causes the interaction in the Layout View and then define the methods that get invoked when the event occurs on that component.
Step 18. Lets start with the Save button. We will build the code necessary to make the Save button save changes made on the Detail Grid.
Select JDPButtons1 in Layout View. Click on the Interaction Manager button:
The Interaction Manager:
Step 19. In the Add New Event tree, open DetailGrid1. It expands to show all available methods for that component. Under Local Methods, select DetailGrid1UpdateRows. It will automatically add this method to the Action Events ACTION_BTN_0 in the Event tree.
Step 20. Notice that the Parameters tab has appeared automatically. Here JDesignerPro shows us the parameters required by the method we selected. In this case String[] is the only one. Select it.
What this does: This tells the Interaction Manager to find and display all of the components in the current application that have a method that returns a value of String[]. This list will appear to the right. In many cases you will also be able to choose from components that are global to any JDesignerPro application. An example would be a method that returns the name of the current user. This can be used by your application to stamp a database record with the last user that changed it.
Step 21. Open the ResultList1 tree in the far right panel. Click on getSelectedKey() under Methods. It will add itself to the String[] parameter. If the DetailGrid1Load method had more than one parameter you would do the same for each parameter in turn. If you simply want to edit the source to fill in the parameters manually you can do this by clicking on the Source tab.
What this does: You have just created all the source necessary to make that button update the database with the new data and changes entered in the Grid. Your Interaction Manager should look like this:
Step 22. The next button is the Reset button. Click back on the Add New Event tab. Under DetailGrid1 / Local Methods click and hold on DetailGrid1LoadGrid. Then drag it and drop it onto ACTION_BTN_1 in the Event tree. It will be added as an event for that button.
TIP: If you accidentally add a method to the wrong Action Event, click on it twice in the Action Event tree and choose Remove Method from the Pop up menu.
Click on String[] under Parameters. The lists to the far right will refresh. Open ResultList1 at the right and choose getSelectedKey() under Methods. The Java source code is now built for that button.
Step 23. The last button is the Delete button. Ultimately we want highlighted rows removed from the Grid when this button is pressed. In the Add New Event tree go to DetailGrid1 / Local Methods. Drag the DetailGrid1DeleteRows method and drop it onto ACTION_BTN_2. Then click String[]. Next click on getSelectedKey in the ResultList1 / Methods tree at the far right.
Your Interaction manager should look similar to this:
Step 24. Now we will link the Result List to the Detail Grid. While in the Interaction Manager, select ResultList1 in the Layout View
Step 25. Under Add New Event, DetailGrid1 / Local Methods click on the DetailGrid1LoadGrid method. Click on String[] in the Parameters window, then, as you did earlier, open ResultList1 and choose getSelectedKey() under Methods.
The steps we just did create code that says, "When a branch is selected in the Result List tree, take the unique key of the selected branch and populate the grid with rows from the table that correspond to that key."
For more help with the Interaction Manager, look at the included Example Applications for ideas about how to build various applets. Load one of the them and look at the Interaction Manager. The Interaction Manager and Code Window will show you how those work so you may learn by example.
Click on the Layout View button:
Step 26. 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.
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.
To add to this module, we might build a set of fields from the Columns component, to be the Master and make the Grid the detail of a Master/Detail screen. We could link both the Columns and the Grid to the Result List so both are populated.
Step 27. 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 Tutorial 4, Menu Maintenance and Deployment.