How You Can Customize the Built-in Active Display Code
To customize the Active Display code, you can do one of the following:
• Override the relevant RequestManager functions by supplying code conforming to the format described here that the built-in calls will use instead
• Simply replace the code with your own code, in specific cases or all cases
You also may add extra events with their own code. The following paragraphs describe how to work within the current conventions.
The built-in event code calls—directly or indirectly—a RequestManager method named RespondToRequest. This method reads the requesttype/action from the tagged value settings of the triggering button (or other fieldtype), then examines your frame to see if you have supplied a local procedure for this requesttype. The built-in buttons, for example, trigger searches for procedures called datarequest, framerequest, or tblrequest, depending on their function. If you have coded such a procedure, it executes that procedure; if you have not coded a procedure, or your procedure does not define any code for the request action, it looks within RequestManager for such a procedure and executes that.
For more information about the RequestManager user class, see the Language Reference Guide.
Your procedure should adhere to the following example format and:
• Accept the three parameters action, trigger, and info
• Contain a case statement of all the actions you want to code for this requesttype
• Return an integer that will be ER_ROWNOTFOUND if the action is not defined.
PROCEDURE MiscRequest(
action = varchar(32) NOT NULL;
trigger = FieldObject DEFAULT NULL;
info = Object DEFAULT NULL;
)=
declare
rc = integer NOT NULL;
enddeclare
{
/*
** Respond to the request 'misc:tbd'
*/
case action OF
'tbd': //to be done
{
//tbd - set rc to ER_OK or ER_FAIL to indicate outcome of processing
}
default:
{
rc = ER_ROWNOTFOUND;
}
endcase;
return rc;
}
The code in each case block can be as simple or complex as you want. Simpler code is easier to work with. If the code is complex, turn it into a procedure or method, and call it.
The info parameter is provided for you to supply special information to the action processing that cannot be derived simply from the circumstances of the call. It is rarely needed, but if it is, the RespondToRequest method called from the event blocks will accept info as a parameter of type Object and pass it on to your procedure. Info can be as simple or complex as you need. Because the information it carries is for use by your procedure, you can structure its contents as best suits you. Some possible ways of structuring the information are:
• Supply scalar values as their object types (stringobject, dateobject, integerobject, for example).
• Supply multiple objects in an array of object, with each item a different entry in the array.
• Supply multiple objects in a tag-hash structure, using SetTaggedValue and FetchTaggedValue to load and recover the contents. (For details about how to do this, see the item parameter for each of these methods.)
This approach has the advantage that each item in the tag-hash store is labeled by the key you provide, unlike array stores, where information about the order of the contents must be maintained separately.