Add Code Events to template

You can add new code events to a template.

Code events can be integrated into the Business Application Modeler (BAM) template. This means they must be implemented where the BAM generates code. It involves:
  1. Adding code to Tcl scripts. These scripts are where 4gl files are created from the XML consolidation files generated by the BAM. This is where you code to:
    • Define a function type for a given entity
    • Define a variable for this function
    • Register the function as a callback function at the required level (Relation, Document, Record, Field, or Table) of the entity
    • Call this function if defined.

    To better understand what coding is involved, it is recommended to explore how existing code events are created and what Tcl scripts are used.

  2. Providing a locator for the BAM to access the sources defined in step 1 by configuring a LOCATOR Editor in Settings.agconf.

Tcl files

Tcl files are located in the template directory GSTDIR/gst/bin/src/ag/tpl/dbapp<version_number>/tpl. They are processed by commands ($(generate), and tclsh) as part of the build rule for the specific file type.
  1. You need to define the function variable and register the callback for your function in the appropriate Tcl events file. This Tcl file will depend on the entity type:
    Table 1. Tcl files
    File Code event
    uievents.tcl UI code event
    reportevents.tcl Report
    wsj_serviceevents.tcl JSON Web service use
    ws_serviceevents.tcl SOAP Web service
  2. You will also need to update procedures in other Tcl files, where the Genero BDL instructions to use the callback (proc call_), and from where to call the callback ( proc gen_) are generated.

Settings.agconf

The settings.agconf file is located in the template directory GSTDIR/gst/bin/src/ag/tpl/dbapp<version_number>. The <File> element has a specific DynamicProperty (<DynamicProperty>) element for locating code events.

  1. You need to determine where your code event should be in the context of the BAM entity types (by file extension).
  2. This example shows how the Before Row code event is defined in a DynamicProperty element. From this you will be able to see what attributes are being used and how:
    <DynamicProperty name="uc_record_dlgEvent_BeforeRow" 
                     type="LOCATOR" 
                     label="Before Row" 
                     description="Before Row" 
                     filePath="$(Dir)/$(BaseName).4gl"
                     locator="/PUBLIC FUNCTION dlgEvent_$(./@name)_BeforeRow[^\\w].*$"
                     codeTemplate="
    PUBLIC FUNCTION dlgEvent_$(./@name)_BeforeRow(dlg ui.DIALOG, uiMode SMALLINT, 
        dlgCtrlInstruction libdbappEvents.DlgCtrlInstruction_Type)
        RETURNS (libdbappEvents.DlgCtrlInstruction_Type)
    
        DISPLAY &quot;dlgEvent_$(./@name)_BeforeRow (Row scope) is raised&quot;
    
        RETURN dlgCtrlInstruction
    END FUNCTION
    " />
  3. You also have the option of registering the property, ("uc_record_dlgEvent_BeforeRow" in the example) on the record entity by adding its name to the existing <Items> record in the <File> section:
    <Item nodeName="Record" dynamicProperties="...;uc_record_dlgEvent_BeforeRow;..."
  4. The property name can also be added to an existing property group <DynamicPropertyGroup> in the <File> section if required:
     <DynamicPropertyGroup name="DialogEvents" label="Dialog Events" 
                description="Put user code to customize the application" 
                properties="...;uc_record_dlgEvent_BeforeRow;..."