Customizing Applications

AFP load and unloads application as required. Normally an application is loaded if someone requests an AFP page that the application is assigned to. Loading an application means that the AFP sets up a new data session. After that the application's Init event executes. The application can take advantage of this to open tables etc.

Applications are unloaded by running the function App.Unload() or whenever an application is modified. In such a case the Unload event will be fired. There is no guarantee, however, that this event will always fire prior to the unloading of an application.

Applications are defined by XML files. The most important setting of an application is its ID. All applications with the same ID share the same session variables. Aside from the ID you can influence the compilation process through the <build-option> tag. At this time, the only option available is transform. Through this option you define the function to be invoked to convert ?, ?? and = to a character string. By default, the function TRANSFORM() is used for this purpose.

If, however, you wish to send text output automatically through TEXTMERGE() or you require the translation of the page, wish to return multiple values separated by commas, or wish to embed formatting instructions in additional parameters, this option lets you invoke a separate function. You should define this function in the afpa.code file. The penalty for this enhanced flexibility is reduced performance, as the invocation of a user-defined function in FoxPro is slower than the invocation of a built-in function.

To assign an application to a .afpa file the AFP employs a unique search algorithm. It will use the first application that can be assigned to a page. The <file> tag that plays an important role in numerous AFP configuration files is also decisive for the definition of the application. On various occasions the AFP will search for files with certain predetermined names. In the case of applications this will be a file application. The <file> tag lets you can define which physical file, if any, should actually be used.

The <file> Tag exists in three characteristic shapes. In its normal shape it defines a physically existing file. To do this, you will have to define both the physical path and the virtual path on the Web. If no virtual path exists you may specify any other path. The assignment of C24_Fox.afpa is roughly like this:

<file

name = "application"

location = "%root%\C24\C24_Fox.afpa"

virtual = "$virtual/C24_Fox"

Alternatively, you may define the file relative to the current file. The current file depends on the context that AFP uses for the access to that particular tag. Such definition is made through

If the file is application you may use a third alternative to indicate that actually no application exists. In this case a free page will be created:

In some cases an application is spread over multiple directories. If a copy of the .afpa file were to be deposited in each directory, all pages would execute the same code although each directory would have its own session ID. You can therefore specify in the .afpa file that it is only a proxy of another .afpa file. For this purpose you include a <file> tag in the .afpa file that points to another application:

This will ensure the consistent use of the main.afpa in lieu of .afpa in the higher directory. The search for the initial .afpa file of a page is done in three steps. The first step examines if a .config file has been defined for that particular page. Thus, the page index.afp would have index.afp.config as a configuration file. This configuration file lets you define precisely which application is to be used for the page:

<page>

<page>

In this example we define that there is no application for this page. You may of course use any of the three variants of the <file> tag. If specifically no application was defined for a particular page, the directory containing the .afp will be checked for the presence of a single .afpa file. If one is present it will be used. If multiple .afpa files are detected or if there is none, the search will continue.

The .afpa file can at any rate always point to another .afpa file by including a <file> tag in the .afpa file, as described above. Thus, there may be an application in a directory. In a sub-directory, a single page can also be associated with this application via a .afp.config file, while all other files can be associated with a second application in the sub-directory.

If this method finds no .afpa file in the file system, a final search of the <virtual> tree in config.afp will be made. As the search is made from the inside toward the outside, applications defined for sub-directories take precedence over applications defined for the uppermost level. Any application that has been defined through <virtual> is automatically valid for all sub-directories to which the <virtual> tree applies. See below for detailed information about this tree. To define a specific application, e.g. for http://localhost/data/ you may make the following entry in the <virtual> tree:

<file

name = "application"

location = "%root%\secure\data\data.afpa"

virtual = "data/data.afpa"

If even this method cannot find an application for the page, an application-free (free) page will be created. If the compatibility mode for AFP 2.4 activated, C24_Fox.afpa is automatically entered in the upper end of the <virtual> tree. It is then valid for all files that aren't explicitly associated with a different application.