Sparse - Advanced PHP Usage

Most of Sparse's functionality takes place internally, so you don't have to worry about most of it. But you can use Sparse in a variety of ways. The useful functions are as follows:

SparseThisPage([$username,
[$password, [$host]]])

Executes Sparse on the current page. The PHP fragment that contains the SparseThisPage function call will be ignored; all other HTML and PHP code will be parsed. Note that Sparse can use the "global" MySQL connection, so if you already have one up, you can skip the arguments. If the "host" argument is skipped, "localhost" will be used.
This function call must be done before any output is printed - in other words, it must be enclosed in a PHP tag at the very top of the document, before the <HTML> tag. It will call exit() when it finishes, so make sure to do any further processing before you call it. You can do more processing in a separate PHP tag if you wish, though; only the current PHP tag will be ignored after SparseThisPage is called.


SparseThisPage($connection)

Same as the above function; however, if there is only one argument, it will be taken as a MySQL connection resource.

SparsePage($page,
[$username, [$password, [$host]]])

This allows you to execute Sparse on an arbitrary file. The first argument is the file path (relative or absolute), and the other three arguments are treated as in SparseThisPage. Note that you cannot use Ajax functionality if you use this function.

SparsePage($page,
$connection)

This allows you to execute Sparse on an arbitrary file. The first argument is the file path (relative or absolute), the second is a MySQL connection resource.

Using PHP In Templates

You can use your own PHP code anywhere in a Sparse template - it will be stored along with the cached code and executed each time the page is called. You can include any kind of code you want, including leaving off a tag with an open { bracket to conditionally print out HTML code. In fact, you can even use it to conditionally parse Sparse tags like sqlfield! For example, let's say you only want to include a particular field if the user viewing it is logged in:

<?php if (isset($_COOKIE['username'])) { ?>
<td><sqlfield name="password" /></td>
<?php } ?>

Remember that your code will be executed inside a function (inside an object), so if you want to access a previously defined variable, make sure that it's a global variable and access it by $GLOBALS. In addition, you can use the following variables (please READ ONLY, do not write to them!)

$this->current_row: The current row in the data being displayed. You can e.g. use this to alternate colors for odd and even rows.
$this->data: The full dataset that was returned from the query, consisting of a 2D array (indexed 0 to total rows)
$template->page: The current page the user is viewing (starting from zero).
$template->totalRows: The total rows in the query - i.e. NOT just the ones displayed on this page, but all of them together. You can get the total rows displayed on this page by accessing count($this->data).
$template->message: The general message calculated to print out to the user. See sqlmessage.
$template->row_errors: An array of errors (one per row) which would be printed out in an sqlrowerror.

The First Tag - SparseThisPage()

If you're using SparseThisPage() as your function call (allowing you to put all your Sparse and PHP code in a single page), the first PHP tag (from <?php to ?>) on the page is unique. The following things are true about it:

All code after SparseThisPage() will be ignored, because SparseThisPage() calls exit(). You can either put the code in a separate PHP tag, or before the SparseThisPage() call (e.g. if it needs to be done before the data is updated).
Make sure not to output anything before SparseThisPage(), though, because it may try to set cookies when it launches, which it does via headers. In other words, if you have stuff to do on the page before the default behavior of Sparse happens, you'll have to do all the logic before the call, but all the output in a separate PHP tag.
Any functions you wish to use in your Sparse template (e.g. in the sqlfield returnValue or displayValue attributes) must be declared in this first tag before the call to SparseThisPage(). Functions declared in subsequent tags will give you a warning that you're trying to declare them twice (because they're declared once when the page is loaded and again when the PHP code is actually executed). Note that if you include a separate file with your functions, you can stick the include statement wherever you like and can bypass this problem entirely.
Be careful if you forward your user to another page upon completion by using the sqlaction onAction attribute. When forwarded, all the GET/POST data will be lost. If you want to work with that data, be sure to do it before calling SparseThisPage().

Previous: Configuring Sparse | PHP Reference | Next: Ajax