Script Parameters - A to Z

The definitive source for all reserved parameters. Note: All parameters in this document will pertain to the latest release. Newer parameters *will* be added to future versions of the script in which case this document will be updated accordingly. Make sure you're running version 4.14 before you start banging your head on something hard trying to figure out why some of the parameters aren't working.

Reserved Parameters

Below is the current list of all reserved parameters as defined in the latest version of the script.  Most of the parameters are optional.  For more details on a specific parameter such as usage, acceptable values, dependencies, etc., simply click on the parameter name in the table below.

Any of these values can be pre-defined in your cats.ini file(s) so you don't have to constantly send every parameter argument on every call.  Subdirectories can also contain cats.ini that either augment to or overwrite or unset higher level defined settings if needed. You can define most used pairs in the root dir cats.ini file but can override these in lower directories by simply specifying them in the subdir cats.ini file(s).

Example: \foo\bar\cats.ini pairs supersede or append to \foo\cats.ini pairs

		Parameter Req Description               align defines horizontal record template placement in a results table cell   body path/filename or fully qualified URL of the body template   border defines the border thickness value for the results table   cellpadding defines the cell padding of the results table   cellspacing defines the cell spacing of the results table   cols defines the number of columns per row to display   debug toggles debug mode; additional output for troubleshooting   dir directory to retrieve file listing from   hr toggles inserts of horizontal rules between result table rows   in fieldname(s, separated by commas) to limit query defined  by search parameter   limit used to define subsets of data to be displayed   nav path/filename or fully qualified URL of the sub navigation template   order ORDER clause (SQL) - part 1   page path/filename or fully qualified URL of the page template   plugin plugin (without '.php' extension), set to 'null' if doing static page creation   plugins pathname or fully qualified URL of plugin(s) location   raw outputs a record template of the raw final recordset in tabled form   record path/filename or fully qualified URL of the record template [*]   rowcolor1 defines results table odd-numbered rows bg color (HTML HEX)   rowcolor2 defines results table even-numbered rows bg color (HTML HEX)   rows defines the factor used to calculate "records per page" values   search full table search; used with in to define column specific searches   sort ORDER clause (SQL) - part 2 (ORDER must be defined to trigger sorting)   table path/filename or fully qualified URL of the table template   templates pathname or fully qualified URL of the template files location   valign defines vertical record template placement in a results table cell   where for use as top level filter for later end user searches   width defines results table width; percentage (%) or fixed pixel

Parameter Details

align

Description

This parameter is used to control horizontal record template placement inside a results table cell. [Optional]

Acceptable values

right, left, center, justify

Example(s)

• align=center
• align=right

Default value

center

Notes

If you plan to align your records templates the same way for the majority of your site, it is recommended that you define this key/value pair in the [defaults] section of your root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
align=center

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

body

Description

The body parameter is used to load the HTML file that will contain descriptive information pertaining to the table that will be nested into it.  This file can be located either locally or remotely on another web server.  The table details are replaced in the template via tokens. [Required]

Acceptable values

Calls to existing pages, local or remotely stored

Example(s)

• body=mybody.shtml
• body=/mybody.shtml
• body=./mybody.shtml
• body=http://www.mysite.com/mybody.shtml

Default value

null

Notes

The way that you define the parameter value is important to note.

• body=mybody.shtml
  Uses the website defined templates to retrieve the page ( / )
   
• body=/mybody.shtml
  Uses the server DOCUMENT_ROOT as the base dir to retrieve the page ( / )
   
• body=./mybody.shtml
  Uses the dir defined location to retrieve the page ( ./ )
   
• body=http://www.mysite.com/mybody.shtml
  Uses the URL specified to retrieve the page (can be a page on your own server or from another server).

If you have one body template that you plan on using most of the time, you'll want to define it in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string whenever you want to use the main table template.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
body=mybody.shtml

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

border

Description

This parameter controls the border thickness of the results table.  [Optional]

Acceptable values

Any numeric value from 0

Example(s)

• border=0
• border=4

Default value

0

Notes

Setting this parameter to 0 (zero) turns the border off.

If you plan to use (or not use) borders on results tables for the majority of your site, it is recommended that you define this key/value pair in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
border=2

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

cellpadding

Description

This parameter is used to control the amount of cell padding that is applied to the results table. [Optional]

Acceptable values

Any numeric value from 0

Example(s)

• cellpadding=0
• cellpadding=10

Default value

4

Notes

If you plan to use the same amount of cell padding in your results tables for the majority of your site, it is recommended that you define this key/value pair in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
cellpadding=5

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

cellspacing

Description

This parameter is used to control the amount of cell spacing that is applied to the results table. [Optional]

Acceptable values

Any numeric value from 0

Example(s)

• cellspacing=0
• cellspacing=20

Default value

4

Notes

If you plan to use the same amount of cell spacing in your results tables for the majority of your site, it is recommended that you define this key/value pair in the [defaults] section of the root-level cats.ini.  This way, you do not have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
cellspacing=2

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

cols

Description

This parameter defines the number of result table columns per row.  Each cell width will be evenly distributed across the screen. [Optional]

Acceptable values

Any numeric value from 1

Example(s)

• cols=1
• cols=4
• cols=8

Default value

1

Notes

If you plan to use the same number of columns for the majority of your site, it is recommended that you define this key/value pair in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
cols=3

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

debug

Description

Toggles debug mode; if set to 'y', produces additional text to aid in troubleshooting issues. meant for diagnostic purposes track down issues if they arise. [Optional]

Acceptable values

y, Y

Example(s)

• debug=y

Default value

null

Notes

For an example of the debug output you get , click here.  You can also add "&debug=y" to any URL served thru the cats.php script.

Back to top

dir

Description

Sets the current operating directory. [Optional]

Acceptable values

Any call to a subdirectory in or under the current location of the cats.php script that is being executed.

Example(s)

• dir=/
• dir=/files
• dir=/2025/pictures
• dir=/code/cats/docs

Default value

null

Notes

Depending n your setup, each subfolder may contain a different subsection of your website.  As such, each subfolder can contain modified CATS.INI files that use different templates to display results in a different way depending on the dataset you are querying via your plugin. Each subfolder can contain a different homepage that discusses the areas purpose and can be called in the INI file using the "./" [dot][slash] chars like this:

?dir=/sean/code

/sean/code/cats.ini
[defaults]
body=./home.html

The above example will use [DOCUMENT_ROOT][dir]/home.html or /var/services/web/sean/code/home.html for the body portion of the page generated. Please see page, body, nav, table, record, nav, and hr for usage.

Back to top

hr

Description

This parameter controls whether or not to insert horizontal rules between rows in the results table. You may specify a template file for this value as well.[Optional]

Acceptable values

y, n or null, or any valid URL call to a hr template file

Example(s)

• hr=y
• hr=n
• hr=null
• hr=hr_blue_bar.shtml
• hr=http://www.mysite.com/templates/hr.shtml

Default value

null

Notes

To turn this option on, simply supply a value with the parameter.  There are 2 ways to use this:

1. Setting the value to 'y' will use a standard HTML horizontal rule.  No template needed.
2. Setting this value to anything other than 'y' will have the script attempt to pull the value as a web page template.

The way that you define the parameter value is important to note.

• hr=y
  Inserts HTML horizontal rule tag between rows.
   
• hr=null or hr=n
  Turns horizontal rules off
   
• hr=myhr.shtml
  Used in conjunction with the templates parameter to retrieve the file
   
• hr=/myhr.shtml
  Uses the [DOCUMENT_ROOT] to retrieve the file ( / )
   
• hr=./myhr.shtml
  Uses the script's current location to retrieve the file ( ./ )
   
• hr=http://www.mysite.com/myhr.shtml
  Uses the URL specified to retrieve the file (can be a page on your own server or from another server).

To turn horizontal rules off, set the value to null.

If you plan to use (or not use) horizontal rules for the majority of your site, it is recommended that you define this key/value pair in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
hr=y

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

in

Description

Defines the field or fields, separated by commas, to query in for the term(s) defined by search parameter. If null, search is performed across the whole data row. [Optional]

Acceptable values

Any field name contained within the data returned by the plugin used

Example(s)

• in=name
• in=base,caption

Default value

null

Notes

This function is bypassed if search is "" or null.

If any of the fieldnames passed do not exist in the data returned by the plugin, CATS silently removes the offending fieldname from the [IN] array and will throw a debug msg if 'debug=y' is used.

Back to top

limit

Description

Defines the returned record subset. If null, final [DATA] will contain every record meeting search conditions (if defined) or all. [Optional]

Acceptable values

Any valid starting record number and any positive range value, separated by a comma or 'null'

Example(s)

• limit=0,10
• limit=40,10000000
• limit=null

Default value

null

Notes

There are 2 values that get used with this parameter, separated by a comma. The first value indicates what record to start from while the second number controls the number of records to return.  A start value of 0 indicates to begin displaying records from the beginning of the record set.

Example: limit=0,10 indicates to start at record 1 and return the next 10 records from the record set.

Example: limit=30,15 indicates to start at record 31 and return the next 15 records (to record 45) from the record set.

If the value for records to return is greater then the actual number of records left, all the remaining records are displayed.  No error is generated for values that are too large.

Works similar to it's SQL related equivalent.

Setting this parameter to null will over-ride the limit, allowing you to display all the records in the record set.

Back to top

nav

Description

The nav parameter is used to load the HTML page that contains sub navigational links. [Optional]

Acceptable values

Calls to existing pages, local or remotely stored

Example(s)

• nav=mynav.shtml
• nav=/mynav.shtml
• nav=./mynav.shtml
• nav=http://www.mysite.com/mynav.shtml
• nav=http://www.somebodyelsessite.com/mynav.shtml

Default value

null

Notes

The way that you define the parameter value is important to note.

• nav=mynav.shtml
  Used in conjunction with the templates parameter to retrieve the page
   
• nav=/mynav.shtml
  Uses the [DOCUMENT_ROOT] to retrieve the page ( / )
   
• nav=./mynav.shtml
  Uses the dir defined location to retrieve the page ( ./ )
   
• nav=http://www.mysite.com/mynav.shtml
  Uses the URL specified to retrieve the page (can be a page on your own server or from another server).

It is recommended that you'll want to define it in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
nav=mynav.shtml

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

order

Description

This parameter is used to specify what field(s) to order against.  Multiple values must be separated with commas. [Optional]

Acceptable values

Any valid field name(s), separated with commas, 'null' for no sorting,

 Example(s)

• order=`name`
• order=`name`,`size`
• order=null

Default value

null

Notes

You can use all standard SQL clause-related arguments and functions with the parameter.

Using 'null' as a order value will cause the records to be returned in the order they are retrieved from the database (input order).

Back to top

page

Description

The page parameter is used to load the HTML page that contains what is termed as 'your site identity'. This page will contain your various colors, top/root navigational links, CSS file link and other style related tags. Most sites will only need one page template but you can define more (each subdirectory can have it's own PAGE setting).  This file can be located either locally or remotely on another web server. [Required]

Acceptable values

Calls to existing pages, local or remotely stored

Example(s)

• page=mypage.shtml
• page=/mypage.shtml
• page=./mypage.shtml
• page=http://www.mysite.com/mypage.shtml
• page=http://www.somebodyelsessite.com/siteident-4.htm

Default value

null

Notes

The way that you define the parameter value is important to note.

• page=mypage.shtml
  Used in conjunction with the templates parameter to retrieve the page
   
• page=/mypage.shtml
  Uses the [DOCUMENT_ROOT] to retrieve the page ( / )
   
• page=./mypage.shtml
  Uses the dir defined location to retrieve the page ( ./ )
   
• page=http://www.mysite.com/mypage.shtml
  Uses the URL specified to retrieve the page (can be a page on your own server or from another server).

Since most users will only have 1 site identity, it is recommended that you'll want to define it in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
page=mypage.shtml

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

plugin

Description

The plugin parameter is used to define which plug-in to use for data mining. If no pathname info is specified with the plugin call, the plugins location is used. If set to 'null', assumes page creation is not dynamic and bypasses all data array collection and sorting.

Acceptable values

Any filename that corresponds to a existing plug-in file.

Example(s)

• plugin=directory
• plugin=files
• plugin=text

Default value

null

Notes

Since most users will only have 1 plug-in location, it is recommended that you'll want to define it in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
plugin=files

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

plugins

Description

The plugins parameter is used to define the location of you plug-ins. If no pathname info is specified with the plugin call, the plugins location is used.

Acceptable values

A pathname to the location of your plug-ins. Setting this value to "null" reverts to your server's DOCUMENT_ROOT.

Example(s)

• plugins=/data/home/webs/shrum.net/html
• plugins=/home/web/foobar.com/plugins
• plugins=null

Default value

null

Notes

Since most users will only have 1 plug-in location, it is recommended that you'll want to define it in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
plugins=/data/home/webs/shrum.net/code/cats/plugins

You may still override this default by passing the parameter with a different value in subfoldered cats.ini files and your query string.

Back to top

raw

Description

Returns a record template of a raw basic HTML table with all fields and rows in the final recordset.

Example(s)

• raw=y

Default value

null

Notes

T

Back to top

record

Description

The record parameter is used to load the file data that defines the primary record layout template. [Optional]*

* If no plugin value is supplied in the call, the script assumes static page creation and skips all data array functions. If however a plugin is defined, this parameter will be needed in order to table the data.

Acceptable values

Calls to existing pages, local or remotely stored

Example(s)

• record=myrecord.shtml
• record=/myrecord.shtml
• record=./myrecord.shtml
• record=http://www.mysite.com/myrecord.shtml
• record=http://www.somebodyelsessite.com/rec_weblog.htm

Default value

null

Notes

The way that you define the parameter value is important to note.

• record=myrecord.shtml
  Used in conjunction with the templates parameter to retrieve the page
   
• record=/myrecord.shtml
  Uses the [DOCUMENT_ROOT] to retrieve the page ( / )
   
• record=./myrecord.shtml
  Uses the dir defined location to retrieve the page ( ./ )
   
• record=http://www.mysite.com/myrecord.shtml
  Uses the URL specified to retrieve the page (can be a page on your own server or from another server).

Since most users will multiple record templates for various content situations, you will want to specify the most used record template in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
record=myrecord.shtml

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

rowcolor1

Description

Sets the ODD row background color for zebra striping. Defines the background row color, in HTML HEX code, for the results table *odd* numbered rows (1,3,5,...). [Optional]

Acceptable values

Any valid 6-digit HTML HEX color code or 'null'.

Example(s)

• rowcolor1=ffffff
• rowcolor1=e4d2f8
• rowcolor1=null

Default value

ffffff

Notes

If you plan to use the same alternating row colors for all your result tables on your site, it is recommended that you define this key/value pair in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
rowcolor1=eeeeee

Alternatively, if you wish to reset this value, you can call the parameter with 'null' as the value.  This will remove the rowcolor setting allowing the page background image or color to be displayed.

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

rowcolor2

Description

Sets the EVEN row background color for zebra striping. Defines the background row color, in HTML HEX code, for the results table *even* numbered rows (2,4,6,...). [Optional]

Acceptable values

Any valid 6-digit HTML HEX color code or 'null'.

Example(s)

• rowcolor2=ffffff
• rowcolor2=e4d2f8
• rowcolor2=null

Default value

eeeeee

Notes

If you plan to use the same alternating row colors for all your result tables on your site, it is recommended that you define this key/value pair in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
rowcolor2=ffffff

Alternatively, if you wish to reset this value, you can call the parameter with 'null' as the value.  This will remove the rowcolor setting allowing the page background image or color to be displayed.

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

rows

Description

Sets the pagination values for number of rows. [Optional]

Acceptable values

Any numeric value greater than 1

Example(s)

• rows=5
• rows=10
• rows=100

Default value

10

Notes

This parameter does not actually control the number of rows that are displayed but rather sets the factor used in conjunction with the cols parameter to determine navigational elements for 'records per page' pagination options.

Example: If you have the following settings:

• cols=1 and rows=10; records per page option: 10, 20, 30
• cols=2 and rows=4; records per page option: 8, 16, 24
• cols=3 and rows=6; records per page option: 18, 36, 54
• etc.

If you plan to use the same 'records per row' options for the majority of your site, it is recommended that you define this key/value pair in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
rows=5

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

search

Description

Allows for case insensitive (fuzzy) searches (OR / MUST CONTAIN / MUST NOT CONTAIN ) as well as case sensitive using a ^ operator across a whole data row (if in is not used or null) or in only specific field(s) if defined with in. [Optional]

Acceptable values

Any string of text.

Example(s)

• search=this that
• search=this -that ^CATS
• search=this +that -those "foo bar"
• search=>=10000 <20000

Default value

null

Notes

This parameter is meant more as a way to allow you to place search forms on your site to allow users to filter on a set of data passed from a plugin.

Search operators can be used to help the user narrow down the results.  They are (in order of operation):

• - (dash) => NOT (must not include)
• + (plus) => AND (must include)
• no preceding operator => OR
• ^ (caret) => case sensitive match
• "" (dbl-quote wrapped) => OR
• >, <, >=, <= (must pass condition)

For example, if search is defined as:

search=foo bar

...the search would look for records that contain either or both "this" or "that" anywhere in the data row being evaluated.

Another example (using operators and field specific search) is:

search=+foo -bar&in=contents,filename

...the search would look for records that must contain "foo" but not contain "bar" in the 'contents' or 'filename' columns.

Another example (using case sensitivity operators and field specific search) is:

search=^CATS&in=contents

...the search would look for records that contain "CATS" case matches only in the 'contents' column.

Back to top

sort

Description

This parameter controls the sorting of the supplied ORDER parameter. Will not trigger ASCENDING or DESCENDING sorts unless ORDER field is defined and exists in DATA. Can use "r" to do randomizing of data without a ORDER field specified [Optional]

Acceptable values

a, asc, ascending, d, desc, descending, r, rand, random, null

Example(s)

• sort=asc
• sort=descending
• sort=r
• sort=null

Default value

asc

Notes

The script only looks at the first letter of the returned SORT parameter.

Setting this parameter value to 'null' effectively resets this parameter to a unassigned state , effectively turning the [ORDER] parameter off.

Back to top

table

Description

The table parameter is used to load the file data that defines the table template. [Optional]

Acceptable values

Calls to existing pages, local or remotely stored

Example(s)

• table=myrecord.shtml
• table=/myrecord.shtml
• table=./myrecord.shtml
• table=http://www.mysite.com/myrecord.shtml
• table=http://www.somebodyelsessite.com/rec_weblog.htm

Default value

null

Notes

The table temple will typically contain information such as record set navigational elements, record count, etc. 

The way that you define the parameter value is important to note.

• table=mytable.shtml
  Used in conjunction with the templates parameter to retrieve the page
   
• table=/mytable.shtml
  Uses the [DOCUMENT_ROOT] to retrieve the page ( / )
   
• table=./mytable.shtml
  Uses the dir defined location to retrieve the page ( ./ )
   
• table=http://www.mysite.com/mytable.shtml
  Uses the URL specified to retrieve the page (can be a page on your own server or from another server).

If you have a mian table template that you plan on using most of the time, you'll want to define it in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string whenever you want to use the main table template.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
table=mytable.shtml

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

templates

Description

Sets the base location to look in if a template call is made without path information.  Defaults to the root location of the current website if not defined explicitly. [Optional]

Acceptable values

Any valid URL address that will be the primary location of your template files (see page, body, table, record, nav, and hr for more information pertaining to these items)

Example(s)

• templates=http://www.mysite.com
• templates=http://www.mysite.com/templates
• templates=http://www.mysite.com/this/is/a/really/deep/dir/templates

Default value

"http://" . $_SERVER['HTTP_HOST']

Notes

The templates parameter defines the location in which your template files are collectively located.  This information is used whenever a template call is made that does not include any path information.  This way, you don't have to retype in the same base location for all your templates in each of your script calls.

Since most users will only have one location for their templates, and therefore it is recommended that you pre-define it in the [defaults] section of the root-level cats.ini.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
templates=http://www.mysite.com/templates

You may still override this default by passing the parameter with a different value in your query string.

Back to top

valign

Description

Defines the vertical record template placement inside a results table cell. [Optional]

Acceptable values

top, middle, baseline, bottom

Example(s)

• valign=top
• valign=middle
• valign=bottom

Default value

middle

Notes

If you plan to align your records templates the same way for the majority of your site, it is recommended that you define this key/value pair in the [defaults] section of the root-level cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
valign=middle

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

where

Description

Mainly for webmasters to pre-define a user searchable record set. Entries are in [fieldname]=[term] format. Multiple entries are separated with commas. Server side protected. [Optional]

Acceptable values

Any valid SQL-based WHERE statement including conditional statements or 'null'

Example(s)

• where=ext=caption
• where=this=foo,that=bar
• where=null

Default value

null

Notes

If WHERE is defined server-side, in a cats.ini file, or set as a default value in the script, any URI/query string attempts to modify this parameter are ignored.

Back to top

width

Description

Defines results table width. [Optional]

Acceptable values

Can be set as a percentage (75%) or a fixed pixel width by omitting the percent sign (600).

Example(s)

• width=100%
• width=75%
• width=700

Default value

100%

Notes

If you plan to size your results tables the same way for the majority of your site, it is recommended that you define this key/value pair in the [defaults] section of the cats.ini.  This way, you don't have to pass this parameter in the query string.  You can define the default parameter in the INI file like so:

cats.ini
[defaults]
width=100%

You may still override this default by passing the parameter with a different value in your query strings.

Back to top

Reserved Value: NULL

Having a reserved *value* may seem strange but once you know, you'll understand why. 

Setting any parameter to "null" will  unset the parameter as undefined.  This will make the script act as if that parameter never had a value (this allowing the script to skip over function blocks if that particular parameter triggered any). One example (or reason, depending on how you look at it) for doing this is in the case of row colors.  If rowcolor is predefined in the cats.ini but don't want to use rowcolors (opting for transparent backgrounds instead), you can set "rowcolor1=null&rowcolor2=null' in the query string or the area specific cats.ini file. This way, the script knows to not define background colors for rows in the results table.  Another example is when you want to unset a predefined argument. These are just a few examples but I'm sure more exist.

Unreserved Parameters (non-cat.php arguments/tokens)

You can define any number of unreserved parameter pairs (key=value) and pass them to the script for template token replacement.  This is great when using a generic template and using key/value pairs to insert custom text into them.

How it works

When you pass a unreserved parameter on the query string, it and it's value are passed and stored by the script for later use.  Once a page has been composited, the script searches the body of the document for the parameter name wrapped in dollar signs like this: $iamatoken$.  If you were to pass the following query, the script will do a search-&-replace operation for all occurrences of '$token$' and replace it with 'foo bar'.

http://www.mysite.com/cats.php?token=foo bar

Some browsers (COU-Netscape-GH!) don't like <SPACE> characters in the URL and will actually reject the query as a improperly formatted request.  To compensate for these sorts of situations, use '%20' in place of  <SPACE> like this:

http://www.mysite.com/cats.php?token=foo%20bar

The next document you should aquaint yourself with is Template Tokens. It discusses how to use not only script based tokens but also $_SERVER, $ENV, recordset and pagination, and plugin returned tokens.

A really good collections of generic templates (that I use all the time) and the tokens that they use can be found in the templates area.  Of specific import in this regard is the table_generic-icon_title.shtml file.  Note how `icon` and `title` tokens are present.  These are tokens that require parameters be passed on the query string with the same name in order to replace the values in the template.

Note that the icon and the title on the above HTML document are both tokens.  Unless these values are provided with the call (or defined in the [defaults] section of the cats.ini), they will remain unchanged.