There and Back Again

Say Hello to HTML_AJAX

HTML_AJAX had its first PEAR release today. Its the same version as was voted on so there is no new code but you can use the PEAR installer to get it.

Once you have it installed you’ll find the examples in the docs dir to be quite helpful, on my server thats /usr/share/pear/docs/HTML_AJAX/examples. These examples are also available online: run, view code.

I’ve started a basic website for the project, it includes a development roadmap, so if you want to help out, or just want to know whats happening next thats a great place to start.

HTML_AJAX has two different main use cases, standalone and proxy.

Now in proxyless/standalone mode you can use just the JavaScript library making requests to pages and working with its results however you want.

To accomplish this basic usage you either need to create a instance of a server class that will server the JavaScript libraries, or copy them into your web root. These js files are located in your pear data directory, on my server thats: /usr/share/pear/data/HTML_AJAX/js.

Setting up a server that will handle client requests is easy, a basic one is shown below:

include 'HTML/AJAX/Server.php';

$server = new HTML_AJAX_Server();
$server->handleRequest();

If you save that as server.php you can include the needed JavaScript libraries like below:










Once you have the libaries pulled in you easily make various AJAX calls, the main usage for proxyless operation is to pull down some new content and put it into your page using innerHTML. Any asyncronous example of this is shown below:

HTML_AJAX.grab('/index.php',function(result) { alert(result); });

A sync version of grab is also available, just don’t pass it a callback function. This is even easier to use but has the disadvantage of blocking while the download happens. In some circumstances this can useful since your already in a callback, but you have to be careful when using it. Besides the grab method there is also a replace method it takes an id and replaces its innerHTML with the results. Finishing up the standalone api there is a call method which allows you to call methods on classes registered with the server. Registering classes is shown in the proxy section. A sample async call is shown below:

HTML_AJAX.defaultServerUrl = 'server.php';
HTML_AJAX.call('test','rot13',function(result) { alert(result); },'Hello World');

Call can also be used to do sync calls just pass false in instead of a callback function.

Moving on from the basic standalone api HTML_AJAX offers generated proxy classes. You start this usage by registering a class with the server. The class will be introspected and public methods will be exported (methods starting with _ are considered private).

include 'HTML/AJAX/Server.php';

class test {
  function rot13($string) {
    return str_rot13($string);
  }
}
$test = new test();

$server = new HTML_AJAX_Server();
$server->registerClass($test);
$server->handleRequest();

After that you need to include the generated proxy class. After that you can create an instance of that, when you do it you pass in a callback class. An example of this calling the rot13 method is shown below.


// create an instance of our proxy class, passing in a object with a rot13 function which acts as the callback
var remoteTest = new test({rot13:function(result) { alert(result); }});
remoteTest.rot13('Hello World');

There is some other optional functionality around as well, the examples show documentation of pretty much everything. I’ll write more formal documentation as I have time. If you have any questions feel free to ask them on this post, and i’ll either reply in the comments or in a new post if there is enough of them.

13 thoughts on “Say Hello to HTML_AJAX

  1. terry chay

    You left the block in the last code snippet even though it is javascript. 🙂

    The tgz file has a premature EOF (which doesn’t affect the install).

  2. terry chay

    I’m getting an “undefined” back in all the examples, but since you seem to be using the RAWPOSTDATA, it’s a bit confusing to debug.

    Take care,

    terry

  3. Joshua Eichorn Post author

    I switched the last code block to JavaScript highlighting oops. The tgz is generated by the pear installer so if there is a problem thats why, I guess it might be worth adding a bug for that.

    On the RAWPOSTDATA front thats what you use, your not sending with a form encoding so _POST will never be populated. Which is good cause things aren’t urlencoded, there JSON by default which is just a chunk of text.

  4. Errr

    After that you need to include the generated proxy class. After that you can create an instance of that, when you do it you pass in a callback class.

    What?

  5. vern

    Sometime while reading through tons of AJAX libraries, I think you said something about one of the goals being not having to work with Javascript, and just work with PHP. I’ve been told before that the J in Ajax is Javascript, but if you could make things so that only a minimal knowledge of Javascript is required, you’d be my hero. 🙂

  6. Joshua Eichorn Post author

    Errr, sorry about that not my best writing ever. I also included the include for the proxy class.

    If you look at the output of server.php?stub=test you’ll get a better idea of what is happening. The server generates a new JS class that has a stub method on it for each function on the php side. Each one just contains boiler plate for doing the AJAX call.

    when you create an instance of this proxy class you pass it its callback class. You can do this by passing in a variable instance or since JavaScript is an odd language by creating a hash of functions right there, like i showed in the example.

    Hopefully that clears things up a bit.

  7. SNo0py

    Somehow it seems the site is broken in Firefox – I can’t read the examples 🙁
    Just gray on gray.

  8. Joshua Eichorn Post author

    Things look fine for me, im running the firefox 1.5 beta, but I doubt there was any change. Do you have any user style sheets or extensions running that might mess with colored text.