vBulletin 4 Template Syntax

vBulletin 4.0 introduces a rich new syntax for marking-up templates, reducing the need for formatting and escaping to be performed in .php files.

Note that once a template makes use of any vBulletin 4 template syntax, the old syntax will cease to operate for that template. Conversions must be an all-or-nothing affair.

• Variable Access
  • Safe Variables
  • Raw Variables
• Curly-Brace Syntax
  • Built-in Methods
    • phrase
    • rawphrase
    • date
    • time
    • number
    • raw
    • escapejs
    • urlencode
    • if
    • link
    • math
    • stylevar
• Tags
  • literal
  • if
  • elseif
  • else
  • comment
  • each
• Example use of vb:each

Variable Access

Safe Variables

Going forward, variables should be referenced in templates wherever possible using the following syntax:

{vb:var variable}

Variables accessed in this manner are 'made safe' by being run through htmlspecialchars as they are output.

To access array elements, use a dot operator, rather than standard PHP square brackets:

{vb:var variable.foo} // accesses htmlspecialchars($variable['foo'])
{vb:var variable.$varkey} // accesses htmlspecialchars($variable[$varkey])

Raw Variables

To access variables in the normal, pre-vB4 fashion, use the following syntax:

{vb:raw variable}

This is equivalent to simply accessing $variable in the pre-vB4 syntax. No treatment is applied to the variable. The same dot operator is used to access array elements.

Curly-Brace Syntax

The general syntax here is

{vb:method arg1[, arg2...]}

Inside curly braces, variables can be accessed without using a separate set of surrounding braces. For example,

{vb:method {variable}} // unneccessary extra braces
{vb:method variable}

Built-in Methods

phrase

{vb:phrase phrase_name[, arguments for phrase...]}

Inserts the specified phrase. If arguments are provided, they will be run through htmlspecialchars.

rawphrase

{vb:rawphrase phrase_name[, arguments for phrase...]}

As above, though arguments bypass htmlspecialchars.

Example:

{vb:rawphrase message_by_x_on_y_at_z, {vb:link member, {vb:raw postinfo}}, {vb:raw postinfo.username}, {vb:raw postinfo.postdate}, {vb:raw postinfo.posttime}}

date

{vb:date timestamp[, format]}

Formats a UNIX timestamp using the default date format for the active language. A format may also be explicitly specified. Timezone will be corrected for the viewing user.

time

{vb:time timestamp[, format]}

As above, though uses the default time format instead of date format.

number

{vb:number number[, decimals]}

Outputs a number having run through vb_number_format for correct locale formatting. Number of decimal places to display can be optionally specified.

raw

{vb:raw variable}

Outputs the variable raw, without any formatting or escaping.

escapejs

{vb:escapejs variable}

Returns the variable prepared for use as a Javascript single-quoted string instead of running htmlspecialchars.

urlencode

{vb:urlencode variable}

Escapes the variable using urlencode.

if

{vb:if condition, true[, false]}

Use this in instances where the full <vb:if> tag can not be used, such as within HTML tags.

link

{vb:link type, info[, extra-info]}

Used to build a hyperlink URL of the specified type and into the correct 'friendly' format.

math

{vb:math expression}

Primarily used within CSS, this is used to evaluate the result of the mathematical expression specified.

stylevar

{vb:stylevar name[.sub-part]}

Used to output a style variable from the style system. No escaping is performed.

Tags

All tags make use of the vb namespace for ease of identification and parsing.

The following tags are available:

literal

<vb:literal>misc code</vb:literal>

Any code inside vb:literal tags will be treated as plain HTML. No curly-brace syntax or vb:tag markup will be evaluated.

if

<vb:if condition="condition">true result</vb:if>

If the expression specified in condition is true, the contents of the vb:if tags will be output, otherwise nothing will be output.

elseif

<vb:elseif condition="condition" />true result

Used in conjunction with vb:if, this allows a secondary condition to be checked and the true result to be output if the condition is met.

else

<vb:else />true result

Used in conjunction with vb:if, the true result will be output if the vb:if condition failed, and so did any vb:elseif checks.

comment

<vb:comment>a comment</vb:comment>

In cases where a comment is necessary but the usual <!-- comment --> syntax is undesirable, the vb:comment tag allows its contents to be completely removed upon compiling, so they will not be delivered to the browser. Useful for internal commenting.

each

<vb:each from="array" key="key" value="value"></vb:each>

This tag will iterate through an array, in a similar manner to foreach. See the example use below.

Example Use of vb:each

// We have an array of users available in PHP.
// It looks like this:
// $users = array(
//	1 => array('username' => 'Adam', 'email' => 'adam@adam.com'),
//	2 => array('username' => 'Ben', 'email' => 'ben@ben.com'),
//	3 => array('username' => 'Chris', 'email' => 'chris@chris.com')
// );

<!-- our template code... -->
<vb:each from="users" key="userid" value="userinfo">
	<li><a href="member.php?u={vb:var userid}">{vb:var userinfo.username}</a></li>
</vb:each>

<!-- will output... -->
	<li><a href="member.php?u=1">Adam</a></li>
	<li><a href="member.php?u=2">Ben</a></li>
	<li><a href="member.php?u=3">Chris</a></li>