Template Tokens

Tokens: 'what' they are, 'how' to use the predefined ones or implement your own, and 'where' in the templates you can use them. This document contains the thinking behind tokens and discusses the different types of 'wrappers' and their associated 'words'.

Introduction

CATS uses search-&-replace on words flanked by special characters located in your template files to insert content into the final, composted page.  Each token is made up of two parts: the token wrapper and the token word. 

Token Wrappers

There are a number of different token types and as such, there are different wrapper characters for each.

		Wrapper Description Example     $ $_SERVER, VAR, template, and keyword tokens ($_SERVER, $aTemplates, $aKeywords) $foo$     ! Parameter/query string, cats.ini [defaults] tokens ($aParams) !foo!     : Server date / time field tokens ($aTime) :foo:     * Script-specific tokens ($aScript) *foo*     # Recordset navigation tokens (next, previous, record count, etc) ($aRecordset) #foo#     % Record field tokens (record data) ($aData) %foo%

Token Words

Server / environment variables, cats.ini [keywords] [ code variables => $_SERVER, $aTemplates, $aKeywords ]

SERVER_VARS and ENV_VARS are PHP and HTTPD server key/value pairs that holds information about the script engine and HTTPD server. Below are a couple of the *many* keys that are common. It's recommended that you make use of PHP's predefined variables on your server to get a current listing of the key/value pairs available to you. Examples of returns are partially listed below. A complete list of these pairs can be found at PHP.NET - Predefined Variables.

These types of tokens are wrapped in dollar signs ( $ ; $foo$ ).

		Token Description Currently     $ HTTP_HOST $ returns the current host name www.shrum.net     $ REMOTE_ADDR $ returns the visiting users IP address 216.73.216.182     $ REMOTE_PORT $ returns the visiting users port number 14330     $ PHP_SELF $ returns the path and name of the executing script http://www.shrum.net/cats.php     $ SERVER_SOFTWARE $ returns the name and version of the web server software LiteSpeed     $ DOCUMENT_ROOT $ returns the DOCUMENT ROOT of the website /home/shrumnet/public_html         ...and many others supported by PHP's predefined variables

$_REQUEST array (aka URI query string) and cats.ini [defaults] tokens ( ! )  [ code variable => $aParams ]

$_REQUEST array values and cats.ini [defaults] tokens are any key/value pair that is passed on the current query string or pre-defined in the cats.ini file(s) under the [defaults] section.  This includes all the script parameters, reserved and unreserved.  These can be used in conjunction with tokens in templates to control text that is displayed in the final page. See Script Parameters - A to Z for a complete listing of parameters that can be used in this manner.

$_REQUEST and cats.ini [defaults] tokens are wrapped in exclamation marks ( ! ; !foo! ).

		Token Description Currently     ! templates ! returns the location for template files /sean/code/cats/templates     ! plugins ! returns the location for plugin files /sean/code/cats/plugins     ! page ! returns the filename of the page template page_shrum.net-v16.shtml     ! body ! returns the filename of the body template /sean/code/cats/docs/Template Tokens.shtml     ! sort ! returns the defined data sort direction a

Date/ time tokens ( : ) [ code variable => $aTime ]

Date and time tokens are set according to the machine on which the script is run (unless the time parameter is used to modify this). Mainly used for allowing you to timestamp generated pages (see top right of this page for example).

Date and time tokens are wrapped with semicolons ( : ; :foo: ).

		Token Description Currently     : sec : seconds, w/ leading 0 46     : min : minutes, w/ leading 0 34     : hour_24 : hours, in 24-hour format, no leading 0 20     : hour_0_24 : hours, in 24-hour format, w/ leading 0 20     : hour_12 : hours, in 12-hour format, no leading 0 8     : hour_0_12 : hours, in 12-hour format, w/ leading 0 08     : AM_PM : current am/pm time specifier; uppercase PM     : am_pm : current am/pm time specifier; lowercase pm     : timeofday : time of day, depending on current time evening     : timezone : current time zone of machine PST     : month : current month name February     : mon : current month name, abbreviated Feb     : mnum_0 : number of the current month, w/ leading 0 02     : mnum : number of the current month, no leading 0 2     : daysinmonth : the number of days in the current month 28     : weekday : current day name of the week Wednesday     : wkday : current day name of the week, abbreviated Wed     : mdayth : day of the month with 'st', 'nd', 'rd', or 'th', no leading 0 4th     : mdayth_0 : day of the month with 'st', 'nd', 'rd', or 'th', w/ leading 0 04th     : mday : day of the month, no leading 0 4     : mday_0 : day of the month, w/ leading 0 04     : year : current year, expressed in 4 digit format 2026     : yr : current year, expressed in 2 digit format 26     : yday : current day number in the year 35     : epochsecs : number of seconds elapsed since last epoch 1770266086     : isdst : displays "Daylight Savings Time" if active, blank if not     : last_month : last month name January     : last_mon : last month name, abbreviated Jan     : last_mnum_0 : number of the last month, w/ leading 0 01     : last_mnum : number of the last month, no leading 0 1     : last_month_year : last months year, expressed in 4 digit format 2026     : last_month_yr : current year, expressed in 2 digit format 26     : last_year : last year, expressed in 4 digit format 2025     : last_yr : last year, expressed in 2 digit format 25     : next_month : next month name March     : next_mon : next month name, abbreviated Mar     : next_mnum_0 : number of the next month, w/ leading 0 03     : next_mnum : number of the next month, no leading 0 3     : next_month_year : next month year, expressed in 4 digit format 2026     : next_month_yr : next month year, expressed in 2 digit format 26     : next_year : nextyear, expressed in 4 digit format 2027     : next_yr : next year, expressed in 2 digit format 27

Script tokens ( * )  [ code variable => $aScript ]

Script tokens are used to display information about the script itself or internal details of the script such as timing benchmarks. 

Script tokens are wrapped with asterisks ( * ; *foo* ).

		Token Description Currently                 * author * name of author Sean Shrum     * created * script creation date 2005.07.21     * distribute * script distribution URL http://cats.shrum.net     * domain * returns the top level domain name shrum.net     * email * email address of author sshrum01@gmail.com     * modified * script last modified date 2025.12.14     * name * name of the script file cats.php     * pagesize * HTML and text total page size (minus any page graphics)  in kb 111     * release * release status of script release     * relative * relative location of script (minus name) /     * status * status of script open source     * subdomain * returns the subdomain portion of the domain name www     * timer:cats * time, in seconds, of cats.php execution only 0.0048     * timer:overall * total time, in seconds, for web server, script, and plugin to return result 0.0050     * timer:plugin * time, in seconds, of plugin execution time only 0     * timer:search * time, in seconds, of [SEARCH] execution time only 0     * timer:sort * time, in seconds, of [SORT] execution time only 0     * timer:templates * time, in seconds, to retrieve requested template files only 0.0002     * version * version number of the script 4.14

Recordset and pagination tokens ( # )  [ code variable => $aRecordset ]

Recordset tokens are used to display information about the database table both before and after the SQL query is applied.  Pagination tokens are primarily used in your table template and allow visitors to your site to navigate the data that you're going to display.  You can restrict visitor navigation by omitting various pagination tokens from your templates.

Recordset and pagination tokens are wrapped with pound / hashtag ( # ; #foo# ).

		Token Description     # total # the total number of records in the table currently being queried   # match # the number of matching records (pre-LIMIT)   # return # the number of records returned from the complete SQL query   # rownum # used to display row number; mainly used in record templates   # colnum # used to display column number; mainly used in record templates   # recordnum # displays the record number; used in record templates   # start # starting record number minus 1 ( record 1 = 0 )   # first # starting record number   # end # number of records returned in the recordset   # last # last record number   # sliceoffset # number of records to display per page   # slicecount # number of data slices required to display all the data   # slicenav # hyperlinks to each slice; returns blank if slicecount = 1   # sliceall # complete URL for a single data slice; if slicecurrent = slicecount, returns current URL   # slicecurrent # current slice number   # slicefirst # complete URL for the first data slice; if slicecurrent = slicecount, returns current URL; for use as a navigational element to first page of results   # sliceprevious # complete URL for the previous data slice; if slicecurrent = 1, returns current URL; for use as a navigational element to previous page of results   # slicenext # complete URL for the next data slice; if slicecurrent = slicecount, returns current URL; for use as a navigational element to next page of results   # slicelast # complete URL for the last data slice; if slicecurrent = slicecount, returns current URL; for use as a navigational element to last page of results   # ascdesc # returns sort order: 'ascending', 'descending' 'random', 'undefined'   # sortdesc # complete URL with modified (or appended) sort parameter for descending order; for use as a navigational element to descending order display of results   # sortasc # complete URL with modified (or appended) sort parameter for ascending order; for use as a navigational element to ascending order display of results

Record tokens (%)  [ code variable => $aData ]

Record field tokens use the record field names wrapped in %.  So if a plugin returns an array with a column header of "First_Name", you will place the field name in your templates like %First_Name% wherever you want the script to input the data retrieved from that column. Refer to the plugin you are using to determine the names of the fields it will return with the array it creates as each plugin will have different column names.

Record tokens are wrapped with exclamation mark ( % ; %foo% ).

An example of a record template can be seen here: