[Prev] [Next] [Top] [Bottom] [Contents] (7 out of 17)

Data Site Callbacks

In the description earlier of how Sapphire-generated CGIs "play" HTML templates, the concept of a data site was defined. When a data site is encountered, Sapphire/Web CGIs look for Population callbacks registered for the site through Object Bind Editor Binding (described earlier). This section describes two other types of data site callbacks.

The first of these data site callbacks is basically String Substitution. You register this with a Call to the Function, SaRegisterStringSite. Its function prototype is:

int SaRegisterStringSite(char* file, char* site, char* 
value);
The first parameter, file, specifies the filepath name of an HTML template file. If non-null and not an empty string, this file will be "played", if it is not already on the "play" list. If NULL or an empty string, the second parameter, site, will still be registered, but can be overridden by a similar site name with a specified filename. The third parameter, value, is a string to substitute for the specified data site. The string is copied locally.

The second of these data site callbacks is more general, although you must write a data site callback function. You register this with a call to the Function, SaRegisterFuncSite. Its function prototype is:

typedef void (*SaSiteCallback)(char* file, char* site, 	void* 
client);
int SaRegisterFuncSite(char* file, char* site, 
SaSiteCallback func, void* client);
The first parameter, file, specifies the filepath name of an HTML template file. If non-null and not an empty string, this file will be "played", if it is not already on the "play" list. If NULL or an empty string, the second parameter, site, will still be registered, but can be overridden by a similar site name with a specified filename. The third parameter, func, is a site callback function which must be of the type, SaSiteCallback, as declared above. The fourth parameter, client, is a general purpose pointer that is sent to the Callback Function. It must be valid when function is called. Data Site Callbacks are a powerful feature which extends the functionality of Sapphire. See Login Functionality in the preceding section as one example of how they can be used.

Now the rules for data site processing can be stated as follows. First a Sapphire/Web CGI looks for any Population Callbacks registered on a Data Site. The first one registered on the site is called, all other population callbacks on that site are "shadowed" (i.e., not called). Whether or not any population callbacks are found, the Data Site Callbacks are checked. If the site is registered with a filename parameter, then those without are shadowed. If multiple registrations are found, only the last one is called and the others are shadowed. Finally if any data site is found in a ##Sa_BeginLoop## ##Sa_EndLoop## construct, even one of these does not have a Population Callback, the entire loop is not "played", not even once.


[Prev] [Next] [Top] [Bottom] [Contents] (7 out of 17)