1. How do I overload a function in the BALCO public API?

To overload a function in the BALCO public API, simply declare a new function with exactly the same signature as the function you wish to overload. For example, if you wanted to overload the WPCAPI.processLogin() function, you might write the following code:

if(if( WPCAPI ) { WPCAPI.processLogin = function() { // Do stuff... }; }

2. What is the difference between an overloadable function and an event handler?

An event handler is traditionally identified in JavaScript with an oneventname naming convention. It is still common practice to assign events by following a syntax identical to that of overloading a function -- that is, object.oneventname = function(); The return value of the function would determine whether or not the event would occur. Simple custom events for ordinary objects may be defined in this manner. BALCO supports this paradigm while additionally supporting a deferred processing model for events (see #3 below).

Overloadable functions may have any return type and are not necessarily called for their approval on an operation. BALCO overloadable functions exist to allow new functionality to be plugged in or to request information that can only be made available at runtime by the parent application. BALCO supports the same deferred processing model for its overloadable functions that it does for events (see #3 below).

3. Does BALCO support asynchronous function overloading?

Yes! If you need to perform asynchronous operations in an overloaded function (e.g: AJAX requests to your server, wait for some event to be fired, etc), you have the option to defer processing until your asynchronous operations are complete. Any BALCO public API function that explicitly supports overloading can defer processing.

To support asynchronous operations in your overloaded function...

1. Your overloaded function should return null.
   
   
2. After your asynchronous operations are complete, call functionName_Callback(returnValue), where functionName is the name of the overloaded function and returnValue is the return value if the function had been synchronous.

For example, if you wanted to overload the WPCAPI.onpagerename() function to asynchronously update a page title in your application, you might write the following code:

if(if( WPCAPI ) { WPCAPI.onpagerename = function( cellID, title, message ) { // Prepare the data for the request... var data = "cellId=" + encodeURIComponent(cellID); data += "&title=" + encodeURIComponent(title); data += "&message=" + encodeURIComponent(message); var request = new XMLHttpRequest(); request.open( "/page/setTitle","/page/setTitle", "PUT" ); request.onreadystatechange = function() { if(if( request.readyState == 4 ) { // Allow the page rename only with a success response... WPCAPI.onpagerename_Callback( request.status == 200 ); } }; request.send(data); }; }