Clarion Community Help

In our previous lessons, we focused on the fundamentals of application design, and the templates and tools that support it. This lesson provides an overview of the additional templates available to you, with links and references to appropriate documentation.

Procedure Templates

In previous lessons, we learned that a procedure is a series of Clarion language statements (source code) that perform a task. A Procedure template is an interactive tool that (with the help of Clarion's IDE) requests information from you, the developer, and then generates a custom procedure for just the task you specify. A Procedure as stored in a Clarion application (.app) file is really a specification that the development environment uses to generate the procedure source code. The specification includes the Procedure template and your answers to its prompts, the WINDOW definition, the REPORT definition, other local data declarations, embedded source code, etc.

Clarion provides a rich assortment of task oriented Procedure templates with which you can rapidly develop database applications. In Getting Started, the lesson introduces a few procedure templates; the Application Generator lessons in Learning Clarion introduces more. This chapter describes all the procedure templates and their prompts.

Using Procedure Templates

You use procedure templates by selecting the template based on the general task you want it to perform, such as browsing or searching data (Browse template), changing data (Form template) or reporting data (Report template). You select the template when you create the procedure (see Select Procedure Type in the core help for more information). Then you refine the template-generated code to fit your specific task by using the Procedure Properties dialog to answer template prompts and to access other development environment tools such as the Window Designer and the Report Designer.

In the Select Procedure Type dialog, use the Defaults and Wizards tab selections for the majority of your new procedure designs. The Templates tab contains selections that provide a minimum starting point for all procedure templates, and is primarily useful for the basic Window, Source, and External procedure templates.

Procedures as Containers

Procedures can contain data structures such as WINDOW structures, REPORT structures, and the controls within those structures. And Procedure templates can contain other templates'Control and Extension templates that present additional opportunities to customize the procedure.

Procedures Contain Controls

Procedure templates provide standard prompts for any BUTTON, ENTRY, or CHECK controls you add to the procedure's WINDOW. You access these prompts through the Properties dialog for these controls. For each ENTRY control, for example, the procedure template provides prompts to let you use the ENTRY as a lookup field. For a CHECK box, the procedure template provides prompts to let you update variables and hide or unhide controls based on the state of the CHECK box.

Procedure templates provide standard embed points for controls you add to the procedure's WINDOW. Generally, there is an embed point for each event the control generates. Embedding code into these embed points generates code that evecutes when the control generates the event. See ABC Template Embed Points for more information.

Procedures Contain Other Templates

Finally, Procedure templates can contain other templates'Control templates and Extensions templates which provide their own development environment prompts and embed points, and their own runtime functionality.

Thus, a Procedure and its template act as a container which automatically provides support for many layers of functionality and customization. And the Application as stored in the development environment, acts as a container for the Procedures and their templates.

Many of the ABC Procedure templates already contain Control templates. Control templates generate code to define and manage a specific control, including loading data in and out of the control. In fact, the unique set of Control templates within a Procedure template are what determine the template's primary purpose or task. For example, the Browse Procedure template is a generic Window Procedure template which contains the BrowseBox and BrowseUpdateButtons Control templates.

Inter-Procedure Communication

Clarion's template generated procedures use a simple system of global variables and EQUATEs to communicate with each other.

The procedures use two global variables named GlobalRequest and GlobalResponse. The calling procedure uses GlobalRequest to tell the called procedure what database action to do. The called procedure uses the GlobalResponse variable to tell the calling procedure the result of the requested database action.

Whenever a template-generated procedure calls another template-generated procedure, the calling procedure sets the value of GlobalRequest to one of the EQUATEs declared in ABFILE.EQU as follows:

The called procedure checks the GlobalRequest variable and tries to carry out the requested action. The called procedure indicates success or failure by setting the value of GlobalResponse to one of the EQUATEs declared in ABFILE.INC:

Summary of Standard Procedure Templates

Extension Templates

Extension templates add functionality to procedures, but are not bound to a control or a single embed point. Each Extension template has one well-defined task. For example, the DateTimeDisplay template lets you display the date, time, or both on a WINDOW.

From a Procedure Properties dialog, add an Extension template by pressing the Extensions tab.

Only Extension templates may be added and deleted using the Extensions tab. Control templates may be modified here, but may not be added or deleted. Use the Window Designer to add or delete Control templates.

Control Templates

A control is almost anything you see on a window or a report. For example, a check box, a push button, an entry field, and a list box are all controls.

Control templates generate source code to declare controls and manage their associated data. For example, the BrowseBox Control template not only generates source code to declare a list box, it also generates code to load data into a QUEUE, then display the QUEUE in the list box with complete scrolling, searching, sorting, updating, and mouse-click selection capability.

Control templates can also control file I/O; for example, the SaveButton Control template can warn that changes were made if the end user tries to close the window without saving the changes to disk.

Generally, it is to your advantage to use a Control template rather than a simple control.

Adding Control Templates

When starting with a new procedure, to add a Control template:

1.In the Window Designer or Report Designer, add a Control template by selecting the desired template in the Control Templates Pad, and DRAGing to the target window location.

The Designer places one or more controls (the type of controls depend on the Control template) in the window or report.

2.RIGHT-CLICK on the control, then choose Actions from the popup menu to access the Control template prompts.

These prompts define and customize its functionality.

3.Select the Properties Pad dialog to set the control's appearance, location, and other functionality.

Once a Control template is added to a procedure, you can access the Control template prompts via the Extensions tab.

Code Templates

Code templates generate source code into an embed point that you specify, and sometimes into other embed points as well. Their purpose is to make procedure customization quick and easy. Each Code template has one well-defined task. For example, the Initiate Thread Code template simply starts a new execution thread, and no more. Typically, the Code template provides a dialog box with prompts and instructions. Add Code templates to your procedure with the Embedded Source dialog.

Utility Templates

In Lesson 2, we discussed the power of the Application Wizards, and how they can be used to quickly generate feature-rich procedures and whole applications.

Wizards are actually categorized as a form of Utility template. By definition, a Utility template is a template that acts externally to an application on information read from the active dictionary or application itself.

All utility templates generate an ASCII text-based file. The main difference between the Wizards and other Utility templates is that Wizards generate information that is read into an application file, where non-Wizard Utility templates read information out of an active dictionary or application for use with external utilities, documentation, or third-party products.

Module Templates

In Clarion terms, a module is defined as a source or library file used for a given project. In the Application Generator, there may be times when you need to include an external source module or library into your application design. The Module templates allow you to do this effortlessly within the Application Generator.

To add a module to an existing application, choose Application Insert Module from the Application Generator's Main Menu.

Next: Lesson 14 - The Source Procedure