vBulletin LTS

vBulletin 4 Template Syntax: General

by Marco van Herwaarden 23 Aug 2009

The content of this article is also available in your vBulletin distribution in ./readme-syntax.html.

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:

HTML Code:

{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:

HTML Code:

{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:

HTML Code:

{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

HTML Code:

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

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

HTML Code:

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

HTML Code:

[font=Consolas]{vb:method variable}[/font]

Built-in Methods

phrase

HTML Code:

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

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

rawphrase

HTML Code:

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

As above, though arguments bypass htmlspecialchars.

Example:

HTML Code:

{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

HTML Code:

{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

HTML Code:

{vb:time timestamp[, format]}

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

number

HTML Code:

{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

HTML Code:

{vb:raw variable}

Outputs the variable raw, without any formatting or escaping.

escapejs

HTML Code:

{vb:escapejs variable}

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

urlencode

HTML Code:

{vb:urlencode variable}

Escapes the variable using urlencode.

if

HTML Code:

{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

HTML Code:

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

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

math

HTML Code:

{vb:math expression}

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

stylevar

HTML Code:

{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

HTML Code:

<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

HTML Code:

<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

HTML Code:

<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

HTML Code:

<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

HTML Code:

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

In cases where a comment is necessary but the usual  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

HTML Code:

<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

PHP Code:


// We have an array of users available in PHP.
// It looks like this:
// $users = array(
// 1 => array('username' => 'Adam', 'email' => 'email'),
// 2 => array('username' => 'Ben', 'email' => 'email'),
// 3 => array('username' => 'Chris', 'email' => 'email')
// );
 
<!-- 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>

vblts.ru supports vBulletin®, 2022-2024