Thursday 12 April 2007 6:13:00 am
HTML_AJAX has more features than JPSpan. However, to keep things simple, we will use a configuration similiar to the one we applied in the case of JPSpan: an external server page that generates a JavaScript proxy, which is included in our HTML page. HTML_AJAX can also be used with the proxy and server code generated inline, all in one single script. However, we do not recommend this as it removes your ability to cache the generated JavaScript.
An HTML_AJAX server page is generally very simple. It creates an HTML_AJAX_Server instance, registers all the classes you want exported (called stubs) and handles incoming requests. The incoming requests can be of three different types:
HTML_AJAX also provides AJAX functionality that can be used purely from the JavaScript side. This allows you to add some basic AJAX functionality to your site very quickly, or to tie HTML_AJAX into your current framework. One basic use is to update the contents of an HTML element with a fragment generated from another PHP page. This gives you the flexibility of an <iframe> element without many of its drawbacks:
<html> <head> <script type='text/javascript' src="server.php?client=main"></script> <script type='text/javascript' src="server.php?client=dispatcher"></script> <script type='text/javascript' src="server.php?client=HttpClient"></script> <script type='text/javascript' src="server.php?client=Request"></script> <script type='text/javascript' src="server.php?client=json"></script> </head> <body> <script type="text/javascript"> function clearTarget() { document.getElementById('target').innerHTML = 'clear'; } // grab is the simplest usage of HTML_AJAX. You use it to perform a request to // a page and get its results back. It can be used in either Sync mode where // it returns a directory or with a call back. Both methods are shown below var url = 'README'; function grabSync() { document.getElementById('target').innerHTML = HTML_AJAX.grab(url); } function grabAsync() { HTML_AJAX.grab(url,grabCallback); } function grabCallback(result) { document.getElementById('target').innerHTML = result; } // replace can operate either against a url like grab or against a remote // method if it is going to be used against a remote method. defaultServerUrl // needs to be set to a url that is exporting the class it is trying to call. // Note that replace currently always works using Sync AJAX calls. an option // to perform this with Async calls may become an option at some further // time. Both usages are shown below function replaceUrl() { HTML_AJAX.replace('target',url); } </script> <ul> <li><a href="javascript:clearTarget()">Clear Target</a></li> <li><a href="javascript:grabSync()">Run Sync Grab Example</a></li> <li><a href="javascript:grabAsync()">Run Async Grab Example</a></li> <li><a href="javascript:replaceUrl()">Replace with content from a URL</a></li> </ul> <div style="white-space: pre; padding: 1em; margin: 1em; width: 600px; height: 300px; border: solid 2px black; overflow: auto;" id="target">Target</div> </body> </html>
After including the needed JavaScript, you can grab content from a URL on your server either in sync mode using HTML_AJAX.grab(url) or in async mode using HTML_AJAX.grab(url,grabCallback), where grabCallback is the callback function HTML_AJAX automatically calls after grabbing.
Using HTML_AJAX.replace('target',url) replaces the HTML element that has the target ID with the content from the URL.
For security reasons, you can only grab from URLs on your server. This is not an HTML_AJAX-specific feature, but a limitation in your browser to prevent cross-site scripting (XSS) attacks.