There and Back Again

A chapter from my book, Understanding AJAX has been made available as a digital shortcut. This chapter covers the different ways you can use the data you transfer using XMLHttpRequest.

Document centric approaches based on HTML and XML are described as well as various RPC approaches are shown.

Personally i tend to use JSON based RPC approaches or HTML document based approaches. Document based HTML approaches let you add AJAX support without radically changing your development model, since its just a matter of breaking your pages into small chunks and generating HTML just like normal. RPC approaches allow you to develop JavaScript driven apps, which is great for quick prototyping and small apps, since you can write a backend in PHP and have it made immediatly accessible (at least if you use a library like HTML_AJAX to do the work for you) to your HTML and JavaScript frontend.

In Clearhealth we use both approaches. JavaScript widgets like our patient selector make RPC requests. While screens like the claim editor make standard HTTP POSTs treating each form section like it is its own page.

I don’t do much work with AJAX and XML, but client side XSLT can be a good solution if you need to move lots of data since it tends to scale better to extremly large datasets (especially in IE).

If your interested in the details of these various approaches grab the digital shortcut or pickup Understanding AJAX.

I found a handy tutorial of building a stock lookup plugin for Wordpress using HTML_AJAX. Shows how easy HTML_AJAX makes AJAX.

The only problem I see is the code won’t work in PHP5 since introspection will return the method name as GetQuote instead of getquote.

You can fix this by adding the following to the HTML_AJAX_Server instance.

// Create the HTML_AJAX Server
$objServer = new HTML_AJAX_Server();

// Set php4 case compatability so this code will work in 4 or 5
$objServer->ajax->php4CompatCase = true;

The other option too fix this is too set all the methods you want to register which is my prefered fix since it lets you have nice case in your JavaScript functions in php4

    // Create the HTML_AJAX Server
    $objServer = new HTML_AJAX_Server();

    // Create an instance of our stock quote class
    $objStockLookup = new StockQuote();

    // Register the stock quote object with the HTML_AJAX server
    $objServer->registerClass($objStockLookup,'StockQuote','GetQuote');

If you did this you’ll also have to update the JavaScript to use the cased version of the functions.

As you may have noticed I haven’t been bloggiing much lately, but there are a couple good reasons why.

First I’m getting married, planning the wedding tends to take a bit of time.

Second i’ve been working really hard to get a book about AJAX done.

The book is finally into production and I’m just starting to get some chapters back from the copy editor.

I do have one thing to share with you today, the books cover.
The complete title is: Understanding AJAX: Using JavaScript to Create Rich Internet
Applications
The ISBN is 0132216353

Also im still finishing up the books appendices which list AJAX libraries, so if you know of AJAX libs for various languages please let me know, im especially interested in AJAX libs for C#, Java, Perl, and Python I already keep up pretty good with all the PHP ones, and most of the non backend language specific ones.

HTML_AJAX 0.4.0 has been released. You can upgrade using the PEAR package manager in the normal ways.

The biggest new feature is the addition of a setInnerHTML method that runs any JavaScript in the string your using to update and elements innerHTML property and the addition of an ordered queue. The ordered queue makes your AJAX requests return to the client in the same order they were sent. One of the biggest area’s this comes into play is when creating livesearch implementations or any other time you’re making lots of AJAX requests and overwriting the results of the earlier ones with the results of latter ones.

More details (including a place to put testing results for your browser of choice) are available in the release notes on the HTML_AJAX wiki.

I’d also like to thank Laurent Yaish for helping with the testing of this release and Arpad Ray for working with me until we got the optimal implementation of setInnerHTML.

Over the weekend my file upload progress meter code got lots of traffic. It seems it made it made it on the del.icio.us popular list as well as getting over a thousands diggs. To celebrate this i’ve updated the code.

The main new feature is giving you feedback without having to patch PHP. Now the patched version gives you more information such as upload speed and estimated time to completion. But we still provide some nice user feedback even without it now.

I also created some wiki pages to start the documentation process.

So here are the demo’s

With the patch and extension
Without the patch

To get upload speed you will need to download and install the PHP Upload Progress Patch and extension.

If you want to use the code you need to:
Install HTML_AJAX (pear install HTML_AJAX-alpha)
Download PAFUPMU and install it somewhere accessible.
Add the code to your page using demo.php as an example.

The basic way the code works is we take a form containing a file upload and submit it using a hidden iframe as a target. Doing this lets the upload happen in the background. Then we poll the server on a regular basis (say a 2 second interval) asking it for update status. If you have the patch+extension installed this gives you file upload speed etc. If you don’t have the extesion we stop making AJAX calls and just animate the status bar until the upload finishes in the iframe and tells us were done.

In demo.php we handle generating the current page and handling the upload in the same page. So we start by handling the update.

<?php

include 'UploadProgressMeter.class.php';

$fileWidget = new UploadProgressMeter();

if ($fileWidget->uploadComplete()) {
        // output javascript to the iframe to send a final status to the main window
        // this will catch error conditions
        echo $fileWidget->finalStatus();

        // move the file(s) where they need to go

        exit;
}
?>

?>

This code only runs when your uploading so you’ll never see the output of it. This can make debugging problematic. One way around this is too hack the UploadProgressMeter to make the iframe non hidden.

Next you setup the JavaScript needed, first HTML_AJAX and then the uploaders JS.

demoserver.php is included in the source, you might want to name it something else if you actually use this code. Its just a page using HTML_AJAX_Server to register the UploadProgressMeterStatus class

You also need some CSS to style the progress bar. The only important thing is that .progressBar and .progressBar .bar are relatively positioned.

Finally you finish things up by building a form. Note that you can include other elements in the form, but if they need to produce output you’ll have to manage calling back into the parent page from the iframes output.

So i just saw a great piece by Harry Fuecks on how latency can effect AJAX requests. Its one of his demo’s from the ajax@localhost presentation he gave at the PHP Conference Uk.

Now this showed a number of interesting problems, and while HTML_AJAX does a bit better then some toolkits it doesn’t handle them all. However thanks to HTML_AJAX’s design it not that hard to work around some of them.

So to that extent here is a really simple livesearch demo that keeps the reponses in the same order as the requests. The server is adding latency for you so you don’t need to worry about setting up a proxy to try it out. This is only available from HTML_AJAX svn right now, but we should do a release in another week or so there are lots of other good fixes in it.

Please note this queue isn’t really all that great for livesearch (ie it pounds your server). The current queue that is recommened for livesearch (and the one that HTML_Quickform_Livesearch (demo on my server, not the final version) uses sends a request at a maximum rate of every 350ms (this rate is configurable) instead of per character typed.

Finally this is just a quick hack, if you set the latency up too about 10 seconds you’ll start hitting some bug in the timeout code. The timeout is getting combined amoung multiple elements or something. The JS code might be really leak happy too, the queue doesn’t actually have all that much control of what happens when a request is complete just in when it sent in the current design. So to get around this i replace the users callback with one in the queue, and then do some closure fun. And here is the new queue code if you want to take a look.

I answered an FAQ question tonight on the HTML_AJAX wiki, im posting the answer here as well since I know most people don’t check the wiki for changes every day.

Outside of this answer I’d like to hear from what other libraries people would like too see integrated with HTML_AJAX and the reasons for this.

Question:
Will HTML_AJAX integrate with other Javascript AJAX libraries such as scriptaculous? How would this integration look like?

HTML_AJAX doesn’t have specific plans to integrate with other JavaScript libraries. Part of this is because external dependencies make for a more complicated installation process. It might make sense to offer some optional dependencies on a library like scriptaculous automatically using its visual effects for the loading box or something, but there isn’t a lot to gain from making default visuals like that flashier since they are designed to be easily replaceable.

Most integration would take place in higher level components. Its unclear weather higher level components like that should be part of HTML_AJAX delivered through PEAR or if they should just be supported by HTML_AJAX and made available from http://htmlajax.org or some other site. If your interested in building widgets or components based on HTML_AJAX please let me know.

HTML_AJAX does however offer the ability to use its library loading mechanism with any JavaScript library. I use scriptaculous in conjunction with HTML_AJAX and I load both libraries through the server.

To do this you just need to register the library with your server and load add its flag to your include line.

PHP code

<?php

$this->server->registerJSLibrary('scriptaculous',
    array('prototype.js','scriptaculous.js','builder.js','effects.js','dragdrop.js','controls.js','slider.js'),'/pathto/scriptaculous/');

?>

HTML

I did an email interview with PHP Magazine.

Its mainly about HTML_AJAX but there were also some general AJAX questions and questions about PEAR. Responding to an interview like that takes a lot longer then I thought. Anyhow if your interested in the future plans of HTML_AJAX check it out.

HTML_AJAX 0.3.4 was released today, it contains lots of bug fixes so if you use HTML_AJAX you’ll want to upgrade.

Release notes and testing results are available on the wiki, and the examples are available online if you want to see some of the basic features.

I’m hoping to do a beta release soon, so if you have time to help with an API review please get a hold of me.

I’m trying out something new here, every week i’m going to write a short post describing an HTML_AJAX feature. Hopefully this will get some people started using the new features and maybe even get some more developers helping out with the project. It will also give me a place to try out some material for my upcoming AJAX book.

JavaScript Behaviors

JavaScript Behaviors are pieces of JavaScript code applied to DOM elements through the use of CSS selectors.

HTML_AJAX ships with a slightly modified version of the Behaviour javascript library. The slight modification is the replacement of the css parsing/selecting code with Dean Edwards cssQuery() library. This was done for a couple reasons, first the css code in behavior is under an unknown license and Dean’s code supports more of the css selector including most of css3.

I also used the American spelling of Behavior instead of the British (darn extra u’s)

Turning Behaviors on

Assuming you already have HTML_AJAX installed all you need to use behaviors is add “behavior” to your list of libraries.

If you just wanted the behavior library you could do:

Or including it with some of the other HTML_AJAX pieces

Adding Behavior Rules

In most cases you’ll want to put your behaviors in their own JavaScript file, that way they can be reused and they don’t clutter up the html, thats the point of them after all. But you can just toss them in a script block in any file.

An example rule is shown below:

Now this rule is rather worthless since its just setting a style rule, something that css is much better suited for but it does show a couple important things. You have immediate access to the matching elements, this allows you to create new child elements, update properties including innerHTML, and set event handlers.

You can set event handlers using onEvent methods but i prefer to use a couple util methods in HTML_AJAX that map to setEvent etc.

A more useful example which submits all the forms on a page using AJAX is shown below:

There isn’t a lot too see here, we build a function to handle the submit event. It submits the form using HTML_AJAX.formSubmit, the first param is the form to submit, the second is the element to update (The second element is optional but do a bug in 0.3.3 it not being set isn’t detected correctly so you’ll have to upgrade to 0.3.4 to skip it). Then we cancel the normal form submission.

Wrapping it up

These examples show some of the power of behaviors, but there really is a lot more that you can do with it. If you have any tips feel free to leave them on the wiki or as comments to this post.

Run the example.

View the full example Source.

Download the example code.

If you’ve used HTML_AJAX to make something cool I’d like to hear from you.

If what you’ve created is publically accessible that would be even better.

Just leave a comment on this post saying what you’ve created and given a link to it if you can. Any suggestions on improvements that would make further development easier are also appreciated.

HTML_AJAX 0.3.1 is out, lots of good bug fixes, and iframe fallback support for Opera and IE with activeX turned off.

More details are available on the release notes on the wiki.

I would like to thank Elizabeth Smith for all her testing and bug fixing in this release.

Feature wise were getting close to beta release, its mainly getting a browser compatability test suite added in and doing some basic API review. If you have experience supporting an API without breaking bc, it would be great to get your feedback on HTML_AJAX.

HTML_AJAX 0.3.0 is huge leap forward from the previous versions, although it still remains mostly backward compatible with earlier releases. Currently the only change in API occurs in Main.js - some event handlers were colliding so name changes were made. The effected methods are onOpen -> Open, onLoad -> Load, onProgress -> Progress, onSend -> Send. This shouldn’t affect too much code.

One of the most important and exciting changes with HTML_AJAX 0.3.0 is the addition of three new developers who have been putting a lot of time into the project. They totally eradicated every item on the original todo list, and the feature roadmap has jumped ahead.

There are considerable improvements in the behind the scenes code. Using the new HTTP client pooling reuses XMLHttpRequest? clients, giving you a speed up when making lots of requests. This is especially useful for IE, where activex object creation can really slow things down. The new priority queue allows you to make many requests and tag the ones that are more important to be sure they are executed first. HTML_AJAX_Util received several bugfixes and new methods to make debugging javascript a little easier, including a varDump() and getType(). As the code base grows, both in javascript files and in php files, some minor rearranging has been done as well.

On the user end, there are several new serializers to use - you don’t have to be limited to just JSON, Error or NULL. Now you can use php based serialization, url encoding serialization, or HTML_AJAX_Action - which eliminates the need to write client side javascript to handle the data returned from ajax callbacks. There were several bugs fixed - most importantly was a huge bug in Opera and the way it handles unknown Content-Types - it seems to translate them to binary so a workaround was needed.

The examples directory has some great new code to show the power and flexibility that HTML_AJAX can provide in applications. There’s still a lot to do, just take a look at the roadmap, but with this release a huge amount has been accomplished.

As always were still looking for new people to help out. People willing to put time in testing and supply bug fixes for there browser of choice would be especially helpful. It doesn’t take a lot of time unless your favorite browser is horribly broken, but the through testing makes a huge quality difference.

You can upgrade your install as always using the pear installer. If your looking for a full changelog you’ll want to check out our new wiki.

The couple pages of docs I’ve had here on my blog are moving there. Were using yawiki from Paul M Jones, and aside from a couple minor points its been great to work with.

This is a minor bug fix release, the big fixes updating serverl url handling and some fixes allowing you to specify a class name with case when exporting it.

The server url handling allows you to add parameters like a session id to your url.

The case changes allow you to register a class like:

$server->registerClass($instance,’NameWithCase’);

and have it work right on php4 and php5.

The second change was made while updating the UploadProgressMeter to php5. I don’t have a tarball release of that yet, but its in svn (web) now if you want a version that doesn’t rely on JPSpan.

I gave a presentation at yesterdays azPHP Meeting.

The slides from this are now available.

Also there should be another HTML_AJAX release today fixing and annoying bug.

This release is a mix of bug fixes and new features.

There shouldn’t be any reference bugs left so those of you running on php 4.4 or 5.1 should be fine now.

The only item that should cause you problems is that php 4 exports method and class names to JavaScript lowercase while php5 does it in the specified case. So if you want php4 and 5 compatability you’ll need to specify the methods to export. A lowercase all option is on the list of things to do.

Changes:
There is now a append util function on HTML_AJAX
New HTML_AJAX_Debug and HTML_AJAX_Helper classes, look at the examples to see there basic use
HTML_AJAX_Server::registerJSLibrary added to allow you to use the same server class to export you own js libs
multiple client libs can be combined into a single request server.php?client=main,httpclient,customlibname (see helper_usage.php in examples for details)

The default loading implementation has been moved to its own javascript file. If you don’t want the default implementation just don’t include this lib. The implementation has also had a half second timer added so it only shows on slower calls, so if your using it on intranets, you won’t see if for your really fast calls.

Start on a serializer built on php’s serialize call. Be aware this hasn’t had much testing and that it has security issues in older versions of php (bug in unserialize call) and may never work correctly with multibyte characters until php6, but it may be faster and like any serializer its optional.

I’m sure there was some other stuff too. Also like any OpenSource project were looking for more help, including people willing to work on docs, do core development, and auxilary classes for items like template or framework integration. Some widgets may also find there way into HTML_AJAX as optional components so if your interested in writing any let me know.

I just released HTML_AJAX 0.2.1, if your running 0.2.0 you’ll want to upgrade immediatly since this fixes a bunch of bugs I added in that version.

The main changes are:
Bugs:
Remove debug message when throwing an exception
Fix problems with async calls
Fix broken content-type detection
Stop trying to run an init method when the init flag isn’t set
PHP required version moved to 4.1.0 which is what it should need

Features:
A basic debug class has been added, allowing you to write PHP errors to a file
HTML_AJAX.replace now works async

Also there is now a mailing list for HTML_AJAX.

HTML_AJAX 0.2.0 is out. There were a number of changes most of them on the JavaScript side.

The code is now released on the lgpl so thoses of you with GPL apps should feel comfortable using it now.

I don’t have time to write another tutorial showing off the new changes but if your looking a good place to start is with the new HTML_AJAX_Request class in JavaScript. All AJAX requests happen by creating an instance of this class and then running it through HTML_AJAX.makeRequest. If your looking to integrate your own complex widget this is the place to start.

The changelog has some more information.

Also im hoping to get the PHP side fully stabilized soon so we can move to a beta. If anyone has time I would appreciate an API review, mainly on HTML_AJAX and HTML_AJAX_Server.

Finally i’d like to drop the PHP dependency to something lower then 4.3.0, if you’ve used HTML_AJAX on 4.2.x or something else let me know. Once i’ve had confirmation it works i’ll lower it.

The roadmap has also been updated

I was contacted by the Mark Withingon, founder of the Boston PHP Users group today, there looking for someone who could do a presentation about HTML_AJAX for them in November. Now I would love to fly there and help them out, but its not going to happen, so the best I can do try to find someone else.

If your interested let me know and I’ll and get your in touch with Mark. I’ll be doing a similar presentation for my local PHP users group that same month so we should be able to share slides and preparation effort.

A new article in php|architect is out, and an article I wrote about AJAX is in it.

The article gives a good introduction to AJAX as a concept and then moves into practical use.

The issue looks like a good with an article about PEAR 1.4 channels as well.