How RenderTemplate Works

RenderTemplate is AsmBB's template rendering engine that processes template files containing special markup syntax and replaces placeholders with dynamic content.

Core Concept

RenderTemplate uses a gap buffer text structure (TText) and processes templates with a syntax like [command:parameter] to dynamically insert content from:

• SQL query results (field names)

• Special variables (username, permissions, etc.)

• File includes

• Markup rendering (BBCode, MiniMag)

Function Signature

proc RenderTemplate, .pText, .hTemplate, .sqlite_statement, .pSpecial

Parameters:

• .pText - Pointer to TText structure (or 0 to create new)

• .hTemplate - Template filename handle (or 0 if already loaded)

• .sqlite_statement - SQLite statement handle for field substitution

• .pSpecial - Pointer to TSpecialParams with context data

Processing Flow

1. Initialization (lines 126-210)

• Creates/uses gap buffer text structure

• Loads template file from disk (/templates/{skin}/{filename})

• Builds hash tables for constants and SQL field names

• Sets encoding flag (HTML entity encoding enabled by default)

  2. Main Parsing Loop (lines 216-436)

• Scans template character by character

• Looks for special characters: [, ], |, escape char (`)

• Uses stack to track nested bracket levels

  3. Escape Character Handling (lines 255-268)

• |, [, ], \ - Removes escape, keeps literal character

  4. Case Operator (lines 270-425)

• Syntax: [case:value|option0|option1|option2]

• Selects one option based on numeric value

• Supports nested brackets with level tracking

Command System

Commands use syntax [command:parameter] and are dispatched via hash table lookup:

Available Commands:

SQL Field Substitution (lines 468-625)

When [fieldname] is encountered:

1. Computes Pearson hash of field name (case-insensitive)

2. Looks up in .tblFields hash table

3. Calls sqliteColumnText() to get value from SQL result

4. HTML encodes if .fEncode = 1:

   • \< → <

   • \> → >

   • " → "

   • & → &

   • | → |

Special Variables (lines 42-93)

Accessed via [special:variablename]:

Examples:

• [special:username] - Current user's name

• [special:userid] - User ID number

• [special:permissions] - Permission flags

• [special:isadmin] - Admin status (0/1)

• [special:version] - AsmBB version

• [special:timestamp] - Current timestamp

• [special:stats] - Forum statistics HTML

• [special:alltags] - All tags HTML

Key Features

1. HTML Entity Encoding

• Enabled by default for security

• Disabled by [html:] command

• Prevents XSS attacks by encoding user input

  2. Gap Buffer Efficiency

• Uses gap buffer for efficient insertions

• TextMoveGap() positions gap before modification

• TextSetGapSize() ensures space for expansion

  3. Hash-Based Dispatch

• Uses Pearson hash function (table at lines 5-21)

• Fast O(1) command and field lookup

• Case-insensitive field name matching

  4. Template Includes

• [include:filename] - Recursive rendering

• [raw:filename] - No further processing

• Paths normalized and validated for security

  5. Markup Rendering

• [bbcode:text] - BBCode to HTML conversion

• [minimag:text] - MiniMag markup conversion

• Both produce HTML (no encoding needed)

Example Template

<h1>[special:title]</h1>
<p>Welcome, [special:username]!</p>

[case:[special:permissions]|Guest|User|Moderator|Admin]

<div class="post">
  <strong>[usr:[author]]</strong>: 
  [bbcode:[content]]
  
  [attachments:[postid]]
</div>

[include:footer.tpl]

Security Considerations

• SQL field values are HTML encoded by default

• File paths are normalized (StrNormalizePath)

• Only files in template directory can be included

• User input always encoded unless explicitly marked safe

  Summary: RenderTemplate is a powerful, secure template engine that combines SQL data binding, command processing, conditional logic, file inclusion, and markup rendering with automatic HTML encoding for XSS protection.