The Novice's Corner - Understanding Templates And Embeds

by Dave Harms

Published 1999-03-19    Printer-friendly version

In the first article in this series I examined the some of the basic concepts behind Clarion's application generation technology and reviewed the initial steps most Clarion developers take when creating an application. If you follow the approached discussed in that article you can get an application up and running in short order. Chances are, however, that it won't be quite the application you want, and you'll need to make some significant changes.

If you're working within the Application Generator (AppGen) environment, as almost all Clarion developers do, then much of what you do is predicated on the use of templates, as explained in the previous article. Unlike earlier versions of Clarion, which had a fairly monolithic template structure, Clarion for Windows builds applications out of several different kinds (or classes, though in this case the term has nothing to do with object orientation) of templates

The Template Registry

You can see which templates are available by closing any open application and choosing Setup|Template Registry from the main menu. Figure 1 shows the Template Registry main window.

Figure 1: The Template Registry, showing the ABC template chain.

Templates are listed in the registry by type. Keep in mind that the templates are simply text files containing template language (and sometimes also Clarion language) statements. You can register and unregister template sets (also called chains) as you wish, although you should keep in mind that not all templates are created equal, and some are less dispensable than others. Most Clarion applications are built on either the ABC or Legacy template chains and many of these apps also use a number of third party templates which provide additional features but generally do not replace the standard Topspeed-provided templates.

Template Files

You'll see two extensions for template files. The Template Registry can load in TPL files, and TPL files may contain INCLUDE statements that point to TPW files, which contain additional template code. For instance, the ABC template chain's TPL file is called ABCHAIN.TPL, and that file INCLUDEs a number of TPW files, all of which begin with AB (and which can be found in the \template directory). If you purchase a third party product which comes with a template (and most do) you'll receive at least one TPL file and perhaps TPW files, depending on how the product author has chosen to write the templates.

Application/Module Templates

The first two templates shown in Figure 1 are the Application and ABC-Default Program templates. These templates control global options for application generation. Similar templates exist in the legacy template chain (CW.TPL). These templates control core AppGen functionality and do it well enough that there are, to my knowledge, no third party replacements available, or really needed (at least not for generating Clarion code). Some developers do make changes to these templates but such customization is less necessary with the ABC templates than with the legacy templates. If you're starting out with Clarion, you can quite safely ignore the Application and Default Program templates.

Below these two templates is a category called Modules. Module templates control the creation of source modules, and there are in ABC five module types: ExternalDLL, ExternalLib, ExternalObj, ExternalSource, and GENERATED. Again, if you're just starting to work with Clarion, you really don't need to know about these. The one you'll use on a regular basis is GENERATED, but as this template will be called as necessary when you create procedures, its operation is almost completely hidden.

All of the other module types allow you to use non-generated procedures which may be in source, lib, obj, or dll form. If you're using external procedures (most likely because your app has grown large enough that it becomes practical to split it up into dlls) then you may well find that you're better off using source includes rather than these templates. But that's a subject for another article.

Procedure Templates

The place you will begin encountering templates is at the procedure level. Any time you create a procedure (except when you do so using an application wizard or a wizatron) you'll be asked what type of procedure you want. The available choices in the ABC template chain are as follows:

• Browse Displays records from a table (file) in a list box and optionally allows the user to add/delete/update the records
• External A procedure that is defined outside the application (this will result in the creation of one of the external modules)
• Form A window that allows for changing a table (file) record. Tabs are automatically used so that large records can still be displayed. If child records exist corresponding browses with update buttons will be added (and update forms for the child browses will be created as needed)
• Frame A main window for an MDI (Multiple Document Interface) application. You need to create your main procedure using this template if you want to use MDI child windows in your application. MDI windows are clipped by the application frame and if moved beyond the frame cause scroll bars to appear on the frame. This is the default for Clarion applications.
• Menu A main window for an SDI (Single Document Interface) application.
• Process A procedure that loops through a specified set of records and (typically) updates those records.
• Report A report with a progress bar and optional previewing.
• Source A procedure for which you must supply all of the code. This is just a framework for the procedure.
• Splash A splash window that appears while the program is loading.
• ToDo A placeholder for a procedure named but not yet defined.
• Viewer View an ASCII file in a list box.
• Window A generic window. You have to populate the controls you want.

The procedure templates you'll most commonly use are Browse, Form, and Report. If you don't use an application wizard or wizatron to create your initial application then you'll also need to create either a Frame (most likely) or a Menu (quite unlikely) procedure as the main menu. You may also want to create a splash procedure.

You may also want to use the Window procedure template. In fact, most of the procedures in any given application (that is, the Browse and Form procedures) are really nothing more than a combination of the Window procedure and one or more control templates.

Control Templates

While Clarion for Windows 1.0 was in beta testing the then template set (what is now referred to as the Legacy templates) went through a radical transformation. In the early betas the templates that created a browse or form were monolithic. There was one template for a browse, another for a form, another for a report, and so on. This worked, and was in keeping with the approach of the ancestor to the template, the model file, but it wasn't the most efficient use of code.

Enter control templates. In any procedure a certain amount of code is devoted to managing standard window behaviour, and a certain amount is used to manage windows controls.

A control is anything that appears on the screen, such as a button, or an entry field, or a list box. A control template is a collection of template code and Clarion language code which acts as a wrapper for a control. And by abstracting the control code into a template, Topspeed made it possible to plug and play with a variety of controls on the same window, without the window having to know about these controls ahead of time. Do you want a list box on your update form? No problem? Entry fields on your browse? Go right ahead.

If you want to stick with the standard approach, you can still can recreate any browse or form by starting with a window procedure and populating the appropriate control templates. Simply bring up the procedure properties screen, click on Window, and then choose the Control Template icon from the Control Toolbox (see Figure 2).

Figure 2: The Control Toolbox with the Control Template icon highlighted

When you populate a simple control onto a window all that happens is the control is added to the window structure. When you populate a control template you're adding much more. Control templates can specify default size and position attributes for the control. They can specify a number of controls to be populated at once. They can require you to enter certain information, such as which field or file the control represents. They can provide prompts for various kinds of optional information. In short, control templates allow you to add some fairly complex functionality to a procedure without having to deal with the code directly.

If the code template has prompts, you can see them by right-clicking on the control and choosing Actions, or by selecting the control and choosing Edit|Actions from the menu. Figure 3 shows the Actions prompts for a standard Browse box.

Figure 3. Browse control template properties

Some control templates are also conditional on other control templates already being populated on the window. You can't put browse update buttons on a window unless there's at least one browse on the window - if there's no browse, the update control template won't even appear in the list.

The ABC templates include control templates for browse boxes, update buttons, query buttons, entry control lookups, file lookups, OLE controls, date/time stamps, and much more. Control templates are also a particularly good vehicle for third party vendors because they can provide standard appearance and behaviour for their controls without requiring the user to write supporting code.

Code Templates

Code templates are usually (though not always) smallish blocks of code that you wouldn't want to have to keep typing over and over again, but which don't necessarily belong to a control or other type of template. Code templates are inserted at embed points, which are discussed below. These templates often have prompts much as control templates do, and the choices you make in the prompts determine how the code is generated.

Extension Templates

Extension templates are a bit of a hybrid of control templates and code templates. If you go to the Extensions list on the procedure properties window, you'll see it includes any control templates which have been populated on the window. Actual extension templates do not have associated controls, however. Often they're used to extend the functionality of an existing control template, or sometimes the procedure template.

Group Templates

Group templates are a somewhat special case, as are the application templates. You don't use them directly as a developer. They're there for the benefit of the template author, and can function either as included template code, or as functions written in the template language.

Templates and Embed Points

Although there's a tremendous amount you can do with templates, they won't always do everything you want them to do. Sometimes (perhaps frequently) you'll want to add your own code to the application.

Clarion is tightly focused on automating code creation. Many of the things you can do with Clarion are possible only because of the work of the templates, but the price is that you can't simply go to the source code and make your changes, because these changes will be lost when you next generate the procedure.

One of the restrictions of the early DOS versions of Clarion was the limited number of places where you could put source code. Most of the logic that determined where source code could be placed was under the control of the Designer application (the forerunner to the Application Generator). In Clarion for Windows, the AppGen has been dumbed down somewhat, if you like, and the templates have been given a far greater level of control over where code can be embedded.

If you click on Embeds on the procedure properties window you'll see a rather lengthy list of embed points. In the ABC templates, most of these will be inside class methods.

For each embed point there is, somewhere in the templates, a template statement that begins with #EMBED. If you want an embed point where none exists (this is not very likely) you can always find the appropriate point in the templates and add one. (You should also inform Topspeed of your requirement as they will most likely want to add the embed point also.)

Each time you use a template, whether it's a procedure template or a control template or any other kind, if that template contains #EMBED statements, those embed points will appear in the embed list.

You can also use the Source view to see embed points in the context of generated code. From AppGen main window right click on the procedure and choose Source, or from inside the embed list click on the Source button. This view of the source code shows you all of the source that is potentially generated, rather than just the code that will be generated. As you can see, most embed points cause some standard code to be generated along with your embedded source code.

What About Object-Orientation?

One of the benefits of Clarion's application generation technology is that you don't need to know a whole lot about the underlying language to get things done. The templates provide a simplified interface to the underlying code which, if you're using the ABC templates, is the ABC class library. Of course the more you know about how the underlying code works the more you'll be able to leverage that functionality, but the templates make it possible for someone with minimal or no OO programming experience to effectively use OO code.

Clarion's template technology works equally well with procedural and object-oriented code, although OO code puts less stress on the template language. In a procedural environment the templates have to do much more work generating the core logic, whereas in an OO environment the templates mainly set up calls to the class library, and the core logic is contained in Clarion-only code which makes it a lot easier to maintain.

Templates And Embeds - Finding The Balance

For all Clarion programmers except those who write everything by hand, and those who write nothing by hand, application development is an exercise in balancing templates and embedded source. If you're writing a great deal of embedded source, then there's a good chance that some or much of this code could be better placed in templates.

Templates aren't the answer to everything, of course. There are downsides. When you change a template you have to reload the application, and some template changes force global regeneration of the application source, which can take time, particularly if you're doing a lot of changes. As well, traditional means of code reuse such as class libraries and plain old procedural source libraries may be useful.

Templates become particularly useful in two situations. First, where the code that's to be generated is variable, templates offer tremendous flexibility. The template language is a superset of the Clarion language and has a full range of constructs which you can use to generate code based on prompts answered by the developer.

Templates are also invaluable where you need information that is specific to the application, such as fields in a data file, controls on a window, and so forth. The templates have full access to everything the data dictionary and the application generator know.

If you'd like to learn more about how templates work, I strongly suggest reading through the template language section in the help. There's a vast amount of information, and while it might not all make sense right away it'll give you a good idea of the power of the template system.

Information about specific Clarion templates is also available in the general help. Search for Templates and then click on the Display button to bring up a list of available template help topics.

Next in the Novice's Corner - Designing Databases

---

David Harms is an independent software developer and the editor and publisher of Clarion Magazine. He is also co-author with Ross Santos of Developing Clarion for Windows Applications, published by SAMS (1995), and has written or co-written several Java books. David is a member of the American Society of Journalists and Authors (ASJA).

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942