Using code events

Code events allow you to add custom code, in order to modify the behavior of a generated application.

Code events are tied to the entity they modify. The entity may be a Business Application entity (a form, report, Web service, or relation) or a Database Meta-Schema table.

Creating a code event

Creating a code event is a two-step process:

Find the code event in the Properties view of the entity. Learn how to find code events in Locating the code events.
Select the arrow in the Value field. This opens a source file where the code of the required function is generated for you.

The code module is opened automatically (by a The LOCATOR editor property) when you trigger the creation of the event. The BAM generates a function shell for the code event, with required parameters and returns. Triggering a code event brings you to the correct function. Add your own code to this function.

After you add a code event, the code event appears bold in the Properties view. This indicates that you have already created a function for the code event. Selecting the arrow again returns you to the function.

Locating the code events

To locate a code event, you must view the properties of the entity. Some entities have code events at different levels within the object, as identified in Table 1.

Table 1. Locating the code events for an entity
Entity	How to access the entity	Levels with code events	How to access the level	Code Event Layers
BA Relation	Open BA diagram (.4ba) and select a valid relation. See BA relation code events.	Relation level	BA Structure → Relation node	Dialog events
Form	Open BA diagram (.4ba) and double-click the form entity to open the form; or open the Form entity directly. See Form code events for a list of Form entity extensions.	Document level	Form Structure → ManagedForm node	Dialog events
		Record level	Form Structure → Record node	Dialog events Data events
		Field level	Form Structure → Field node	Dialog events
Custom Form	Open BA diagram (.4ba) and double-click the form entity to open the custom form; or open the Custom Form entity (.4fdc) directly. See Custom form code events.	Document level	Form Structure → ManagedForm node	Dialog events
Report Data	Open BA diagram (.4ba) and double-click the Report Data entity; or open the Report Data entity (.4rd) directly. See Report Data code events.	Record level	Structure View → Record node	Data events
Web Service	Open BA diagram (.4ba) and doubleclick the form entity. See Web services code events.	Record level	Structure View → Record node	Data events
Table	Open the Database Meta-Schema (.4dbx) and select a table. See Database code events.	Table level	Database Structure → Table node	Database data events

When you have selected the level within the entity, the Properties view shows what code events are available. Code events are grouped within code event layers.

Code event layers

Code events are part of the application layer – the Genero BDL (.4gl) modules generated by the BAM. They are organized by function into code event layers (logical categories) at the point of where your code interfaces with the application. Three layers are defined:

dialog events support user interaction with an entity.
data events support the data, such as CRUD operations performed by the user.
database data events support data at the database level, but implemented at the application level.

The layers appear as the group headings within the Properties view for a given level.

Where is the code stored?

The code you enter for a code event needs a place to sit in your project. A file is automatically created when you add your first code event. The filename is based on the entity name; for example, the entity entity.4fdm results in a file named entity.4gl to store the custom code. All code events created for the entity will be written to this file.

For that same entity, a file named entity_common.4gl is created for variables. This file defines variables specific to the event code module. Code event functions reference these variables.

Warning:

Do not write to this common file (entity_common.4gl) as your changes will not persist. The file is regenerated with each build.

Code events and renaming

Existing code events in your project are not called when the following elements are renamed:

A record.
An action between two forms.
A relation name between a form and a Report Data entity.

Renaming only affects code events based on these elements. When code events are inserted using the Properties view, a function shell is inserted into the code events file. Depending on the entity type the functions shell may be based on the name of the record, the name of the relation between a form and a report or the name of the action between two forms. Modifying the record name, action names or relation names does not regenerate the names associated with the function shell.

When renaming these elements, update your code to reflect the edits by creating new code events. A new function shell is created and you can migrate the previous code into the new code.