Jan 15th, 2018
23:56 PM PST
diana       sean                         martha  
email   blog code files links photos email


shrum.net /sean/code/cats


documentation files templates support


CATS or [C]ontent [A]cquisition and [T]emplating [S]cript is a dynamic open-source content compiler and formatting engine written in PHP. The main function of CATS is to manage all aspects of site content distribution from datasets returned via plug-ins that deal with various data sources for various content systems (blogs, photo galleries, file lists, database, etc.).


CATS is a content distribution system (CDS)  as opposed to a content management system (CMS).  The main difference between these is that a CDS is a zero-administration system.  This means no user logins, no 'publish dates'.  The focus here is on generating dynamic content that incorporates new data as soon as it's available.  Think of it as 'post-&-play'.

CATS utilizes a plug-in scheme for content retrieval from any type of source. This CATS + plug-in combination gives the system the ability to create dynamic web pages based on data of any source, while also allowing for customizable data retrieval processing.  Using SQL-like data evaluation allows for template-driven content display.  For web page generation, CATS uses simple HTML-based template files to handle keyword and field data insertion and page nesting.




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 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.


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 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).


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:

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.


At the heart of this system is the main script file: cats.phpThis 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.


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.


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

  • PAGE = site identity template

  • NAV = navigational elements template

  • TABLE = results table page (borders)

  • HR = horizontal rule template (between rows)

  • RECORD1 = record template for row 1

  • RECORD2 = record template for row 2

  • RECORD3 = record template for row 3

  • RECORD4 = record template for row 4

Template parameters are typically defined in the cats.ini file so you don't have to keep typing them in every query string.

Any of the cats.ini definitions can be over-ridden by passing the parameter with a new value via the query string.

Further reading

If you're new to CATS, I suggest reading my CATS Primer for Webmasters to get a little of the background and design philosophy.  After that, you'll want to take a look at the Installation Guide - Step by Step. If you already have CATS installed, review the Script Parameters - A to Z.  Lastly, when you start creating your own templates, take a look at the Template Tokens write up.  Enjoy!


If you have any questions, comments, suggestions, etc., please make sure to read my Support & Legal page first.  I welcome all input and hope you find my application helpful.

documentation files templates support


feedback print


Cats v.4.06 [open source] Plug-in: "text" Template size: 42 kb Script: 0.0016 secs Plug-in: 0.0010 secs Overall: 0.0026 secs