AsmBB template engine reference
Overview
The source of the template engine is located in the file asmbb/source/render2.asm
The function of the template engine is to render the text template file containing random text, mixed with template commands into a result text. In fact, it is kind of text editor.
The procedure is defined following way:
proc RenderTemplate, .pText, .hTemplate, .sqlite_statement, .pSpecial
Arguments:
.pText- pointer to TText data structure. If[.pText] == 0, a new TText structure will be created and returned. If[.hTemplate] <> 0, the template named in[.hTemplate]is appended at the end of the[.pText]structure and then rendererd. If[.hTemplate]== 0 then is assumed that the template is already loaded in the TText structure and the structure will be processed from the beginning..hTemplate- handle or pointer to the template name. This argument must specify only the filename, not the path. The template is loaded from the pathtemplates/SKIN_NAME/TEMPLATE_NAME- where theSKIN_NAMEis determined depending on the current user preferences, the default forum setting, and the user browser (mobile or desktop browser)..sqlite_statement- this is a handler to a SQLite statement. The statement must to be prepared, executed and must contain a valid row of data. The render engine can insert data from this row into the template text. The SQL statement depends on the specific template..pSpecial- pointer to theTSpecialParamsfor the current HTTP request. Can't be 0
Return value:
The procedure returns the TText structure (possibly reallocated) in the register EAX.
Template symbols escape
There are 4 special characters used in the template commands that must to be escaped in the template text that is not command. These characters are: [, ], | and ^.
The escaped characters should be prefixed by the escape character ^ when used as a part of the text. I.e. ^[, ^], ^| and ^^.
Template database fields
The database fields from the passed SQLite statement can be inserted in the template text by simply enclosing the field name in square brackets:
For example:
The user [UserName] has been banned!
The field names are case insensitive.
The content of the field is always rendered as a text (if the field is NULL, then it is rendered as an empty string) and the content is HTML encoded.
In order to include a database field not HTML encoded (for example, it it already contains HTML code) it need to be nested in a [html:] command (read bellow):
For example:
This is my HTML formatted [html:[signature]].
But notice, that such constructions can be not safe. AsmBB does not use such HTML formatted fields.
Template commands
The general command syntax is:
[COMMAND:SOME_NESTED_TEMPLATE_TEXT]
COMMAND is the command name.
SOME_NESTED_TEMPLATE_TEXT is template text. It can contain nested template commands and field names.
The rendering of the nested commands is almost always (except the [case:] command - see below) inside out, from the most nested command/field to the least nested command.
[case:]- conditional processing.
The command [case:] has the following syntax:
[case:VALUE|CASE_TEXT0|CASE_TEXT1|...|CASE_TEXTN]
Depending on the value of VALUE it returns the text CASE_TEXT0, CASE_TEXT1 and so on up to CASE_TEXTN.
Notice that the last text CASE_TEXTN is returned for all values greater or equal to N. I.e. the command works with "saturation".
The case texts can contains nested template commands as any other command, but the processing is a little bit different.
The command [case:] has the greatest priority and is processed before any nesting template commands or SQL query fields, including the nested [case:] commands.
The value of VALUE is computed a little bit unusual.
All whitespace characters are ignored.
If it contains digits, they are interpreted as a decimal number.
Every other than digit character increments VALUE by the number of bytes in the character (UTF-8 encoding!).
In the below example, the VALUE will be computed as equal to 126: 123 (as number) + 3 (for the characters A, B and C).
[case: 1A2B3C |case = 0|case = 1|case >= 2]
... and will be rendered as case >= 2
[special:PARAM_NAME] - returns special information related to the internal engine variables and data structures.
This command inserts some information, depending on PARAM_NAME into the template. The possible PARAM_NAME values are:
The command name "special" is named after the TSpecialParams structure used for storage internal engine context during the request processing and it returns some fields from this structure, but also it can return other engine/database internal data.
visitors- returns a table with users that has been active online for the last 5 minutes.version- return the current version of the engine.sqliteversion- returns the current version of SQLitecmdtype- returns value, depending on the current command detected in the URL of the request:stats- returns an informational html block about the current forum statistics. The value is actually the rendered templatestatistics.tpl.timestamp- the time, passed after the start of the request. The time is in milliseconds with microseconds resolution. This value is used as a benchmark and should be used at the end of the page.title- returns the needed value that to be included in the HTML <title></title> element, depending on the current page rendered.header- this returns the html that have to be put in the forum header. This value is contained in the database and is set by the forum administrator from the forum settings panel.tagprefix- returns a web site specific unique prefix that to be used for creating globally unique IDs for the Atom feeds. Tag URI scheme is used.hostroot- returns the root part of the forum URLs - for example: "https://board.asm32.info" for this very site.allstyles- returns all CSS styles used until this moment in the templates (see the command[css:]bellow) Depending on the forum settings it returns the CSS in a form of set of<link>tags, or as a<style>tag.description- returns the forum description (for the<meta name="description">tag) as set from the forum administrator.keywords- returns the forum keywords (for the<meta name="keywords">tag)username- the username for the current user. Can be empty string, if the user is not logged-in.userid- the current user ID (the primary ID from the Users table in the database). Can be 0 if the user is not logged-in.skin- the currently rendered forum skin. Depends on the user preferences, administration settings and the type of the user client (mobile/desktop).lang- the ID of the currently selected language for the user interface of the forum. Depending on the user preferences and forum settings. Notice that the forum always supports utf-8 and the posts can be written in random language. This parameter concerns only the language of the forum interface.skincookie- returns the currently set session cookie namedskin. It is aimed to provide a forum skin change for the not logged-in users.page- the current page specified in the URL. For threads and thread lists.dir- the current selected tag in the URL. The name is nottagbecause of compatibility reasons with the old versions of the engine.limited- can be 0 or 1 depending on whether URL points to limited access threads or not.variant- it is a complex bit field value that depending on the URL can be:thread- the currently selected thread slug. The "slug" is a human readable URL representation of the thread title. Example: "the-asmbb-template-engine-specification.272"permissions- the permissions of the current user as a one number - bit field.isadmin- 1 if the user is administrator.canregister- 1 if the visitor can register account.canpost- 1 if the user can post in this place.canstart- 1 if the user can start new threads.canedit- 1 if the user can edit the post currently selected in the SQLite statement.candel- 1 if the user can delete the post currently selected in the SQLite statement.canchat- 1 if the user can chat in the real-time chat of the forum.canupload- 1 if the user can attach files to his posts.referer- the HTTP_REFERER for the current request. Aimed to provide back links in some dialogs.alltags- renders the tag block for the top of the forum page.allusers- returns a list of the users for use in autocomplete dialogs.setupmode- 1 if the database is empty and the forum is just created. Else 0;search- returns the current search query.order- returns the currently selected sorting order (the value of thesort=URL argument).usearch- returns the value of the URL parameteru=; Used for searching posts from specific user.skins=CURRENT_SKIN- returns a list of<option>tags with all available skins. Marks the CURRENT_SKIN as selected.posters=THREAD_ID- Returns a list of the users participated in the thread with ID = THREAD_ID.invited=THREAD_ID- Returns a list of the users invited in the thread with ID = THREAD_ID. Has meaning only for the limited access threads.threadtags=THREAD_ID- Returns a list of the tags for the thread with ID = THREAD_IDmarkup=MARKUPreturns 1 if theMARKUPnumber is available and active in the forum. Else returns 0environment- returns the whole environment rendered in a text form. For debug purposes only. In order to be available, the engine must be compiled with options.DebugWeb = 1;
0 = no command
1 = prefix command. Example /!avatar/johnfoun
2 = suffix command. Example /the-asmbb-template-engine-specification.272/15792/!edit_thread
0 = "/" root of the forum.
1 = "/(o)/" the limited access threads area.
2 = "/SOME_TAG/" some tag is selected.
3 = "/(o)/SOME_TAG/" some tag is selected in the limited access threads area.
[raw:PATH_TO_FILE] - includes file without processing.
This command includes a file as it is, without future processing.
This is useful for including files that are not templates - such as JS or already prepared files.
[include:PATH_TO_FILE] - includes template
This command includes the specified file and then renders it as a template.
[minimag:SOME_TEXT] - renders MiniMag markup.
This command translates the MiniMag formatted text SOME_TEXT into HTML.
[bbcode:SOME_TEXT] - renders BBCode markup.
This command translates BBCode formatted text SOME_TEXT into HTML.
[html:SOME_TEXT] - skips the HTML encoding of the database fields.
SOME_TEXT is already HTML formatted and must not be HTML entity encoded.
[attachments:POST_ID] - attachments list
This command returns a HTML formatted list of attached files in the post with ID = POST_ID.
[attach_edit:POST_ID] - editable attachments list
The same as [attachments:] but the list contains some editing controls for the author of the post.
[url:SOME_TEXT] - URL encode
Makes URL encoding of the included text.
[json:SOME_TEXT] - json escape
Escapes the included text in order to be included in JSON structure.
[css:FILE_NAME] - use CSS
Adds the specified file to the CSS list if it is not already there. This list is later included in the HTML by the command [special:allstyles].
[equ:NAME=VALUE] - named constant definition.
This command defines a constant with name NAME and value VALUE.
The named constant can be defined in several places. It always has the value of the latest assignment.
[const:NAME] - returns named constant value.
Returns the latest set value for the constant NAME.
See the command [equ:] from above.
[enc:SOME_TEXT] - HTML entity encoding.
Forces HTML encoding of the included text.