In AFP 3.0, events provide the opportunity to react to requests and special events outside of the actual .afp document. There are events for individual pages and events for the application itself. The latter present more deployment opportunities as they allow you to automatically execute code for all pages of an application with only little effort.

Create a procedure in the appropriate .code file to populate an event with code. If the application is sample.afpa this would be sample.afpa.code, with a page named index.afp this would be index.afp.code. All procedure names start with EVENT_. Since AFP uses the underscore as a separation character you shouldn't use it in your own procedure names. Events aren't methods in the classic sense.

When developing Web applications, events are virtually always empty by default. So it is up to you to decide whether or not you wish to utilize this. To get a first impression, take a look at the compiled PRG files in the %cache% directory. All places where events may be added are marked by a comment and the name of the event.

How can you take advantage of this? - Let us consider a Web application with multiple AFP documents that need the same tables for every query. You might be inclined to try placing the code in each of the documents - but you should rather rely on an event that will be run at every query, anyway. This will save you a lot of time and effort in your development work.

To illustrate this, let us take a look at this sample of an Init event that is initiated at the very first invocation of a page in a Web application.

**************************************************************

* Open all tables

**************************************************************

Procedure Event_Init

   USE (File.FullPath("upload.dbf"))

EndProc

Let us examine the structure of the sample code a bit closer. Firstly, event methods can only be used in .code file - like .afp.code or .afpa.code. Since this code originates from upload.afpa.code it means that this is the component of a Web application (.afpa) named upload.

The actual event is defined through the FoxPro instruction Procedure…EndProc. Plus, you must always conclude an event with EndProc. The code defined in the event will be incorporated in the compiling process in its entirety and without modification. Should you forget to put EndProc, you would negatively affect the desired result and unwillingly generate errors.

Inside the event methods you may only use pure FoxPro commands and functions. Segments between <%...%> are not allowed in event programming. The same applies to all special commands available in these code segments. To return generated HTML code you can use neither ?, ?? nor the = commands; rather you will have to utilize the appropriate functions like Response.Write(). Since event code is embedded in an existing procedure, RETURN will not terminate the event but rather the AFP document. One of the results of this is that session variables will not be saved.

Events can occur multiple times in the actual result pages (see PRGs in %cache%). A number of factors affect this, including the course taken by the AFP-internal compilation, whether the event is defined in each page and in the Web application, whether this is a free AFP document or a document tied to an application, and many more. You should also keep in mind that there is no linear interrelation between the event definition in .code and the actual position taken up in the compiled version. This decision is made exclusively by the AFP compiler.