CATS

Example   Example Example  Example
Data sources Data sources are anything that can be queried, listed, etc.  This means any database, table, file listing, anything that can be queried can be distributed through CATS. Plug-ins Plug-ins deal with a specific data source type (a mySQL plug-in will deal with retrieving data from mySQL databases, a directory plug-in will deal with retrieving file data from the system, and so on) and format the data returned into an standard AoA (Array of Arrays) where the first record will contain the field names.  This AoA gets passed to CATS for keyword replacement and template nesting.  In the event there is a data source that does not have a associated plug-in, anyone can create one and use it with the CATS system. CATS.PHP The brains of the operation.  Takes the data mined via the plug-in and places it into the specified html templates.  Also generates pagination information / links for insertion into templates. HTML Templates Templates are just simple web page files that contain token words (%this% is a token word due to the special char surrounding it).  CATS looks for token words that that match field names in the AoA that was passed by a plug-in.  CATS also looks for non-field related tokens as well such as pagination and navigation tokens

No more having to run one script to handle your blog, another one to handle you online photo album, another for your file server, etc.  No more having to run different scripts to deal with all you content delivery needs.  CATS handles it all!  To help put this into another perspective, think of CATS as "the webmaster's Crystal Reports".  CATS only requirement is PHP. Plug-ins may have other requirements (a MySQL plug-in would require MySQL which should be documented in the plug-in itself and are beyond the scope of this document).

Data sources

As mentioned above, anything you have access to can be utilized with CATS via the plug-in scheme and a specifically coded plug-in for the data type your dealing withincluding but not limited to: blogs, photo galleries, link lists, file lists, MP3 repository lists, RSS feed reading, databases, ..., basically anything.

Plug-ins

Plug-ins handle data mining.  Plug-ins can be created to retrieve data from a specific source that your web server has access to.

Plug-ins are fairly easy to create knowing a little about PHP and arrays (specifically associative arrays or AoA).  Most content scenarios can be achieved using one of the existing plug-ins however, they can also be used as a primer to give you a good start if you should decide to tailor one for your own needs.  Plug-ins can be as simple or as complex as you like and can contain as much or as little validation checking as you wish.  There are, however, three (3) basic requirements for all plug-ins:

1. "function main($aParams)" must exist,

2. function main must return an associative array, and

3. the first element number of the returned array must be 0 (zero).

Example

PHP.  Below, I've outlined a simple plug-in and explained each line to help get your feet wet.  Most users shouldn't need to create custom plug-ins as most content systems can be run with either the files.php or text.php plug-ins that come in the CATS distribution.  Below is a self contained plug-in called directory.php:

directory.php
-------------------------------------
01: <?php
02: function main($aParams) {
03:    $aResults = array();
04:    $sPathname = $_SERVER['DOCUMENT_ROOT'].$aParams['dir'];
05:    $aDirectory = dir($sPathname);
06:    while ($entry = $aDirectory->read()) {
07:       $aResults[] = array (
08:            "name" => $entry,
09:            "size" => filesize($pathname."/".$entry),
10:            "type" => filetype($pathname."/".$entry));
11:    }
12:    return $aResults;
13:: }
14: ?>

When a plug-in is used, it receives the $aParams array (2) from CATS. This array contains all the arguments that were defined either in the script itself, in any associated INI files, and passed on the query string.  First we create a empty Results array to store our data (3).  Then, we define the $sPathname string variable that contains both the DOCUMENT_ROOT and the defined directory (4). Once PHP deals with retrieving the filenames (5), the plug-in processes them, each one in turn in a while loop (6). On each entry, the plug-in saves the file info into the $aResults array(7), storing the filename (8), byte size (9), and file type (10) of the entry.  After all the entries are processed, the $aResults array is returned (2) to the CATS script.  Note that the name you give each key is what CATS will use as the replacement word in your record templates. In the example above, I used 'name' (8), 'size' (9) , and 'type' (10). The record templates that you use with this plug-in will need to contain these token names in order for CATS to do search-&-replace operations.

This a just one example of what can be accomplished via plug-ins. Now that you know where the data is coming from, let's look at where it's going to: CATS.PHP.

CATS.PHP

At the heart of this system is the main script file: cats.php.  This script deals with all the mundane tasks needed to be done in order to serve out dynamic content such as:

1. Parameter collection and validation,

2. Template file retrieval,

3. Recordset querying (filtering, ordering, sorting, ...),

4. Pagination calculation / link construction (first, last, next, previous, ...),

5. Records layout (record insertions, zebra-striping, record/row/column numbering, ...), and lastly

6. Final page compositioning (nesting, keyword substitutions).

Reserved parameters

CATS uses a number of reserved parameters to allow for content querying and recordset layout.   Most of the parameters are optional.  For more details on a specific parameter, such as usage, acceptable values, defaults, dependencies, etc., take a look at Script Parameters - A to Z.  Plug-in authors should keep these in mind when deciding on their own plug-in parameter names.

Reserved value

CATS has one reserved value: null. Because CATS allows you to define defaults both in the script itself and in the CATS.INI files, there may be times when you may want to reset a parameter.  Any parameter set to 'null' like '&hr=null' gets UNSET().   This means that the key/value pair will appear to never have been set and will cause all ISSET() checks to report back FALSE.

Querying

I've tried to stick to using established SQL-esk argument names like ORDER, SORT, LIMIT, WHERE, as well as others to make using CATS as easy as possible for those who already have some SQL experience.  Full text searches can be performed using the SEARCH and IN parameters to deal with data filtering. For complete information on all the available parameters, take a look at Script Parameters - A to Z.

Templates

Currently CATS can use up to 8 user-definable templates in the construction of any page.  The 8 template parameters are: