Sparse - Configuration

Sparse's behavior can be altered on a per-file basis by using special define() statements. These can be declared on a conditional basis (inside an if statement in the PHP code). They must be declared before including Sparse.php. For example, to turn off Ajax and set the temporary directory, you'd do this:

<?php
define('SPARSE_NO_AJAX', true);
define('SPARSE_TEMP_DIR', 'c:\windows\temp\');
include('Sparse.php');
SparseThisPage('myUsername', 'myPassword');
?>

Note that the option will be true even if the page is executed via the server during Ajax calls. See Ajax for more information.

List of Options

Any option whose value is "true" is false by default (i.e. if left out).

Option	Value	Description
SPARSE_NOCACHE	true	Disable caching of the Sparse code (see below).
SPARSE_NOWARN	true	Disables the warning log (see below).
SPARSE_NO_AJAX	true	Disables Ajax functionality entirely.
SPARSE_FILE_DIR	string	The web address of your page. Only used in Ajax functionality. If you see your Ajax pages failing, it may be because you haven't set this properly. You only really need to set it if your server doesn't use $_SERVER['DOCUMENT_ROOT'] and $_SERVER['HTTP_HOST'] normally. Don't forget the trailing /.
SPARSE_TEMP_DIR	string	By default, Sparse will store its cached code and warning logs in /tmp/ . Use this if you want them to be stored in another directory. Don't forget the trailing /.
SPARSE_LOG_FILE	string	By default, Sparse will store the warning log in SPARSE_TEMP_DIR/sparse_warning.log. Use this to store it in another file.
SPARSE_THROBBER	string	URL of an animated throbber image to be used in Ajax functionality. By default, uses Sparse's throbber image. Set it to "none" to disable the throbber entirely.

Caching

Sparse essentially creates a program out of the templates that you feed it. The program prints information based on the values it's given, errors, current page etc. Rather than recomputing the program each time, Sparse caches it in a file the first time it's computed - meaning that the template is only fully parsed the first time it's loaded in someone's web browser. After that, the program will simply be read from the cache and executed.

Note that Sparse does not check for the structure of the SQL tables. Instead, it compares the modified date of the cache file with that of the script file (i.e., the file that SparseThisPage or SparsePage is called from). In other words, if the template file itself is changed, Sparse will re-parse it. If you want to force Sparse to re-parse the template (recording new information about your SQL tables), simply modify the actual file and save it, or set the SPARSE_NOCACHE option temporarily.

By default, Sparse uses the /tmp/ directory for caching. If that directory doesn't exist, or Sparse doesn't have access to it, it can't cache the page. The easiest way to know if the cache was successful is to view the source of the generated HTML page; there should be a comment at the top saying "Printing from Sparse Cache".

For the record, the name of the cache file is the full filepath of the page that calls Sparse, with / and \ replaced by %, followed by ".sparse".

Remember that PHP must have write access to the SPARSE_TEMP_DIR directory!

Warning Log

Sparse maintains a warning log which indicates any warnings it comes across. These include required attributes not being given, attributes not having proper values (e.g. add, edit, or display for sqltemplate type attributes) or e.g. a name attribute referencing a nonexistent field. By default, these are stored in the file /tmp/sparse_warning.log. Again, remember that PHP must have write access to the warning log.

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