Getting Started-2-Tier

An additional screen is provided in tutorstd.lib that uses a grid widget to display a list of distributors. In this lesson, you enhance this screen so users can query the database for a specific distributor record through two different search criteria: either a distributor ID number or a partial or full name string. The transaction manager uses user input to generate automatically the appropriate SQL query statement. If a query field is empty, the transaction manager excludes its data from the SQL generation.

In this lesson you learn how to:

• Resize the screen and copy widgets to it from a repository entry.

• Specify and define more than one widget to act as a query-by-example field, so users can use a variety of search criteria to query the database.

In this lesson, you open a wizard-built screen from the tutorial library. You then save it to client.lib, and enhance the user interface by including query fields.

1. If necessary, invoke the editor and connect to the database.
2. Choose ViewLibrary TOC.

   The Library TOC opens.

   

3. If tutorstd.lib is not among the list of open libraries:

   • From the Library Table of Contents, choose Open under the list of open libraries. The Open Library dialog opens.
     

   • Select tutorstd.lib.

   • Choose Open. The Library TOC redisplays.

4. Select tutorstd.lib from the list of open libraries and lesson10.clt from the list of library members. Choose Open.
   

   The lesson10.clt screen opens in the editor workspace.

   

   This screen is a master-only screen for the distributors table and uses a grid format. The grid contains three of the table's columns: distrib_id, distrib_name, and distrib_phone.

5. Choose FileSave AsLibrary Member. The Save Screen dialog opens.
6. Save the screen as dstslect.scr in client.lib.

Increase the screen's vertical dimension so you can add other widgets to it.

7. In the editor workspace, resize the dstslect.scr client screen in one of the following ways:

   • Drag on the upper or lower edge of the screen until it is the size you want.
     

   • Click in an empty area of the client screen to deselect all widgets.

     The screen properties are displayed in the Properties window. Under Geometry, set the screen's Height property to the desired size (default is in grid units).

Make room for more widgets above the grid widget by moving the grid widget and push buttons down to the screen's lower portion.

8. Choose EditSelect All and drag the widgets to the bottom of the screen, leaving space at the top for more widgets.
   

You want to populate the screen with widgets that are associated with a particular database table. You can access these widgets in the repository, just as the screen wizard does.

9. If the repository is not open, choose FileOpenRepository, and select data.dic in the proltut directory.
10. Choose FileOpenRepository Entry.

    The Open Repository Entry dialog opens and displays the contents of the data.dic repository.

    

11. Select the distributors repository entry and choose OK.

    The distributors@[Repository] window opens.

    

You can use widgets from the repository to serve as query fields on the dstslect.scr screen. When you create a copy of a repository widget, the copy has an inheritance link to its parent in the repository. You can use inheritance to propagate changes from the repository to application screens, as shown in the next lesson.

In the following steps, you copy distrib_id and distrib_name from the repository to the client screen dstslect.scr. The copies inherit their property values from the repository.

12. With focus on the distributors repository screen, Shift+click to select the Distrib_id label and its corresponding text widget (distrib_id), and the Distrib_name label and its corresponding text widget (distrib_name).

    Selecting multiple widgets creates a selection set, which is useful for defining common property values. The first widget you select is the dominant widget. You can Ctrl+click on another widget in the selection set to make it dominant.

More About Selecting More than One Widget

When more than one widget is selected, the first one you select is considered the dominant selection and is indicated by little solid black squares around its border (square brackets in character mode); all other widgets in the selection set are indicated with hollow boxes (curly braces ({}) in character mode). The position and size of the dominant widget determines how the other widgets in your selection set will align or resize when you use Edit menu or toolbar options.

There are a variety of ways to select multiple widgets:

• Press Shift+click on a widget to add or remove it in the selection set.

• Press Cntl+click to select a new widget and make it dominant

• With the mouse button pressed, drag a bounding box, also known as a rubber band, around the desired widgets. Any widgets that fall within the rubber band boundary are selected.

• Use the Widget List.

13. Drag the widgets from the repository screen distributors to the top of the screen dstslect.scr.
    

14. (Optional) Bring focus to the distributors repository entry and choose FileClosedistributors. The repository window closes.
    

It is good practice to name all data entry widgets, especially if you need to access them programmatically. Names of all widgets on a screen must be unique. Because the dstslect.scr screen already contains widgets named distrib_id and distrib_name, the copies from the repository are left unnamed. You need to assign different names to the copies via their Name property.

15. Select the copied text widgets on the client screen dstslect.scr and set each one's Name property (under Identity) as follows:

    • distid_qbe—This widget will serve as a query-by-example field.

    • distname_qbe—This widget will serve as an alternative query-by-example field where users can enter a full or partial name string.

Use database properties to provide the transaction manager with information it needs: identify the query fields, define the data to retrieve, and ensure that query field data is not used to update the database.

16. Select the distid_qbe and distname_qbe widgets.
    

17. Under Database, select CHANGE DATA. Under CHANGE DATA, set the following property for both widgets:

    • Use In Update = No

      These settings ensure that the data in these widgets is ignored by SELECT or UPDATE statements of automatically generated SQL.

18. Under Database, select NEW DATA. Under NEW DATA, set the following property for both widgets:

    • Use In Insert = No

19. Under Database, select FETCH DATA. Under FETCH DATA, set these properties for both widgets:

    • Use In Select = No

    • Use In Where = Yes

      Related subproperties display. Leave the Operator property set to =. At runtime, when an ID is entered in distid_qbe, Panther searches the distrib_id column in the distributors table for a record (or row) with the same distributor ID.

20. Select the distname_qbe widget.
21. Under the Use In Where property, set the Operator property to %like%.
    

    The percent sign (%) sign is a wildcard matching any sequence of zero or more characters. This pattern matching operator tells Panther to search the database for all records that contain the string in the distname_qbe field.

22. Save the screen (press F6).

You can try it out!

23. Invoke the screen from your browser by supplying this URL:

    http://hostname/cgi-bin/webAppname/dstslect.scr

    The Select Distributor screen opens.

    Or choose FileTest Mode to view the screen in a GUI environment.

    Note: You may need to start the web application server before viewing the screen in your browser.

24. Type Vid in the Distrib_name field.
25. Choose .

    All distributors that have Vid in their name are listed in the grid.

    

26. Choose .
27. Type 6 in the Distrib_id field and choose .
    

    Panther looks for a record with an exact match—a distrib_id with a value of 6. The record corresponding to ID 6 is displayed in the grid.

    ---

You enhanced a screen so users can search for distributors by name or ID. You did this by performing these actions:

• Opened the distributors repository entry and copied the desired widgets to your client screen.

• Assigned the appropriate database properties to the copied widgets.

What did you learn?

You learned:

• Widget names must be unique on a screen.

• Copying widgets copies their property settings as well.

• The editor provides the editing tools you need to enhance the user interface.