CATS Primer for Webmasters

If you're new to CATS or want to know the background and thinking behind the script, this document is for you. While the information contained within this document is good to know, it is not necessary reading. If you do plan on modifying the script, this document will help provide insight as to the process flow and give suggestions on the tools to use.

In the beginning...

Back before all the open-source RDBMS and content management systems (turn of the century...1999 or so), there really wasn't a (cheap) way for general every day users to display on-line table data without having purchased database access services from a web host.  These services weren't cheap, were MS Access-based databases only (and hence could only be found on NT-based web servers), and were geared toward businesses that wanted to maintain on-line inventory/sales databases.

I wanted to keep track of my family members' birthdays in a table and have a easy way to display them in a web page.  And so I begun...

Being slightly resourceful and not very well paid, I opted to not purchase my web hosts NT/database plan and decided that I would make full use of the Linux-based hosting tools and learn Perl by creating a script that when given a filename and a delimiter designator, would create an HTML table with the data located within it.  Because the delimiter was definable, I could use the script on any text-based table: CVS tables, Pipe-delimited tables, etc.

And it worked great!  Only problem was that the layouts all looked the same and there was no real query ability...it just output table data into a nice HTML-based table.

Later on, as my Perl abilities progressed, I implemented the idea of a page template to be able to place my table data into different looking content scenarios.  Now I could create a page template (a site identity page) and could place the HTML-based table into that.  This was slightly better but still, no real query ability.

Again, and after many discussions on www.perlmonks.com, I began to play with DBI and DBD::AnyData.  DBI is Perl's DataBase Interface and DBD::AnyData, written by Jeff Zucker, is a DBI driver that allows for querying almost any data source:

"The AnyData modules provide simple and uniform access to data from many sources -- perl arrays, local files, remote files retrievable via http or ftp -- and in many formats including flat files (CSV, Fixed Length, Tab Delimited, etc), standard format files (Web Logs, Passwd files, etc.),  structured files (XML, HTML Tables) and binary files with parseable headers (mp3s, jpgs, pngs, etc)." - AnyData readme

Needless to say, as others created format readers for AnyData, all I needed to do was download the format file and my script could now parse that data format.  I even wrote a format parser called Directory.pm (based on Jeff's MP3 parser) that allowed for SQL querying of file directory results (which CATS does).

This combination worked great and I used this to create CONTENT.PL.  Here I was now able to have 3 nested template levels (page, table, and record), and was able to do full SQL-based queries on the data.  However, due to a lack of features (or functions) in the SQL::Statement package (which are probably implemented by now as my discussions with Jeff would have lead me to believe), I needed to find a different database backend to drive the script that conformed more to the SQL standard.

About this time, PHP and MySQL were getting pretty hot...and were free.  I began recoding my CONTENT.PL into (what I then called) MYSQLCMS.PHP.  As time passed by and as I came closer to finishing my code rewrite in PHP, I renamed the script to CATS.PHP as the script itself was in no way a true content management system (it was more like a content display system).

As time has progressed and my needs for certain features emerged, I've updated the code and documented my work here at cats.shrum.net. This site is completely driven by the script and therefore should pose a good example of what can be accomplished if you decide to use it

Design Objectives

CATS is currently defined by the following design objectives:

Allow for various content source acquisition...

Currently, there are 6 types of acquisition-able content that CATS can retrieve:

1. Local, directly called pages
2. Local, HTTP call pages
3. Remote, HTTP call pages
4. FTP called pages
5. MySQL database tables
6. Local directory contents

Allow for as many content scenarios as possible w/o having to modify the original code...

Since the script is controlled by parameters that you predefine in the cats.ini or supply through the query string, the script can be used for different types of content situations by simply supplying different parameter values...all without having to recode the script to handle the new formats or layouts.

Allow for SQL-based queries on directory results...

The script handles this by querying a directory on a DIR parameter call.  CATS requests all the file information from the server and saves this information in a MySQL table.  At that point, the directory results are now searchable just like any database table.

Complete separation of layout, coding, and content...

Most web pages, in order to do something dynamic, require some sort of script call to be embedded within the HTML of the page.  This is no longer the case with CATS (although you can still do this if the need arises).  This allows web designers to construct pages without having to place *hidden* codes in their files to deal with these content situations.  No special authoring tools are required so page designers can continue to use whatever tools they choose.  Layout designers can concentrate on visual appeal, and content creators can issue content without having to know any programming.

Application process outline

With CATS, each final output page utilizes 5 (or more) HTML-based template files:

1. Page template; site identity page,
2. Body template; for recordset descriptions,  recordset title, etc, think "opening paragraph"
3. Nav template; typically used for sub area navigation (a page that contains relevant links to the area your under)
4. Table template; for table borders, recordset navigational / pagination elements
5. Record, record2, record3, and record4 template(s); for record data layout

When CATS is called, the first thing it does is construct the runtime Params.  There are 3 locations for parameters and each one is superseded by the next.  they are:

1. Script defined parameters (those that are listed in the cats.php file); lowest priority
2. Foldered [cats.ini] files,
3. Query string supplied settings (key/value pairs that are provided in the URL; highest priority

After this point, CATS confirms the existence of and loads the template files defined by the page, body, table, record, record2, record3, and record4 parameters (if defined)and stores the page data into the [Templates] array. 

Next, CATS checks to see if a plugin is specified or not, as not all page creation is dynamic. If not, CATS reverts to a static page creation mode, bypassing all data retrievals and querying and goes straight into [PAGE] building and 's&r' (search and replace). However, if a plugin is defined, it is called with the complete [Parameters] array. 

Every plugin contains function main(). This function automatically launches from CATS which passes [Parameters] to it.  The plugin can do what it needs to do, using the values in the [Parameters] area for direction, and upon completion should return an associative array of data or an empty array on no results. These key names are what are used in record 's&r' operations later.

CATS then runs 3 functions on the data array using the broken down SQL-like parameters values: select, from, where, order, sort, group, and limit::

1. Total query (for records total),
2. Filtering, either field specific or fuzzy search and
3. Subset return (for LIMIT based recordsetsl).

CATS reviews the match and return query results to determine the appropriate pagination values.  Once this is done, the script retrieves the return query record set and begins s&r operations. 

Starting with the first record in the return set, CATS creates virtual copies of the record templates and starting with the first row in the returned set, goes to each record, replacing the tokens in the templates with the data located in each record using the table cell field names as tokens.  Based on the values defined for the results table (a pseudo-level template that you control via script parameters: cols, rows, width, border, align, valign, rowcolor1, rowcolor2 ), CATS then places the populated record template into the results table.  This process continues until all the data in the returned set are read.

The populated results table is then nested into the template defined by the table parameter which is in turn nested into the template defined in the body parameter which is nested into the template defined in the page parameter.  At this point, page composition is complete but still needs to go through one final s&r cycle.  This process takes all the various [PARAMETER], database data, pagination data, etc. and searches in the [PAGE] for corresponding tokens (discussed later...or now if you're curious) and replaces them with runtime values. 

Once all the data is replaced, the script then outputs [PAGE] to the visitors browser for display.

The next step: Installation

Now that you know the *how* and *why* of CATS, I would now point you to the installation documentation that will walk you through the process of setting up CATS to run on your website.  It's really just a matter of copying some files over. The document covers system requirements so before you go off shouting "The British are coming", read the document.  Any questions that you may have along the way, you can use the 'support' link near the top of the page.