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

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

{vb:phrase phrase_name[, arguments for phrase...]}
Inserts the specified phrase. If arguments are provided, they will be run through htmlspecialchars.
{vb:rawphrase phrase_name[, arguments for phrase...]}
As above, though arguments bypass htmlspecialchars.
{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}}
{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.
{vb:time timestamp[, format]}
As above, though uses the default time format instead of date format.
{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.
{vb:raw variable}
Outputs the variable raw, without any formatting or escaping.
{vb:escapejs variable}
Returns the variable prepared for use as a Javascript single-quoted string instead of running htmlspecialchars.
{vb:urlencode variable}
Escapes the variable using urlencode.
{vb:if condition, true[, false]}
Use this in instances where the full <vb:if> tag can not be used, such as within HTML tags.
{vb:link type, info[, extra-info]}
Used to build a hyperlink URL of the specified type and into the correct 'friendly' format.
{vb:math expression}
Primarily used within CSS, this is used to evaluate the result of the mathematical expression specified.
{vb:stylevar name[.sub-part]}
Used to output a style variable from the style system. No escaping is performed.


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

The following tags are available:

<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.
<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.
<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.
<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.
<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.
<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>

<!-- 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>