Jul 16th, 2018
03:23 AM PST
 
diana       sean                         martha  
email   blog code files links photos email

email

 
 
  
shrum.net /sean/code/cats

 

  
 
 
documentation files templates support
 
filter
 
 
shrum.net :: Code :: CATS :: Script Parameters - A to Z

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

 

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

 captionextension of the caption file; for use with dir calls

 cellpaddingdefines the cell padding of the results table

 cellspacingdefines the cell spacing of the results table

 colsdefines the number of columns per row to display

 debugtoggles debug mode; additional output for troubleshooting

 dirdirectory to retrieve file listing from

 fromFROM clause (SQL)

 groupGROUP clause (SQL)

 hrtoggles inserts of horizontal rules between result table rows

  in fieldnames to query terms defined by the search parameter

 limitLIMIT clause (SQL)

  nav

path/filename or fully qualified URL of the navigation template

 orderORDER clause (SQL) - part 1

 page

path/filename or fully qualified URL of the page template

  plugin

plugin (without '.php' extension) to use

  plugins

pathname or fully qualified URL of plugin(s) location

  raw toggles display of pre / post process array dumps (for debugging)

 record1

path/filename or fully qualified URL of the first record template

 record2path/filename or fully qualified URL of the second record template

 record3path/filename or fully qualified URL of the third record template

 record4path/filename or fully qualified URL of the fourth record template

  traverse utilized by some plug-ins to toggle subfolder traversing; 'y' or  'n'/'null'

 rowcolor1defines results table odd-numbered rows bg color (HTML HEX)

 rowcolor2defines results table even-numbered rows bg color (HTML HEX)

 rows

defines the factor used to calculate "records per page" values

  search

keyword search parameter to supplement the WHERE clause

 select

SELECT clause (SQL)

 sort

ORDER clause (SQL) - part 2

 sql

complete SQL statement

 table

path/filename or fully qualified URL of the table template

 templates

pathname or fully qualified URL of the template files location

 time

time offset for date/time tokens

 valign

defines vertical record template placement in a results table cell

 where

WHERE clause (SQL)

 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)

Default value

null

Notes

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

  • body=mybody.shtml
    Used in conjunction with the templates parameter to retrieve the page
     
  • body=/mybody.shtml
    Uses the website root to retrieve the page ( / )
     
  • body=./mybody.shtml
    Uses the script's current 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


caption

Description

The caption parameter is used to load the contents of a text-based files into the `caption` field of a dir table. [Optional]

Acceptable values

Any listing of extensions to look for, separated by comma

Example(s)

  • caption=txt,inf,caption
  • caption=caption

Default value

txt,inf,caption

Notes

Let's say you specify 'caption' as the caption extension. When the script reads the files in the specified directory, it looks for files that have the same beginning filename:

...
my_8th_grade_photo.gif
my_8th_grade_photo.gif.caption
my_essay.txt
my_essay.txt.caption
...

If the match is found with the caption extension appended, the script will:

  1. opens the caption file,
  2. read the file contents, and
  3. store the contents into the `caption` field of the file record.

If no caption file is found or if a caption extension is not specified, the base name of the file is stored in the `caption` field.

If you plan to use the same caption extension for 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]
caption=caption

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. [Optional]

Acceptable values

y, Y

Example(s)

  • debug=y

Default value

null

Notes

None at this time.

Back to top


dir

Description

Retrieves file details from the supplied subdirectory and loads the results into a database table for querying against. [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=./
  • dir=./foo/bar

Default value

null

Notes

Once a DIR parameter call is made, the script queries and collects the file listing and other associated information from the hard drive and then creates a table called 'dir_' plus the name of the folder specified.  Since '/' characters are not valid in table names, all the '/' (forward-slashes) are converted to '_' (underscores) so a call like: dir=./code/php would create the table: dir_code_php.

Typically, this parameter should only be used when you want to create the table or update the contents as this command tends to bring a server to it's knees for a couple of seconds while it is reading the directory specified.

Once the table is created, if the folder does not get a lot of updates (new files, modifications, deletions), it is recommended that you use the FOR parameter, doing queries against the previously collected data versus doing redundant DIR operations.  If however, your folder will be getting a number of updates, it would be wise to continue using the DIR parameter as this method makes the whole process maintenance free.

The table structure for all DIR based calls is as follows:

dir
This field holds the directory name (seems redundant and it is but it's useful when using templates)
table
If the type is 'dir', stores the folder name with '/' replaced with '_'
name
Full name of the file
base
Base name only of the file (truncates off everything at and after the last '.' in the name)
ext
The extension of the filename (minus the '.')
type
Returns the file type: 'file', 'dir', or 'link' (on *nix systems)
size
Returns the file size (in bytes)
modified
Returns the modified date information in 'yyyy-mm-dd' format
caption
If a caption file is found, the contents of the caption file are stored here.  If no caption file is found or if no caption parameter is defined, the base value of the filename is stored here.

Back to top


from

Description

This parameter is used to specify what table in the database you want to access. [Optional]

Acceptable values

Any pre-existing table name that resides in the database or 'null'

Example(s)

  • from=my_experiment_results
  • from=personnel_wages
  • from =null

Default value

null

Notes

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

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

Back to top


group

Description

This parameter controls how the data in the recordset is grouped (by). [Optional]

Acceptable values

Any field name(s) that exist in the table defined in the from parameter; multiple entries must be separated by commas or 'null'

Example(s)

  • group=name
  • group=type,name
  • group=null

Default value

null

Notes

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

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

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 website 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 fields to query in for the terms defined by the search parameter [Optional]

Acceptable values

Any field name contained within the active database

Example(s)

  • in=name
  • in=base,caption

Default value

null

Notes

Used in conjunction with the search parameter.

Back to top


limit

Description

Defines the returned record subset. [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.  Example: limit=10,10 indicates to start at record 10 and return the next 10 records from the record set.  A start value of 0 indicates to begin displaying records from the beginning of 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.

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

Setting this parameter to null will allow you to 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 recordset navigational elements, also known as pagination controls. [Required]

Acceptable values

Calls to existing pages, local or remotely stored

Example(s)

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 website root to retrieve the page ( / )
     
  • nav=./mynav.shtml
    Uses the script's current 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 or 'null'

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'.  Most sites will only need one page template.  This file can be located either locally or remotely on another web server.  This page will contain your various colors, main navigational links, CSS file link and other style related tags. [Required]

Acceptable values

Calls to existing pages, local or remotely stored

Example(s)

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 website root to retrieve the page ( / )
     
  • page=./mypage.shtml
    Uses the script's current 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.[Required]

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. [Required]

Acceptable values

A pathname to the location of your plug-ins.

Example(s)

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

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/html

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

Back to top


record1

Description

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

Acceptable values

Calls to existing pages, local or remotely stored

Example(s)

Default value

null

Notes

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

  • record1=myrecord.shtml
    Used in conjunction with the templates parameter to retrieve the page
     
  • record1=/myrecord.shtml
    Uses the website root to retrieve the page ( / )
     
  • record1=./myrecord.shtml
    Uses the script's current location to retrieve the page ( ./ )
     
  • record1=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]
record1=myrecord.shtml

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

Back to top


record2, record3, record4

Description

The record2, record3, and record4 parameters are used to load the file data that defines the second, third and fourth record templates.  If values omitted, will fallback to lower valued record parameter value or will use the template defined in the record parameter. [Optional]

Acceptable values

Calls to existing pages, local or remotely stored or 'null'

Example(s)

Default value

null

Notes

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

  • record2=myrecord2.shtml
    Used in conjunction with the templates parameter to retrieve the page
     
  • record2=/myrecord2shtml
    Uses the website root to retrieve the page ( / )
     
  • record2=./myrecord2.shtml
    Uses the script's current location to retrieve the page ( ./ )
     
  • record4=http://www.mysite.com/rec_row4.htm
    Uses the URL specified to retrieve the page (can be a page on your own server or from another server).

Typically, record definitions are area specific and therefore is recommended that you define these values in the [defaults] section of the sub-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]
record2=myrecord2.shtml
record3=myrecord3.shtml
record4=myrecord2.shtml

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

When used in a multi-column layout (cols >= 2), you can define additional record templates to be used.  If this parameter is omitted, the template defined in the record parameter is used in multi-columned layouts.  If this parameter is supplied, the logic is thus:

  • 1 col : record
  • 2 cols: record|record2 or record|record
  • 3 cols: record|record2|record3 or record|record2|record or record|record|record
  • 4 cols: record|record2|record3|record4 or record|record2|record|record2 or record|record|record|record

Since RECORD is required, we can always use the template defined for RECORD for all the columns if no additional record templates have been defined.

This template will alternate with the record template to fill in the various columns in your results table.

Back to top


rowcolor1

Description

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

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 keyword fuzzy searches (LIKE / NOT LIKE). [Optional]

Acceptable values

Any string of text.

Example(s)

  • search=this that
  • search=this -that
  • search=this |that -those

Default value

null

Notes

Used in conjunction with the in parameter

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 that you have already provided them with (via the where parameter)

Search operators can be used to help the user narrow down the results.  They are:

  • + (plus) = AND
  •  - (dash) = NOT
  •  ! (exclamation point) = NOT
  •  |  (pipe) = OR

For example, if search is defined as "search=this that +whose -those", the search would look for: records that contain "this" or "that" and "whose" but not "those".

If  an operator does not precede a search term(s), OR condition is used.

Back to top


select

Description

This parameter defines the SQL SELECT clause for what fields to return in the recordset.. [Optional]

Acceptable values

Any valid SQL SELECT statement, including functions and stored procedures

Example(s)

  • select=*
  • select=`name`,`salary`,hire_date`
  • select=`name` as 'this_name', `size` as 'that_size'
  • select=COUNT(*) as `total_records`
  • select=`name`,format(`size`/1000,0) as `size_kb`,`modified`,`type`

Default value

*

Notes

It is best to predefine your most commonly used select statement, which in most cases will be to return ALL the fields.  Since the default for this parameter is already "*", it is not necessary to pre-define this in your cats.ini files.  If however, you are applying functions to your SELECT statement, you will want to store that value in 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]
select=*

For more information on the SELECT clause, along with functions that are supported by the version of MySQL that you have, see http://www.mysql.com/doc/en/SELECT.html

Back to top


sort

Description

This parameter controls the sort order of the ORDER parameter. [Optional]

Acceptable values

asc, desc, null

Example(s)

  • sort=asc
  • sort=desc
  • sort=null

Default value

asc

Notes

This parameter is only used if the order parameter is defined.

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

Back to top


sql

Description

A fully-defined SQL statement that takes precedence over the composited SQL statement. [Optional]

Acceptable values

Any valid SQL statement

Example(s)

Default value

null

Notes

The sql parameter allows you to specify a complete, SQL statement that replaces the piecemealed SQL statement that gets placed together via the select, from, where, order, sort, group, and limit parameters.  Use of this parameter should be done only when needed.

Back to top


table

Description

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

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 website root to retrieve the page ( / )
     
  • table=./mytable.shtml
    Uses the script's current 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, record2, record3, record4 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


time

Description

Time offset for date/time tokens. [Optional]

Acceptable values

Any positive or negative value in relation to the number of hours to add or subtract

Example(s)

  • time=-3 hours
  • time=+4 hours

Default value

0 hours

Notes

Chances are your web host is not in the same time zone as you.  Let's say you're on the west coast (PST) but your web host is on the east coast (EST).  When cats.php replaces the time tokens, it will be listed 3 hours ahead of your current time.  As a result, the time values that the script reports will not reflect the time values that you are currently in.  Use of this parameter is to set the time value so it matches your time zone.

Changing this value *does not* have any effect on timestamps handled by MySQL.  MySQL will use the server time for all internal date and time based functions.

It is recommended that you define this key/value pair in the [defaults] section of the root-level cats.ini as this value will not change like so:

cats.ini
[defaults]
time=-3 hours

Your value will vary based on where you live in relation to where your web host places his servers.  If your web host is 2 hours behind you, use "+2 hours" as the value for the time key.  If your server time zone is already current, you can omit this parameter or set it to 'null'

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

Defines search criteria for the returned record set. [Optional]

Acceptable values

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

Example(s)

  • where=`ext`='caption'
  • where=`type`='file` AND `size`>'1000000'
  • where=null

Default value

null

Notes

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

Setting this parameter to null will allow you to over-ride any preset where statement, allowing the record set to return all the records in the table.

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 to it's undefined format.  This will make the script act as if that parameter never had a value.  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.  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 WHERE argument.  These are just a few examples but I'm sure more exist.


Unreserved Parameters

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

A really good collections of generic templates (that I use all the time) 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.

 
 
 
documentation files templates support
 
top

bookmark

feedback print

back

 
 
Cats v.4.06 [open source] Plug-in: "text" Template size: 105 kb Script: 0.0095 secs Plug-in: 0.0016 secs Overall: 0.0111 secs