1. How do I override a function in the client application?

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

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

2. What is the difference between an overridable 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 overriding 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. Wetpaint Injected supports this paradigm while additionally supporting a deferred processing model for events (see #3 below).

Overridable functions may have any return type and are not necessarily called for their approval on an operation. Overridable 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. Injected supports the same deferred processing model for its overridable functions that it does for events (see #3 below).

3. Does Injected support asynchronous function overriding?

Yes! If you need to perform asynchronous operations in an overridden 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 Wetpaint Injected public API function that explicitly supports overriding can defer processing.

To support asynchronous operations in your overridden function...

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

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

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", "PUT" ); request.onreadystatechange = function() { if( request.readyState == 4 ) { // Allow the page rename only with a success response... WPCAPI.onpagerename_Callback( request.status == 200 ); } }; request.send(data); }; }