skip to main content
OpenEdge Development: ADM and SmartObjects
Developing ADM Extensions : Creating a new class at the bottom of the ADM class hierarchy
 
Creating a new class at the bottom of the ADM class hierarchy
You use the AppBuilder’s New ADM Class tool to create a new ADM class. There are three steps in creating a new class:
*Considering and resolving planning issues for your new class
*Using the New ADM Class tool to create the class file
*Adding application logic to the class files as required to provide the custom behavior for your new class
This section describes planning issues and explains how to use the New ADM Class tool to create the class files. For instructions on adding application logic, see the “Adding application logic to your new or customized ADM class” section. For an example of creating a new class, see the “Creating the myviewer class” section .
Planning issues
Before you use the New ADM Class tool, consider some planning issues for questions that will arise during its use. Be sure to resolve these issues before you use this tool to create your new class:
*Decide where to put your new class files at design time. Since an ADM class is a collection of files, most of which are include files, and other files will reference the location of these include files, you might want to have a standard location in which to put all of the new class files. The New ADM Class tool (described later in this chapter) prompts you to enter the name of the directory where you want your new class files to be written. Progress Software Corporation recommends you follow the convention of the standard ADM class files and create an src\adm2 directory for your source files and an adm2 directory for your .r files in your working directory.
*Think about how to name your class files. The New ADM Class tool automatically generates the filenames based on the naming convention used for the standard ADM class files shipped with Progress. Progress Software Corporation recommends you use the same convention with your new class files.
*The New ADM Class tool automatically creates a custom subdirectory under the source directory you specify. This subdirectory will hold all the custom files or hooks that the standard ADM class files reference to allow the end user to customize the class. These files are a necessary part of the class structure, even if you do not plan to use them.
Remember you cannot change the filenames and relative paths of a class once the AppBuilder generates the files. You must be careful to create a development environment that is consistent with the environment and file structure in which you plan to deploy your applications.
Creating the new class files
You create the new class files with the New ADM Class tool, located on the AppBuilder menu bar. To start the New ADM Class tool, choose ToolsNew ADM Class... from the menu bar, shown in Figure 8–2.
Figure 8–2: New ADM Class menu option
Invoking this command opens the New ADM Class dialog box, shown in Figure 8–3.
Figure 8–3: New ADM Class (initial)
This dialog box contains two tabs. In the Basic tab, you name the class and supply various file and directory names and locations. The Custom Files tab provides information about the new custom files for this class. The following sections describe how to use these tabs.
The Basic tab
The Basic tab initially contains only one fill‑in field, Name, in which you enter the name of your new class. After you specify a class name, fill‑in fields open for the other labels on this tab. These fields contain automatically generated default names based on the class name you supply. For example, specifying the class name as mybrowser and the class from which to derive as ...browser.cld produces the result shown in Figure 8–4.
Figure 8–4: Basic tab with fill‑in fields
The default names follow the standard Progress naming convention. Progress Software Corporation recommends you use these names but does not require that you do so. Recall that once you save your new class, you cannot change the file and directory names for your new class.
Table 8–1 lists and describes the fill‑in fields in this tab.
 
Table 8–1: Basic tab fill‑in fields
Field name
Description
Mandatory?
Name
The name of the class. This name serves as a base name for the names of all of the files for the class.
Yes
Class Definition File
A file that references the components of a class. The extension must be .cld.
Yes
Source Directory
The pathname of the directory where the source files will be generated. You can browse for this directory.
Yes
Rcode Directory
The pathname of the directory for the r‑code for the super procedure. You can browse for this directory.
Yes
Template Directory
The pathname of the directory for the template file. You can browse for this directory.
Mandatory if there is a value in the Template field
Derive From Class
The class definition file (.cld) to subclass.
No
Method Library
A file that defines the class name, references a property file, and starts the super procedure. The extension must be .i.
This file is also called the primary include file.
Yes
Property File
A file that defines properties for the class. The extension must be .i.
Yes
Super Procedure
Defines the get and set functions for readable/writable properties and new behavior for the class. The extension must be .p.
Yes
Prototype File
A file that references the functions and internal procedures of a super procedure. The extension must be .i.
Note: You can create the contents of this file by using the ProtoGen tool from the AppBuilder’s Pro*Tools palette.
Yes
Template
The name of the template file. It references the primary include file of the class.
No
Copy From Template
A template file to copy from. You can select the file on disk by clicking the file button.
No
Check the Replace existing files if exist option at the bottom of the Basic tab if you want to open these files in the AppBuilder once they have been created.
The Custom Files tab
The Custom Files tab displays all the custom files (hooks) that will be generated when the new class is created. Like the file and directory names in the Basic tab’s fill‑in fields, these filenames are generated automatically based on the class name you supply, and thus they are not filled until after you specify a class name. For example, specifying the class name mybrowser in the Basic tab produces the result in the Custom Files tab shown in Figure 8–5.
Figure 8–5: Custom Files tab
The custom files allow you to modify and/or extend a class after it is deployed, without altering the basic class itself. They are described in more detail in the “Custom class files” section.
Creating the class files
Once you supply all the information required in the Basic tab, including specifying whether to open the files in the AppBuilder, you are almost ready to create the files.
Before you create them, however, you must decide whether the AppBuilder should replace files that already exist when it creates the class files. To specify this, either check or uncheck the Replace existing files if exist option at the bottom of the New ADM Class dialog box, as appropriate. You can now create the class by clicking OK. (To cancel the operation, click Cancel.)
When the AppBuilder creates a new class, it generates these files:
*Class definition file: class-name.cld
*Primary include file: prim-incl-file.i
*Property file: prop-file.i
*Prototype file: proto-file.i
*Super procedure: super-proc.p
*Template: template-file.w
(if specified in the Basic tab of the New ADM Class dialog box)
*Custom primary include file: prim-incl-filecustom.i
*Custom property file: prop-filecustom.i
*Custom prototype file: proto-filecustom.i
*Custom super procedure: super-proccustom.p
*Custom exclude definition file: class-nameexclcustomm.i
*Custom instance definition file: class-namedefscustom.i
*The r‑code for the super procedures in the r‑code directory.7
You already should be familiar with the standard class files. For descriptions of them, see the “Adding application logic to your new or customized ADM class” section.
Warnings and error messages
When the AppBuilder tries to create a new class, it uses validation controls to check whether pathnames and filenames are correct and whether files already exist. If it is successful in creating the class, the AppBuilder advises you of this:
If the validation process fails, the AppBuilder displays a warning message and does not generate code. The following are warnings and error messages the AppBuilder might display:
*Saving the Class Without a Class Name — If you try to save the class without providing a class name, the AppBuilder displays the following error message:
*Generating Your Files Directly in the DLC Directory Progress Software Corporation recommends you do not install user‑defined code in the DLC directory. If you try to do this, the AppBuilder displays the following warning message:
The warning gives you the option of creating a similar directory structure in your working directory (that is, \src\adm2). If you choose to do this, and any of the directories specified do not yet exist, you are prompted to create them:
If you choose not to create the directory, the AppBuilder stops processing and does not generate files. You must provide a valid directory name and then try again.
*File Generation Error — If an error occurs while the AppBuilder is generating class files, it displays a message and stops processing. For example:
If the AppBuilder stops processing during file generation, it does not delete files that it has finished generating.
Modifying the new class files
After creating the class files for your new class, you modify the standard class files as required to provide behavior specific to your new class. You already should be familiar with the standard class files, which are described in detail in Chapter 1, “Overview.”
You modify the standard class files by adding Progress 4GL code that supplies the application logic for the class’ custom behavior. For details, see the “Adding application logic to your new or customized ADM class” section. For an example of creating a new class, see the “Creating the myviewer class” section.
Customizing an existing ADM class
The custom class files built into a particular ADM class provide a way for you to add modifications and/or extensions without altering its standard class files. Most of the custom class files share essentially the same structure as the corresponding standard class files. The custom files allow you to alter an existing ADM class by:
*Adding new properties
*Adding a new super procedure
*Adding new behaviors
*Replacing or removing existing behaviors
*Adding new prototype definitions
*Adding new instance properties
All standard class files in the %DLC% (Windows) or $DLC (UNIX) directory under the adm2 and web2 subdirectories include custom hooks that allow their customization. Similarly, any new class that you create (or that is given to you) has these custom hooks built in.
For descriptions of the custom class files, as well as design rules and special notes on adding properties, see the “Adding application logic to your new or customized ADM class” section. For an example of customizing an existing class, see the “Customizing the visual class” section.