| |  | | | | |
shrum.net :: Code :: CATS :: Script Parameters - A to ZScript 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.
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 DetailsDescriptionThis parameter is used to control horizontal record template placement inside a results table cell. [Optional]
Acceptable valuesright, left, center, justify
Example(s)Default valuecenter
NotesIf 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
DescriptionThe 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 valuesCalls to existing pages, local or remotely stored
Example(s)Default value
null
NotesThe 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
DescriptionThis parameter controls the border thickness of the results table. [Optional]
Acceptable valuesAny numeric value from 0
Example(s)Default value0
NotesSetting 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
DescriptionThis parameter is used to control the amount of cell padding that is applied to the results table. [Optional]
Acceptable valuesAny numeric value from 0
Example(s)- cellpadding=0
- cellpadding=10
Default value4
NotesIf 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
DescriptionThis parameter is used to control the amount of cell spacing that is applied to the results table. [Optional]
Acceptable valuesAny numeric value from 0
Example(s)- cellspacing=0
- cellspacing=20
Default value4
NotesIf 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
DescriptionThis parameter defines the number of result table columns per row. Each cell width will be evenly distributed across the screen. [Optional]
Acceptable valuesAny numeric value from 1
Example(s)Default value1
NotesIf 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
DescriptionToggles 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 valuesy, Y
Example(s)Default value
null
NotesFor 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
Description
Sets the current operating directory. [Optional]
Acceptable valuesAny 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
DescriptionThis 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
NotesTo turn this option on, simply
supply a value with the parameter. There are 2 ways to use this:
- Setting the value to 'y' will use a standard HTML horizontal rule.
No template needed.
- 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
DescriptionDefines 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 valuesAny
field name contained within the data returned by the
plugin used
Example(s)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
DescriptionDefines the returned record subset.
If
null, final [DATA] will contain every record meeting search
conditions (if defined) or all. [Optional]
Acceptable valuesAny 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
NotesThere 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
DescriptionThe nav parameter is used to load the HTML page that contains
sub navigational links. [Optional]
Acceptable valuesCalls to existing pages, local or remotely stored
Example(s)Default value
null
NotesThe 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
DescriptionThis parameter is used to specify what field(s) to order against. Multiple values must be
separated with commas. [Optional]
Acceptable valuesAny valid field name(s), separated with commas, 'null'
for no sorting,
Example(s)- order=`name`
- order=`name`,`size`
- order=null
Default value
null
NotesYou 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
DescriptionThe 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 valuesCalls to existing pages, local or remotely stored
Example(s)Default value
null
NotesThe 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
DescriptionThe
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 valuesAny
filename that corresponds to a existing plug-in file.
Example(s)-
plugin=directory
- plugin=files
- plugin=text
Default value
null
NotesSince 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
DescriptionThe
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 valuesA
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
NotesSince 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
Description
Returns a record template of a raw basic HTML table with all fields and rows
in the final recordset.
Example(s)Default value
null
NotesT
Back to top
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)
Default value
null
NotesThe 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
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 valuesAny valid 6-digit HTML HEX color code or 'null'.
Example(s)- rowcolor1=ffffff
- rowcolor1=e4d2f8
- rowcolor1=null
Default valueffffff
NotesIf 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
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 valuesAny valid 6-digit HTML HEX color code or 'null'.
Example(s)- rowcolor2=ffffff
- rowcolor2=e4d2f8
- rowcolor2=null
Default valueeeeeee
NotesIf 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
DescriptionSets the pagination values for number of rows. [Optional]
Acceptable valuesAny numeric value greater than 1
Example(s)Default value10
NotesThis 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
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 valuenull
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
DescriptionThis 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 valueasc
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
Description
The table parameter is used to load the file data that defines the table
template. [Optional]
Acceptable valuesCalls 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
NotesThe 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
DescriptionSets 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 valuesAny 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']
NotesThe 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
DescriptionDefines the vertical record template placement inside a results table cell. [Optional]
Acceptable valuestop, middle, baseline, bottom
Example(s)- valign=top
- valign=middle
- valign=bottom
Default valuemiddle
NotesIf 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
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 valuesAny 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
NotesIf 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
DescriptionDefines results table width. [Optional]
Acceptable valuesCan 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 value100%
NotesIf 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:
NULLHaving 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 worksWhen 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. | | | | |
| | |
