CATS

Example  Example
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. 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 associative array where the first record will contain the key (or field) names. This array 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 within the CATS system. 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. 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 key names in the array 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).

CATS.PHP

At the heart of this system is the one script file: cats.php. The best thing I can compare it to is Crystal Reports (if you're familiar). This script deals with all the mundane tasks needed to be done in order to composite fill 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 composition (nesting, keyword substitutions).

7. But most importantly...TONS of debug output when things don't work.

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, bypassing the code handling that parameter.

In a case where the page generated isn't pulling from a data set, you can set "plugin=null" and the script will generate a static page, bypassing data retrieval and sort/search functions.

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.

Plug-ins

Plug-ins handle all data mining and pass that to the script in an assocative array.  Plug-ins can be created to retrieve data from any source your web server has access to.

Plug-ins are fairly easy to create knowing a little about PHP and arrays.  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 array of associative arrays, or an empty array on ZERO results

3. the first row of the array much contain column names (used in "search-and-replace" functions)

Example

PHP.  Below, I've outlined a basic 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 but you can create customized output by augmenting these or building your own.  Below is asimple, 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:    if (file_exists($sPathname)) {
06:       $aDirectory = dir($sPathname);
07:       while ($entry = $aDirectory->read()) {
08:          $aResults[] = array (
09:             "name" => $entry,
10:             "size" => filesize($sPathname."/".$entry),
11:             "type" => filetype($sPathname."/".$entry));
12:       }
13:    }
14:    return $aResults;
15: }
16: ?>

Step by step:

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 'dir' value provided on the query string (4). For error checking we confirm that the $sPathname exists (5) and if not we return an empty array (14). Once PHP deals with retrieving the filenames (6), the plug-in processes them, each one in turn in a while loop (7). On each entry, the plug-in saves the file info into the $aResults array(8), storing the filename (9), byte size (10), and file type (11) of the entry.  After all the entries are processed, the populated $aResults array is returned (14).  Note that the name you give each key ['name' (9), 'size' (10) , and 'type' (11)] is what CATS will look for as the record token in your record templates. 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.

The data returned from the directory.php plugin (if the specified 'dir' exists), gets passed to CATS in it's RAW state. CATS handles basic sorting, filtering, and slicing based on what is being requested in the call.  Say you wanted only ".php" entries, listed alphabetically by name, and only records 4-6:

If you find that the amount of filtering you desire from the built in CATS functions are limiting you can specifically code a plugin to OMIT (or add) certain entries as well, if the need to generate a different dataset is required.  Once all the operations on the dataset are done. CATS can being the process of filling in the record template with the data values here via record tokens. This just one example of what can be accomplished via plug-ins. Now that you know where the data is formatted, where can we get data from...

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 with including but not limited to: blogs, photo galleries, link lists, file lists, MP3 repository lists, RSS feed reading, databases, ..., basically anything.

Templates

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