Home | SourceForge | Documentation | FAQ | What's New | To-Do List | Forums | Download | Contact

Sparse - Ajax

What is Ajax? A good overview can be found here. There are some disadvantages to using it, but it's one of the most popular new web technologies and can make your applications look quite impressive. Sparse's edge is that it automatically creates a full-fledged Ajax form for every template! Not only do you not have to worry yourself about the server-side code, you also don't have to worry about the client-side Javascript code. Everything is taken care of!

Ajax is always enabled by default. If you want to turn it off, you'll have to configure Sparse to do so. However, you don't have to worry about clients who have Javascript disabled or who use older browsers, or if a problem crops up server-side - Sparse's forms are fully degradable, meaning that the regular functionality will take over if the Ajax functionality isn't available.

The code generated when running the server side of the Ajax connection is a good deal smaller than the usual code - and it's cached separately so it doesn't have to be generated each time!


Ajax isn't quite as robust and flexible as regular Sparse forms, though most of what you can do can be replicated. If you can't meet these requirements, configure Sparse to turn off Ajax.

Be Careful

Even if you do meet the above requirements, there are a few things that can confuse Sparse, so you should know about them.


Sparse comes with its own throbber image - that's the little animation that appears in the top right when your browser is loading. Often Ajax applications don't give any indication of this, so it's nice that Sparse does! Although the throbber shows up nicely in Firefox, unfortunately I haven't managed to get it to stay in the same place in Internet Explorer (due to its absence of support for position:fixed). I've seen about five different ways to work around this, and none of them have worked, so if you can help, please do!

You can change the throbber image or remove it entirely by configuring Sparse to do it. Some neat ones can be found here.

If the user clicks on the throbber, the current request will abort (similar to clicking the Stop button on a regular browser). This is useful if the request is taking too long.

Your PHP Code (Advanced)

Your custom PHP code will be re-executed each time the server is contacted, and the results will be re-sent and re-displayed on the page - all in Ajax! Not bad, huh? However, there are times when you don't want code to be re-executed each time the server is contacted (e.g. if it outputs a bit of code which won't change each time the user changes the data). You can indicate that the Sparse server shouldn't re-execute the code by including the following line anywhere in the PHP tag:


Each PHP tag (i.e. from <?php to ?>) will be dealt with separately.

Custom Javascript Code (Advanced)

Just like with your PHP code, you can stick custom Javascript code to be executed when a Sparse action button or link is clicked. Just redefine the following functions like so:

sparseInitialUserCode = function(aNode) {...}
sparseFinalUserCode = function(aNode, aXML) {...}

The first function will execute as soon as the button is clicked, and the second will execute after everything is finished. If the first function returns false, nothing at all will happen on Sparse's side; if it returns true, execution will continue as normal.

The aNode argument is the thing that was clicked (either a submit button, image, or link), and the aXML argument is the XMLDocument returned from the server. (If the clicked item was in an sqltoolbox, aNode will simply be any node inside the target template.) The document has the following XML nodes. In the following examples, the template index (i.e., the first, second, third etc. sqltemplate on the page) is {i}, the current row is {j}, and the name of an sqlfield - i.e., the alias used in the returned data, surrounded by `SQL apostrophes` - is {name}.

<error id="sparseMessage{i}" value="error value"/> The general message printed. One per document.
<error id="sqlrowerror--{i}-{j}" value="error value"/> An error for each row.
<error id="sqlerror-{name}-{i}-{j}" value="error value"/> An error for each field.
Every error is always returned, even if blank, because they have to be set to blank if they were already posted.
<datarows value="number of rows returned"/> Only one per document.
<data name="name of field" value="value of field"> The HTML name and new value for each field. The HTML name is sparse_values[{i}][{name}][{j}].

There are other nodes in there, but they shouldn't really be of interest to you.

Previous: Errors | Configuring Sparse | Next: Advanced PHP Usage