Clarion Community Help

The Products Table Procedures

Now that we've created the Customer Browse procedure, we can reuse much of that work for the next procedure by copying the procedure, then changing its columns. In this chapter, you'll copy the BrowseCustomers procedure to create the BrowseProducts procedure.

You will also use “Embed points” to write “embedded source code” to call the BrowseProducts procedure from your application's menu and toolbar. This will introduce you to the numerous points at which you can add a few (or many) lines of your own source code to add functionality to any procedure.

Starting Point:

The LCLESSON.APP file should be open, and the Application Editor (tree).

Copy the Procedures

As you recall, when you created your Browse Products menu item, and the toolbar button labeled “Products,” you didn't specify a procedure to call when the end user executed them. We'll start by creating the procedure to call.

1.Highlight the BrowseCustomers procedure in the Application Tree dialog.

This is the procedure you will copy.

2.Choose Application Copy Procedure from the main IDE menu.

The New Procedure dialog appears.

3.Type BrowseProducts in the entry control then press the OK button.

Because the UpdateCustomer procedure is nested under the BrowseCustomers procedure (the one you are copying), the Procedure name clash dialog appears. This offers you options on how to handle the clashing procedures.

4.Press the Prompt button.

By pressing the Prompt button, you tell the Application Generator to let you have the opportunity to rename all the clashing procedures, or not.

Another warning message box appears to inform you of a specific duplicate procedure name.

5.Press the Rename button.

The Alternative Procedure dialog appears.

6.Type UpdateProduct in the entry control, then press the OK button.

The BrowseProducts and UpdateProduct procedures appear in the Application Tree. They look “disconnected” from the other procedures because no other procedure calls them (yet). We'll do that next.

Working with Embed Points

The Clarion templates allow you to add your own customized code to many predefined points inside the standard code that the templates generate. It's a very efficient way to achieve maximum code reusability and flexibility. The point at which your code is inserted is called an Embed Point. Embed points are available at all the standard events for the window and each control, and many other logical positions within the generated code.

In this example, you add embedded source code'using a Code template that will write the actual source for you'at the points where the end user chooses the Browse Products menu item, and at the point where the end user presses the Products button on the application's toolbar.

Name the procedure to call to Browse the Products

1.RIGHT-CLICK on the Main procedure in the Application Tree.

There are several ways to access the embedded source code points within a procedure. Two of them appear on the popup menu that you now see.

The first is the Embeds selection, which calls the Embedded Source dialog to show a list of all the embed points within the procedure.

The second is the Source selection, which actually generates source code for the procedure and calls the “Embeditor” (the Text Editor in embed point edit mode) to allow you to directly edit all the embed points within the context of generated source. The generated source code is “grayed out” to indicate that you cannot edit it, and every possible embed point in the procedure is identified by comments, following which you may type your code.

There are advantages to each method of working in embed points, so we'll cover both methods during the course of this lesson. First, we'll use the Embedded Source dialog.

2.Choose Embeds from the popup menu.

The Embeds Tree dialog appears, allowing access to all the embed points in the procedure. You can also get here from the Embeds button on the Procedure Properties window, but the popup menu is quicker. This list is either sorted alphabetically or in the order in which they appear in the generated source, depending on whether you have the Sort Embeds Alphabetically box checked in Setup Application Options.

3.Press the Contract All button on the right of the window.

This will make it easier to locate the specific embed point you need.

4.Locate the Control Events folder, then CLICK on its + sign to expand its contents. You can easily locate this by entering BrowseProducts in the entry locator above the embed tree. It works, even when the tree is totally collapsed.

The menu selection is a control, just as an entry box on the window is.

You'll notice that there are some up and down buttons and a spin box at the right side of the window that allow you to select a Priority'these are important. The templates generate much of the code they write for you into these same embed points. Sometimes, the code you want to write should execute before any template-generated code, and sometimes it should execute after, and sometimes it should execute somewhere between various bits of generated code. The exact placement of your code within the embed point is determined by the Priority number. This provides you with as much flexibility in placing your embed code as possible. The Priority numbers themselves do not matter, but the logical position within the generated code does, and that's why this dialog also shows comments which identify the embed priorities. Don't worry, there's more coming on this issue later that'll help make it clearer.

5.Locate the ?BrowseProducts folder, then CLICK on it to expand it.

6.Highlight Accepted then press the Insert button.

The “Accepted” event for this menu selection marks the point in the generated code that executes when the user chooses the menu command.

The Select embed type dialog appears to list all your options for embedding code. You may simply Call a Procedure, write your own Clarion language Source in the Text Editor, or use a Code template to write the source code for you. This is one advantage to editing embed points from within the Embedded Source dialog'you can use Code templates to write the code for you instead of writing it yourself.

7.Select the InitiateThread Code template, then press the Select button.

A Code template usually provides just a few prompts and instructions on its use. It gathers the information it needs from you to write its executable code, which it then inserts into the standard generated code produced by the Procedure template directly into this embed point. This Code template is designed to start a new execution thread by calling the procedure you name using the START procedure.

8.Choose BrowseProducts from the Procedure Name dropdown list.

This names the procedure to call when the user chooses the menu item. This is the name of the procedure you previously copied.

9.Press the OK button.

Name the procedure to call for the Products toolbar button

At this point, you could do the same thing to call the BrowseProducts procedure from the Product button. However, there's an easier way to write this code again'just Copy and Paste it from one embed point to another!

1.CLICK on the Copy button located on the toolbar.

The Code template you just added should still be highlighted, so this will copy it to the Windows clipboard.

2.Locate the ?ProductsButton folder (in the same Control Event Handling folder you are already in), then CLICK on it to expand it.

3.Highlight Accepted then press the Paste button located on the toolbar.

The Procedure name clash dialog appears again to warn you that you've already called this procedure once.

4.Press the Same button.

Now this embed point will generate the same code as the previous one.

5.Press the Save and Close button.

The BrowseProducts procedure now “connects” to the Main procedure. Now you can customize the copied procedures for the Products table.

Modify the Browse

Change the table for the browse list control

1.RIGHT-CLICK the BrowseProducts procedure and choose Window from the popup menu.

2.RIGHT-CLICK on the list box control and choose List Box Format… from the popup menu.

3.In the List Box Formatter press the Delete button repeatedly until all the columns are removed.

4.Press the Add Field button.

5.Highlight the Customer table in the Tables list, then press the Delete button.

6.Highlight the <;ToDo> which replaces the Customer table, then press the Add button.

7.Highlight the Products table then press the Select button.

The Select Column dialog now lists the correct table and columns for this procedure.

8.Press the Change button, then select ProdDescKey from the Change Access Key dialog.

The Select Column dialog now lists the correct table and columns.

Re-populate the columns

1.Highlight ProdNumber in the Columns list, then press the Select button.

2.Set the RightBorder and Resizeable properties to TRUE, and verify that the Width property is set to 24.

3.Press the Add Field button.

4.Highlight ProdDesc in the Columns list, then press the Select button.

5.Set the RightBorder and Resizeable properties to TRUE, and verify that the Width property is set to 120..

6.Press the Add Field button.

7.Highlight ProdAmount in the Columns list, then press the Select button.

8.Set the RightBorder and Resizeable properties to TRUE, and verify that the Width property is set to 32..

9.Press the Add Field button.

10.Highlight TaxRate in the Columns list, then press the Select button.

Notice the default Justification is Decimal, and the Data group's Indent spin box is still set to twelve (12) from the previous column.

11.Press the OK button to close the List Box Formatter.

Don't worry about the buttons on top of the list box. Remember, these are just the “hidden” buttons that the toolbar update buttons call.

Change the name of the window

1.CLICK on the sample window caption bar.

2.Type Browse Products in the Title property of the Property Pad, then press TAB.

Remove all tab controls

1.CLICK immediately to the right of the KeyZipCode tab to select the entire property sheet.

To be sure that you have CLICKed in the right place, look at the Property Pad and make sure that its Use entry displays ?Sheet1. If it does not, try again until it does.

2.Press DELETE on your keyboard.

All of the tabs disappear.

Add an incremental locator

If the list of Products to display is very long, the user can do a lot of scrolling before finding the specific Product they want. By default, all BrowseBox Control Templates have a “Step” row locator that allows the user to press the first letter of the value in the sort key column to get to the first row that begins with that letter.

Sometimes with large databases however, the user needs to enter the first several letters to get close to the row they want. An Incremental locator provides that functionality by specifying an string control for the user to see the information they type. As they type, the list scrolls to the first row matching the data the user entered thus far. This works best with STRING keys.

1.If the Control Toolbox is not opened, open it now by selecting View Toolbox from the IDE Menu.

2.CLICK on the Str STRING button on the control toolbox.

3.The mouse cursor changes as you move it across the window. Drop the string above the list box on the left side of the window. You should now see String 1.

4.RIGHT-CLICK on the string control and choose Properties.

5.In the Properties Pad, set the IsPicture property to TRUE.

6.In the Use property, type PRO:ProdDesc, or press the ellipsis button to select it from the column list.

7.Press the Save and Close button to exit the Window Designer.

8.Press the Save and Close button to exit the Window Designer Edtor.

9.Choose File Save, or press the Save button on the tool bar.

Clean up the alternate sort orders

1.RIGHT-CLICK the BrowseProducts procedure and choose Extensions from the popup menu.

The Extension and Control Templates dialog appears. This dialog lists all the Control templates in the procedure and their Actions prompts.

This dialog also allows you to add and maintain Extension templates to the procedure. Extension templates are very similar to Control templates, in that they add specific functionality to the procedure, but an Extension template's functionality is not directly associated with any control(s) on the window. In other words, Extension templates add “behind the scenes” functionality to a procedure that don't directly affect the user interface.

A very good example of Extension templates comes in Clarion's ASP (Active Server Pages) product. Clarion ASP contains (among its other development tools) a set of Extension templates, which automatically “translate” a Clarion procedure into dynamic ASP pages.

2.Highlight Browse on Products then press the Properties button.

3.In the Browse on Products dialog, press the Locator Behavior button.

4.Select Incremental from the Locator drop list then press the OK button.

This completes the requirements for the Incremental Locator. The key column of the sort order (in this case PRO:ProdDesc) is the default locator control.

5.Select the Conditional Behavior tab.

6.Press the Delete button twice.

This removes the two conditional expressions we entered for the BrowseCustomers procedure.

7.Press the OK button.

8.Press the Save and Close button to return to the Application Tree.

Creating the Form Procedure

When you renamed the reference to the UpdateCustomer procedure while copying BrowseCustomer to BrowseProducts, it made the UpdateProduct procedure a “ToDo” procedure. Therefore, we need to create a form to update the Products table.

Select the procedure type for UpdateProduct

1.Highlight UpdateProduct, then press the Properties button.

2.Select the Defaults tab, choose FORM (Add/Edit/Delete) and then press the Select button.

3.Open the Data / Tables Pad if not already opened.

4.In the Data / Tables Pad, highlight the <;ToDo> table, then press the Add button.

5.Highlight the Products table then press the Select button.

6.Press the Window tab and press the Designer button to enter the Window Designer to design your form.

Populate the columns

1.We will use the Data / Tables Pad in this section to populate our Form.

2.In the Data / Tables Pad, select the Products table as shown below:

3.DRAG ProdNumber to the upper left of the window, and DROP.

This automatically places both the prompt and entry box for the column near the top left corner of the window.

4.DRAG ProdDesc just below the ProdNumber prompt, and DROP.

This automatically places both the prompt and entry box for the column immediately below the last column that was placed.

5.DRAG ProdAmount just below the ProdDesc prompt, and DROP.

6.DRAG TaxRate just below the ProdAmount prompt, and DROP.

Change the form window caption

1.CLICK on the caption bar of the sample window.

2.Type Product Form in the Title property of the Property Pad then press TAB.

Exit the Window Designer, and save your work

1.Press the Save and Close button on the toolbar to close the Window Designer (save your changes).

2.Press the Save and Close button in the Window Designer Editor to close it.

3.Choose File Save, or press the Save button on the toolbar to save your work.

The Products table update form window is completed.

OK, What Did I Just Do?

Here's a quick recap of what you just accomplished:

Now that you're thoroughly familiar with Procedure Templates, we'll go on to use some Control and Extension Templates.

Click here to jump to the next lesson