HTML_AJAX

[ AdvancedSearch | AreaMap ]

HTML_AJAX Manual

What is AJAX

At its core AJAX is a simple technique combining a number of techniques that have been around in web development for years. You take JavaScript and use it to manipulate the DOM of the Browsers. To that you add a web server running a server side language like PHP. Then you combine the two parts using a communication layer that is hidden from the person sitting at their browser.

This hidden communication usually takes place using a built in JavaScript object called XMLHttpRequest, but it can also take place with IFrames, dynamic Script tags and lots of other ways. XMLHttpRequest has the largest feature set and most complete API so it's the best option for the communications channel and it's what HTML_AJAX uses where possible, falling back to using hidden IFrames if support for XMLHttpRequest doesn't exist.

You might have thought that AJAX was just flashy JavaScript, the animations and effects of "Web 2.0". It's not. Don't worry, though, JavaScript is part of AJAX. In order to complete the usability puzzle, you may want to use some of its effects. As for "Web 2.0" there isn't any official definition, so as long as you make a good looking site, call it "Web 2.0" and move on.

If you're interested in learning more about AJAX you might want to check out Joshua Eichorn?'s AJAX book. It covers a lot of ground from different data encodings like XML or JSON to usability. It also includes a large number of examples that will help you see how the whole picture fits together.

If you're scared of JavaScript (the J in AJAX) you might want to brush up on it. The Learning Resources Page contains some books and websites you might find useful.

Why AJAX

So why should you use AJAX? This is both simple and complex. You should use AJAX because it allows you to introduce new content into web pages without reloading the entire page. This ability allows you to access large datasets in a fast transparent manner, giving you all the power of a thick client server application development environment, without all the deployment hassles.

More Here

What is HTML_AJAX

HTML_AJAX is a PHP and JavaScript library released through the [PEAR that gives you an extremely featureful communication layer plus a lot of useful related tools. It doesn't include effects or animations or drag n drop. If you're looking for those I recommend using jQuery or mootools.

HTML_AJAX allows for (at least aims for) the following AJAX programming styles

• JavaScript driven (grabbing normal PHP or HTML pages with a simple straight forward API)
• JavaScript driven to registered PHP classes (HTML_AJAX acting as a controller for your AJAX code)
• PHP driven using helpers to generate JavaScript (Needs the most work)
• PHP driven using an action based approach where registered PHP classes inject actions into the browser using a PHP API
• JavaScript with PHP proxies, PHP classes accessible as JavaScript objects using generated Stub classes
• Some combination of all of these :-)

HTML_AJAX has a bunch of other features these are covered in later parts of this manual

Why HTML_AJAX

So why should you use HTML_AJAX instead of some other AJAX library. HTML_AJAX provides advanced communications features (queues, pluggable serialization/data encoding, error handling), great PHP integration (proxied classes, helpers, action based development), and an easy to use API. It is designed by PHP developers for PHP developers and works hard to present AJAX in a way that is accessible and easy to use.

But in the end what library you use is just a personal preference. Some other library might fit you (or your project) better, there is no best approach just lots of options (some good and some bad).

Remember HTML_AJAX is well prefixed and doesn't mess with core JavaScript prototypes so its easy to mix with other libraries.

Getting started

HTML_AJAX allows for a lot of different coding styles, which is one of its problems. You just got started and now you need to make decisions. But since I'm the author I'll help you out getting started by using the JavaScript API.

Installing HTML_AJAX

But before we can do that lets take a step back and get things installed.
HTML_AJAX is part of PEAR so if you already have PEAR installed you're on an easy street just run <code>pear install HTML_AJAX-beta</code> (the -beta is there because pear only installs stable packages by default, and a stable release is waiting on this manual being done, *Note remove -beta when 1.0 is released*).

If you don't have PEAR you have a couple options, you can [install PEAR] (yes even on shared hosts with only ftp access) or you can download HTML_AJAX and install it by hand.

You can grab the package from: http://pear.php.net/package/HTML_AJAX/download
Untar it and you'll see a directory like:

AJAX
docs
examples
js
AJAX.php

HTML_AJAX_Server

Ok so now you have the install done you'll want to take a look at HTML_AJAX_Server (And for you framework developers out there, no you don't have to use it, but remember I'm making choices in this manual so we're going to.).
You can think of HTML_AJAX_Server as a front controller for AJAX stuff. It contains code to deliver JavaScript libraries, export PHP Classes, and generate JavaScript stub classes for exported PHP classes.

In its most basic usage you make a new PHP script, lets call it ajax.php, in you put:

require_once 'HTML/AJAX/Server.php';

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

Pretty simple right, now for those of you who didn't use the PEAR installer and you still want to use HTML_AJAX_Server to serve up the JavaScript library code then you'll need to add 1 line.

require_once 'HTML/AJAX/Server.php';

$server = new HTML_AJAX_Server();
$server->setClientJsLocation('/path/to/js/lib/from/the/tarball');
$server->handleRequest();

But if you used PEAR just ignore that line, the installer did some magic on install time and prefilled that value for you.

Making an AJAX request HTML_AJAX.grab

So now all the setup is done and we can make an AJAX request.
The simplest way to do this is using the HTML_AJAX.grab function, a simple example is shown below:

<html>
<head>
<script type="text/javascript" src="ajax.php?client=all"></script>
</head>
<body>
<script type="text/javascript">
HTML_AJAX.grab('examplefile.html',function(result) { alert(result); });
</script>
</body>
</html>

As you can see grab is simple. The first parameter examplefile.html is the the url to load, and the second is an anonymous JavaScript function to call when the request is complete.

There are a couple of items to note:

• XMLHttpRequest only makes requests to the same domain, its part of the JavaScript security sandbox, so if you put a url on a different server then the on the script was delivered by you'll get an error.
• grab makes a GET request you can pass parameters in the query string ?foo=bar
• the callback is optional if you don't supply it you make a sync request (don't do that enough you have a good reason)
• grab takes an optional 3rd parameter that allows you set lots of options going so far as not making grab work like grab (but what would be the point of that)

HTML_AJAX.post

Now if you wanted to make a POST request instead of a the GET request that grab did just use HTML_AJAX.post. Post is setup so it will look to PHP like a form was submitted so $_POST will be automatically be populated. Its basic usage looks like:

HTML_AJAX.replace

HTML_AJAX.formSubmit

Exporting PHP Classes

Registering Classes in ajax.php

Options for lots of Classes

Setup Methods

Setup Objects

HTML_AJAX.call

JavaScript proxies of PHP Classes

Changing the formating/disabling the default Loading indicator

There are a couple different options

You can override the loading js functions (HTML_AJAX.Open, HTML_AJAX.Load) http://svn.bluga.net/HTML_AJAX/trunk/js/Loading.js

or you can create a new div with an id of HTML_AJAX_LOADING this will be shown instead of the default one.

Manual Author(s)

This manual was written by Joshua Eichorn?, the original author of HTML_AJAX and author of [Understanding AJAX], an [AJAX Book] which covers the topic of AJAX a lot more then this manual. It doesn't have the same level of detail on HTML_AJAX though it does use it, and Scriptaculous and Sarissa in examples.
Josh also created [phpDocumentor] and writes about AJAX and PHP in his [blog].

Others have helped with this manual they include:
(if you work on this manual add your name here, if you write a lot add a paragraph about yourself.)

This site powered by YaWiki 0.22 beta.