+ Script info

+ List of available parameters and their script set defaults (null'ed items unless specified get UNSET()):

+ Importing 'cats.ini' key => value pairs from all directories starting in [DOCUMENT_ROOT] thru /sean/code/cats...

+ UNSET()'ing any parameters = 'null'....7 parameters removed

+ Current [PARAM]eters for this page (CATS.INI::[defaults] + URL-based parameters)

+ Current [KEYWORDS] for this page (CATS.INI / [keywords])

+ Retrieving templates...

+ Combining templates; [RECORD]set=>[TABLE]=>[BODY]=>[PAGE]<=NAV

+ Applying S&R on tokenized entries (parameter, _SERVER, keyword, and script)...shrum.net/sean/code/cats
 
Wednesday, Feb 4th  2026 @ 17:19:36  
 
 
  
www . shrum.net /sean/code/cats
All scripting, coding, html, layout, design, .... basically everything here done by yours truly. - S

  

  
 
 
documentation templates news
 
filter
  clear search
 
 
CATS

CATS

CATS or [C]ontent [A]cquisition and [T]emplating [S]cript is a open-source content compiler and formatting script 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. or to composite static pages to build 1 page by using multiple input pages : sitetheme.html, nav.html, body.html, etc.).

Introduction

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                    
 

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:

name size type
. 246 dir
.. 162 dir
blog.php 5595 file
favorites.php 706 file
files.php 1449 file
plugins.zip 2594 file
rss.php 532 file
textconvert.php 5398 file
_vti_cnf 182 dir
static.php 51 file
directory.php 368 file
text.php 4742 file
update.php 4912 file
caption.php 4542 file
name size type
. 246 dir
.. 162 dir
_vti_cnf 182 dir
blog.php 5595 file
caption.php 4542 file
directory.php 368 file
favorites.php 706 file
files.php 1449 file
plugins.zip 2594 file
rss.php 532 file
static.php 51 file
text.php 4742 file
textconvert.php 5398 file
update.php 4912 file
name size type
blog.php 5595 file
favorites.php 706 file
files.php 1449 file
rss.php 532 file
textconvert.php 5398 file
static.php 51 file
directory.php 368 file
text.php 4742 file
update.php 4912 file
caption.php 4542 file

 
name size type
rss.php 532 file
textconvert.php 5398 file
static.php 51 file
Plugin RAW data Order and Sort Fuzzy search Limit
cats.php?dir=/plugins&plugin=directory &order=name&sort=a &search=.php &limit=3,3

[ Example tables above generated by CATS &debug=y mode as troubleshooting aids ]

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:

  • PAGE = site identity template (top level and sub nav links should be stored here)

  • BODY = main page contents (static); description of recordset, (subnav links should be stored here)

  • NAV = subnav link file

  • TABLE = results table page (pagination links, borders)

  • HR = horizontal rule template (between rows)

  • RECORD = record template for entry

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!

 
 
top

Page generation time = 0.0024/s
Page size (minus graphic elements) = 63kb

bookmark

 feedback print

back
Since 1992 - shrum.net

Copyright 2026 Sean Shrum

 
 
CATS.PHP [C]ontent [A]cquisition and [T]emplating [S]cript v.4.14 [ 2025.12.14 ] by Sean Shrum