Templates Introduction

The templates are text files, with extension ".tpl" located in the directory "/templates". They contains some text, mixed with special commands, interpreted by the forum engine in order to create the HTML code of the pages, sent to the user.

By editing the template files, it is possible to change the appearance of the forum to any desirable visual skin.

The commands are enclosed in square brackets and can be nested recursively. Each command in fact returns some text value, replacing the command itself.

The template engine is always called with 2 (optional) parameters:

1. Active SQLite statement, containing one row of some SQL query and

2. Pointer to an array of engine internal variables about the currently served HTTP request.

This way, the commands are two types - commands returning information from the internal data structures of the engine and commands returning information from the SQL statement.

Commands returning request information

It is group of commands, returning information from the internal data structure.

Depending on KEYWORD, there are:

(Note: Remove space in between [ ])

[ special:version ] - Returns the version of the engine executable file. Ex: 42b4bf25137cf180

[ special:timestamp ] - Returns the time elapsed from the beginning of the current HTTP request, formatted as a decimal number with 3 digits after the decimal point. The time is measured in milliseconds with resolution in microseconds. Ex: 2.601

[ special:title ] - Returns the full current page title. Ex: ..:: AsmBB ::.. "AsmBB how to download, compile and install."

[ special:username ] - Returns the username of the user that made the request, or empty string if the user is not logged in.

[ special:userid ] - Returns the ID of the user (as in Users table of the database) that made the request, or 0 if the user is not logged in.

[ special:permissions ] - Returns the permissions of the user that made the request. If the user is not logged in - returns 0.

[ special:isadmin ] - 1 if the user is admin. 0 - if not admin or not logged in.

[ special:canregister ] - 1 if the user is permitted to register. Currently, it is always 1, but in the future versions is possible to be used to ban users by IP.

[ special:canpost ] - 1 if the user is permitted to post messages in existing threads.

[ special:canstart ] - 1 if the user is permitted to start new threads.

[ special:canedit ] - 1 if the user can edit the currently displayed post. 0 elsewhere. This flag is a little bit tricky. It will be 1 only if the user has global editing permission or if the current SQL statement, passed to the template engine has field "userid" equal to the userid of the current user and this current user has editing permissions for its own content.

[ special:candel ] - 1 if the user can delete the currently displayed post. See 0 for detailed explanation.

[ special:page ] - Returns the number of the page, as specified in the requested URL or 0 if no page is specified. It has meaning only for the thread lists and threads pages.

[ special:dir ] - Returns the current directory (in other words the current selected tag) as specified in the requested URL.

[ special:thread ] - Returns the slug of the thread as specified in the request URL. Has meaning only for threads.

[ special:referer ] - Returns the page from where the user came. i.e. the HTTP_REFERER header of the request.

[ special:alltags ] - Returns all tags, of the forum, that have at least 1 thread attached, formatted in HTML with sizes, proportional to their popularity (i.e. the number of threads tagged with every tag). This command is aimed especially to construct the tag list displayed at the top of the pages. Can be styled by CSS or/and JS if needed.

[ special:setupmode ] - Special tag, that has value of 1 only when the forum is in setup mode, i.e. the Users table is empty. In this mode, only the admin created form is displayed by the forum. Should not be used in the templates actually.

[ special:search ] - Returns the current search query of the forum search engine.

[ special:posters= ] - Returns list of the usernames of the thread starter and first several posters in the thread with ID=THREAD_ID. Can be used in the thread list summary representation of the thread. The list is formatted in HTML.

[ special:threadtags= ] - Similar to the previous command, returns a list of the tags, assigned to a thread with ID=THREAD_ID.

Commands for data processing

MARKDOWN_TEXT - This command parses the markdown formatted text MARKDOWN_TEXT and converts it into HTML. The markup is very similar to the base markdown, but has some differences.

TEXTN - case operator, depending on the value of INDEX, one of the "|" delimited texts is returned. The operator works with saturation. If the value of INDEX is bigger than the number of provided texts, the last text is returned.

[sql:SQL_STATEMENT|PARAM1|PARAM2|...|PARAMN] - Prepares SQL statement SQL_STATEMENT, binds the "?" parameters to the provided, "|" separated values and executes the query. The query must be scalar - i.e. to return only one value and this value is returned as a result of the operation. If the query ends with empty set or error, an empty string is returned. Notice: this is extremely dangerous command that can destroy the data base! Use only "select" statements and always use fixed query and parameter bindings.

Actually this command is usually used not for extracting data from the database, but simply as a calculator to compute complex expressions by using the SQLite expression parser. In this case the command looks like:

[sql: select EXPRESSION|PARAM1|PARAM2...|PARAMN]

and is safe for use, because does not access the database at all.

SQL statement data fields.

The fields of the SQL statement passed to the template are replaced by simply enclosing the field name in square brackets.

For example admin will return the value of the field "username" from the statement if such field exists.

If such field does not exists, the command is not replaced at all.

Every template file has its own different SQL query that is passed to it with its own set of accessible database fields.

The fields will be described with the description of the particular template files.