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!

Caveats

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.

You can only use Ajax with SparseThisPage() (see Advanced PHP Usage). Using SparsePage() will result in the problem that the server won't know the SQL username/password and thus will mess up. A later version of Sparse may correct this problem.
Sparse's Ajax won't be able to detect Sparse tags that are inside other, regular HTML tags (e.g. printing a value inside a link).
File uploads are not supported with Ajax forms. This is a limitation of Ajax in general.
The startMarkup and endMarkup attributes of the error tags are unfortunately unsupported in Ajax at this time.

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.

The function call to SparseThisPage() must be all on one line by itself (nothing before or after it).
Sparse will detect if the first tag after sqlrow is a tr, th, or td tag (due to the DOM table layout, each of these tags must be styled separately). If your sqlrow is inside a table, make sure that the first tag after the sqlrow tag is tr, th, or td.
Putting <body> or <head> tags inside a comment may confuse Sparse, so don't do it.

Throbbers

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:

//SPARSE_IGNORE_AJAX

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