The Who Called script displays a list of recent callers. The display format is defined in an external template file with support for randomly-selected templates, multi-line headers, etc.
A user list template is a text file that defines the format of a listing. A template contains instructions that define the header, user rows, and footer of a listing. A template can also contain comments for your own use.
Any line beginning with a semicolon is ignored. The semicolon must be the first printable character on the line (e.g. spaces or tabs before the semicolon are allowed). This allows you to disable instructions or add copyright notices and other information to the template file. Comments are never displayed to users or administrators because they are ignored during the loading process.
; This is a comment.
HEAD Header ; This text is part of the header; it is not a comment
; This is another comment
The HEAD, ITEM and FOOT instructions define the contents of the header, each user record, and the footer, respectively. You may use the alternate names of HEADER and FOOTER instead of HEAD and FOOT (whichever is easiest for you to remember). The HEAD and FOOT names are intentionally four characters in length; this enables your margins to line up in your text editor (when using a mono-spaced font).
The first whitespace character after an instruction is ignored. For example, the following instruction defines content of the header as "Header":
HEAD Header
It does not define the header as " Header". Any characters after the space (including additional whitespace characters) are interpreted as part of the content. For example, the following instruction defines the header as " Header" because there are two spaces between the instruction and the letters. The first space is ignored.
HEAD Header
The carriage-return at the end of the line is not treated as part of the content. If you wish to display a carriage return, you must use a control code (such as @CR@ or \n) to force a carriage return. This is inconvenient but it allows you to create more complex formats. Trailing whitespace (before the carriage return) are treated as content. For example, assume the underscore (_) character below is really a space. In this example, the header would be defined as "Header ".
HEAD Header___
You are allowed to use the HEAD and FOOT instructions more than once. The BBS will concatenate all of the content lines together. This is useful when creating complex templates that have multi-line (or very long) headers or footers. You can define the content across multiple instructions instead of one massive instruction. Control code sequences and other macros should not cross over lines; they may not be interpreted properly by the BBS.
The ITEM instruction can also be used more than once. However, the BBS does not concatenate the lines together. Instead the BBS cycles through each ITEM as it renders the user list. This allows you to create interesting templates that require alternating formats for each line. If you need to define a multi-line user row, then you will need to use embedded control codes to force a newline. This is a compromise to ensure maximum flexibility.
You may use any support control code (see Translators) with the ITEM, HEAD and FOOT commands. However, it is recommended that you stick with control codes that are supported by plain text editors. PCBoard or WildCat! codes are recommended because they are easy to use (e.g. consistent length with no strange characters). ANSI-BBS codes are difficult to manage and many other codes require control characters (such as ^P, ^K, etc) that might not be handled gracefully by all text editors.
In addition to your desired control codes, you may also embed several character codes in your templates. The \n code is expanded into the newline sequence appropriate for the current user (usually a carriage return). The \r code forces a carriage return and the \f code forces a line feed (regardless of any user preferences). These control codes do not use a translator for their implementation; instead they are expanded while parsing the template. This means you will not see a "\r" or "\n" when looking at a template programmatically; they will have been expanded already.