Proxy Functions

Contents

Specify That a Function Should Be Proxied
Give a Proxied Function Access to the Scripts it Needs
Invoke a Proxy Function
Use the Proxy Function's DOM
Supported Return Values

API Links

Proxy functions, the third stage of a page's lifecycle, provide a means for exchanging data between the browser and the server using your own Javascript functions. Proxy functions ease the data exchange process by encapsulating the details of the XMLHttpRequest object.

Note: Proxied functions are executed, internally, through Jaxer.Callback; try not to let this confuse you.

Specify That a Function Should Be Proxied

You can specify that a server function should be proxied to the client by:

including the function in a script block designated with runat
setting the proxy property on a function object with a value of true
or adding any server function object to the Jaxer.proxies array

// Using runat=
<script type="text/javascript" runat="server-proxy"></script>

// Using the proxy property
function getResult() {
	return 42;
}
getResult.proxy = true;

// Adding a server function object to Jaxer.proxies
function getNumber() {
	return 42;
}

window.onserverload = function() {
	Jaxer.proxies.push(getNumber);
};

Give a Proxied Function Access to the Scripts it Needs

Prior to invoking a proxy function, you can determine which scripts and libraries are available when the function executes by doing the following:

adding an autoload="true" attribute to a script tag to ensure that a script is always available to all proxy functions to the page. <script src="included-script.js" runat="server" autoload="true"></script>
using Jaxer.load inside the server-side oncallback function to load scripts or libraries required by the proxy function.

Using JavaScript Libraries During Callbacks

You must update the path reference for jQuery on line 8

<html>
	<head>
		<script src='/PATH/TO/jquery.js' runat='server' autoload='true'> 
		 
		</script> 
		<script runat='server-proxy'> 
		    
		    function doCallback(msg){ 
		    
		        Jaxer.Log.info(msg + ": OK I'm in the proxy function..."); 
		        // put something in the dom 
		        document.getElementsByTagName('BODY')[0].innerHTML = "<h1 id='test'>this was set during the " + msg + " proxy function</h1>" 
		        
		        // use jquery to access the DOM node we inserted 
		        domCheck = $('#test').text(); 
		        Jaxer.Log.info(msg + ": ...proxy function completed"); 
		        
		        // return the CONTENTS of the DOM node to the client. 
		        return domCheck; 
		    } 
		</script> 
		 
		<script runat='client'> 
		    document.getElementById('myDiv').innerHTML = doCallback('first'); 
		    document.getElementById('myDiv').innerHTML = doCallback('second'); 
		</script>
		 
		<script runat='server'> 
		    
		    Jaxer.Log.info(""); 
		    Jaxer.Log.info(Jaxer.request.current.url); 
		    
		    document.getElementById('myDiv').innerHTML = "<B>Inserted by the server</B>"; 
		    
		    /* 
		     * oncallback is a 'special' function name that is run in the context of 
		     * a callback prior to the requested data being exec'd. 
		     */ 
		    function oncallback(){ 
		    
		        Jaxer.Log.info("Setting up environment for the callback"); 
		        
		        if (typeof $ == 'undefined') { 
		            Jaxer.Log.info("jQuery not loaded"); 
		        } 
		        else { 
		            Jaxer.Log.info("jQuery already loaded."); 
		        } 
		    } 
		</script>        	
	</head>
    <body>
    	<div id='myDiv'></div>
	</body>
</html>

Invoke a Proxy Function

For each function that you specified should be proxied, Jaxer automatically embeds a proxy function in the page it emits to the browser. A proxied function named saveComment can be directly invoked in the browser as saveComment().

Using a Proxy Function

By default, all proxy functions are synchronous: the browser waits until the proxy function has returned. However, you can invoke a proxy function asynchronously by using the async() method and providing the function that should be called when the proxy function returns; for example, saveComment.async(finishFunction). You may provide a parameter, finishFunction which will get the return value of the proxied function.

Using an Asynchronous Proxy Function

Use the Proxy Function's DOM

Every proxy Function's DOM on the server is initially empty and doesn't contain the content of the original page. This DOM may be used to create and transform HTML content to return to the browser after querying document.documentElement or someElement.innerHTML.

However, the proxy function must return the new/changed data— it isn't automatically returned to the server and the function's state is discarded after execution.

Supported Return Values

Proxied functions can return any value supported in JSON, specifically any of these value types:

Primitive: string, number, Boolean
Composite: object, array
Complex: date, RegExp, XMLDocument (through Aptana extensions to JSON) (other Node types are not supported yet).
Custom: You may also register custom type serializers
Advanced: Jaxer also extends JSON to support cycles in the object graph and multiple references to the same object.

Jaxer Guide