skip to main content
OpenEdge Development: ADM and SmartObjects
Developing ADM Extensions : Examples
 
Examples
This section provides two examples. The first illustrates creating a new class with the New ADM Class tool; the second illustrates customizing an existing class.
Creating the myviewer class
The example in this section illustrates creating a new class based on the viewer class. The new class, called myviewer, will contain custom functionality that displays a warning message to an application user who wants to delete a record and allows the user to choose how to proceed. This functionality will be built into all SmartObjects based on this class.
The following sections describe how to create the new myviewer class files, then modify them to create the new functionality.
Note: The example assumes you installed Progress in the D:\PROGRESS directory.
Creating the myviewer class files
To create the myviewer class files:
1. From the AppBuilder main menu, choose ToolsNew ADM Class...:
The New ADM Class dialog box opens, with the Basic tab in front.
2. In the Name field, enter myviewer, the new class name:
When you type myviewer, the AppBuilder enters default directories in the directory fill‑in fields and names based on myviewer in many of the filename fill‑in fields; for example, myviprop.i for the property filename.
3. Select the class from which to derive the myviewer class:
a. Click on the Class button next to the Derive From Class field. In the Choose Class Definition dialog box that appears, you are placed by default in the %DLC%\src\adm2 (Windows) or $DLC/src/adm2 (UNIX) directory.
b. Select the viewer.cld class definition file in that directory, then choose Open.
The AppBuilder adds information to the New ADM Class dialog box:
The Derive From Class field now contains the viewer.cld class definition file. The the Copy From Template field automatically is filled with the filename of the viewer template. This happens only because the class definition file contains a definition of this template; if it did not, this field would stay empty.
4. Click the Custom Files tab to note the custom class files that will be generated for the myviewer class:
5. Click the Basic tab, then check the Open files in the AppBuilder once generated check box. This instructs the AppBuilder to open the primary include file, the property file, the super procedure file, and the prototype file after creating the class files:
6. Press OK to create the files.
7. After the AppBuilder finishes creating the myviewer class files, close the primary include file (myviewer.i) and the prototype file (myviprto.i). In this example, these files do not need modification.
Modifying the myviewer standard class files
You use the following new code to implement the custom myviewer functionality: a DeleteMessage property, a setDeleteMessage function, and an override procedure for the standard ADM deleteRecord method. Adding this functionality requires changes only to the myviprop.i property file and the myviewer.p super procedure file, both of which should still be open in the AppBuilder.
To add the new functionality in the AppBuilder:
1. Define the new DeleteMessage property in the myviprop.i property file.
To do this, go to the file’s main block and add the code shown in bold typeface below:
 
/* Include the file that defines prototypes for all of the super
   procedure’s entry points. And skip including the prototypes if we are
   *any* super procedure. */
&IF "{&ADMSuper}":U EQ "":U &THEN
{src/adm2/myviprto.i}
&ENDIF
 
/* Put your xp{&Property} preprocessor definition here. Use the following
   format, e.g. &GLOBAL-DEFINE xpMyProperty. These preprocessors tell at
   compile time which properties can be retrieved directly from the
   temp-table */
&GLOBAL-DEFINE xpDeleteMessage
 
{src/adm2/viewprop.i}
 
&IF "{&ADMSuper}":U = "":U &THEN
  /* Put your property field definition here. Use the following syntax,
     e.g. ghADMProps:ADD-NEW-FIELD(’MyProperty’:U, ’CHAR’:U, ,’x(20)’:U,
     ’Hi’:U). */
 
ghADMProps:ADD-NEW-FIELD(’DeleteMessage’:U, ’CHAR’:U, 0, ?,
  ’Are you sure you want to delete this record?’:U).
&ENDIF
 
{src/adm2/custom/myvipropcustom.i}
When you finish making these changes, click on the Save button (the diskette icon) on the AppBuilder main window to save your changes, then close the property file window.
2. Create a new setDeleteMessage function in the myviewer.p super procedure file.
This function allows you to set the new DeleteMessage property. To create the new function, add the code shown in bold typeface:
 
RETURNS LOGICAL
  ( INPUT pcDeleteMessage AS CHARACTER ) :
/*-------------------------------------------------------------------
  Purpose:
    Notes:
  -------------------------------------------------------------------*/
  {set DeleteMessage pcDeleteMessage}.
  
  RETURN TRUE.   /* Function return value. */
END FUNCTION.
3. Create a new override procedure for the deleteRecord method in the myviewer.p super procedure file. This procedure displays an alert box when the deleteRecord method is invoked; this alert box prompts the user with a message that corresponds to the value of the new DeleteMessage property: if the user chooses Yes, the ADM deleteRecord executes, otherwise it returns without executing. To create the new override procedure, add the code shown in bold typeface:
 
/*-------------------------------------------------------------------
  Purpose:     
  Parameters:  <none>
  Notes:       
-------------------------------------------------------------------*/
  DEFINE VARIABLE cDeleteMessage AS CHARACTER   NO-UNDO.
  
  {get DeleteMessage cDeleteMessage}.
  MESSAGE cDeleteMessage
    VIEW-AS ALERT-BOX QUESTION BUTTONS YES-NO
    UPDATE lAnswer AS LOGICAL.
  
  IF lAnswer THEN 
    RUN SUPER.
END PROCEDURE.
When you finish making the changes in Step 2 and Step 3, click on the Save button (the diskette icon) on the AppBuilder main window to save your changes, then close the super procedure file window. The AppBuilder now creates a .r version of the super procedure in the src\adm2 directory under your working directory.
4. Enable the new super procedure file by moving the .r file from the src\adm2 directory under your working directory into the adm2 directory under your working directory.
Note: If you do not move the .r file into the adm2 directory under your working directory, you will not be able to use the new super procedure.
5. Make the template for the myviewer class available on the New dialog box that appears when you choose FileNew from the AppBuilder menu. To do this:
a. Create a new .cst file and add to it the following code lines:
 
*NEW-SMARTOBJECT  SmartDataViewer Demo
NEW-TEMPLATE src/adm2/template/myviewer.w
b. Put the .cst file into the src\adm2\template directory under your working directory.
c. Load the new .cst file by choosing MenuUse Custom... from the AppBuilder Palette window and adding the name of the new file to the list.
The new class, with its custom behavior, is now ready for use. Before you work with it, you should restart the AppBuilder to re‑establish the super procedure stack.
Customizing the visual class
The example in this section illustrates customizing the visual class. The customization defines a special property that you can set to specify the background color for SmartObjects that inherit from this class (that is, all visual SmartObjects), thus standardizing the look of your Progress 4GL applications.
The following sections note which custom class files you need to provide, and describe how to modify them to create the new functionality.
Copying the visual custom class files
You customize an existing class by modifying the custom class files built into that class. For this example, you will modify a selected set of the visual custom class files. You work on a copy of the required files in your working directory rather than in their installed location.
To prepare for customization:
Copy the following files from the %DLC%\src\adm2\custom (Windows) or $DLC/src/adm2/custom (UNIX) directory into the src\adm2\custom (Windows) or src/adm2/custom directory under your working directory:
*vispropcustom.i
*visualcustom.p
*visualdefscustom.i
Modifying the visual custom class files
You use the following new code to customize the visual class with the new functionality: a BgColor property, setBgColor and getBgColor functions, and an override procedure for the standard ADM initializeObject method. Adding this functionality requires changes to the visualcustom.i primary include file, the vispropcustom.i property file, the visualcustom.p super procedure file, and the visualdefscustom.i custom instance definition file, which you will copy and open as required.
To add the new functionality in the AppBuilder:
1. Define the BgColor property in the vispropcustom.i custom property file in your working directory). To do this, open the file, go to its main block, and add the code shown in bold typeface:
 
/* Include the file that defines prototypes for all of the super 
   procedure’s entry points. And skip including the prototypes if we are
   *any* super procedure. */
&IF "{&ADMSuper}":U EQ "":U &THEN
{src/adm2/custom/visprtocustom.i}
&ENDIF
 
&GLOBAL-DEFINE xpBgColor
 
&IF "{&ADMSuper}":U = "":U &THEN
ghADMProps:ADD-NEW-FIELD(’BgColor’:U, ’INTEGER’:U, 0, ?, 7).
&ENDIF
 
/* _UIB-CODE-BLOCK-END */
&ANALYZE-RESUME
When you finish making these changes, click on the Save button (the diskette icon) on the AppBuilder main window to save your changes, then close the property file window.
2. Create new setBgColor and getBgColor functions in the visualcustom.p super procedure file. These functions allows you to set and get the new Bgcolor property publicly. To create the new functions, open the file, then add the code shown in bold typeface:
 
FUNCTION getBgColor RETURNS INTEGER
  ( /* parameter-definitions */ ) :
/*-------------------------------------------------------------------
  Purpose:
  Notes:
-------------------------------------------------------------------*/
  DEFINE VARIABLE iBgColor  AS INTEGER  NO-UNDO.
  
  {get BgColor iBgColor}.
  RETURN iBgColor.   /* Function return value. */
 
END FUNCTION.
 
FUNCTION setBgColor RETURNS LOGICAL
  ( INPUT piBgColor AS INTEGER ) :
/*-------------------------------------------------------------------
  Purpose:  
  Notes:  
-------------------------------------------------------------------*/
  {set BgColor piBgColor}.
  RETURN TRUE.   /* Function return value. */
END FUNCTION.
3. Create an override procedure for the initializeObject method in the visualcustom.p custom super procedure file in your working directory. This procedure gets the current value of the new BgColor property and sets the background color of container frame accordingly. To create the new override procedure, add the code shown in bold typeface:
 
PROCEDURE initializeObject :
/*-------------------------------------------------------------------
  Purpose:
  Parameters:  <none>
  Notes:
  ---------------------------------------------------------------------*/
  DEFINE VARIABLE hFrame   AS HANDLE   NO-UNDO.
  DEFINE VARIABLE iBgColor AS INTEGER  NO-UNDO.
 
  {get ContainerHandle hFrame}.
  {get BgColor iBgColor}.
    
  RUN SUPER.
  /* Don’t do anything in design mode */
  IF DYNAMIC-FUNCTION (’getUIBMode’:U IN TARGET-PROCEDURE) NE "":U THEN     RETURN.
 
  IF hFrame:TYPE = "FRAME":U THEN
    hFrame:BGCOLOR = iBgColor.
  ELSE IF hFrame:TYPE = "WINDOW":U THEN
    ASSIGN
      hFrame = hFrame:FIRST-CHILD
      hFrame:BGCOLOR = iBgColor.
END PROCEDURE.
When you finish making the changes in Step 2 and Step 3, click on the Save button (the diskette icon) on the AppBuilder main window to save your changes, then close the super procedure file window. The AppBuilder now creates a .r version of the super procedure in the src\adm2 directory under your working directory.
4. Edit the visualcustom.i primary include file, and uncomment the line that starts the custom super procedure. When you finish making this change, click on the Save button (the diskette icon) on the AppBuilder main window to save your change, then close the primary include file window.
5. Add the BgColor property to the list of instance properties, and specify a filename for the instance properties dialog in the visualdefscustom.i custom instance definition file in your working directory. To add the property and filename, open the file, then add the code shown in bold typeface:
 
/*-------------------------------------------------------------------
  File        : visualdefscustom.i
  Purpose     : Entry point to define:
                  New definitions
                  {&xcInstanceProperties}
                  {&ADM-PROPERTY-DLG}
  Syntax      : {src/adm2/custom/visualdefscustom.i}
  Modified    : 06/03/1999
 
  Notes       : Referenced in {src/adm2/visprop.i}
---------------------------------------------------------------------*/
  &IF "{&xcInstanceProperties}":U NE "":U &THEN
  &GLOBAL-DEFINE xcInstanceProperties {&xcInstanceProperties},
  &ENDIF
  &GLOBAL-DEFINE xcInstanceProperties {&xcInstanceProperties} BgColor
 
  &GLOBAL-DEFINE ADM-PROPERTY-DLG adm2/support/myvisuald.w
You have specified adm2/support/visuald.w—that is, the file visuald.w in the adm2\support directory under your working directory—as the instance properties dialog box file. (Progress code is not sensitive to whether you use forward or reverse slashes in pathnames.) You will add support for this dialog box in the next step.
When you finish making these changes, click on the Save button (the diskette icon) on the AppBuilder main window to save your changes, then close the property file window.
6. Provide support for your new property in the instance properties dialog box. In this example, the simplest approach is to copy the instance property dialog box for the visual class, visuald.w, from the %DLC%\src\adm2\support directory to src\adm2\support (Windows) or from the $DLC/src/adm2/support directory to src/adm2/support (UNIX) under your working directory, then modify the copy as needed.
Alternatively, you can either modify the original visuald.w instance properties dialog box in the %DLC%\src\adm2\support (Windows) or $DLC/src/adm2/support (UNIX) directory or create a completely new instance properties dialog box that includes support for the new property (as well as all other properties required by the class).
Regardless of which technique you use, you must be sure that the instance property dialog box filename matches the name that you specified in the custom instance definition file in your working directory. (See Step 5.)
7. Enable the new super procedure file by moving the .r file from the src\adm2 directory under your working directory into the adm2 directory under your working directory.
Note: If you do not move the .r file into the adm2 directory under your working directory, you will not be able to use the new super procedure.
The customized class, with its new property, is now ready for use. Before you work with it, you should restart the AppBuilder to re‑establish the super procedure stack.