Tutorial: Template syntax¶
Introduction¶
Starting with version 3.1, phpBB is using the Twig template engine. This tutorial will cover some of the details on the implementation of Twig’s syntax in phpBB and its extensions, however more extensive documentation for Twig can be found here: Twig Documentation.
Assigning data in PHP¶
Variables¶
Assign a single variable:
$template->assign_var('FOO', $foo);
Assigning multiple variables:
$template->assign_vars([
'FOO' => $foo,
'BAR' => $bar,
'BAZ' => $baz
]);
Default Template Variables¶
There are some variables set in phpBB’s page_header function that are common to all templates and which may be useful to a style or extension author.
Template variable |
Description |
Sample output |
---|---|---|
|
The path to assets files ( |
|
|
The path to the currently selected style’s theme folder (where all the css files are stored) |
|
|
The path to the currently selected style’s template folder |
|
|
The path to phpBB’s image folder |
|
|
The path to the smiley folder |
|
|
The path to the avatar upload folder |
|
|
The path to the avatar gallery folder |
|
|
The path to topic icons folder |
|
|
The path to the rank images |
|
|
The path to phpBB’s upload folder (shouldn’t be used directly). |
|
Blocks¶
Blocks are used to assign any number of items of the same type, e.g. topics or posts (“foreach loop”).
while ($row = $db->sql_fetchrow($result))
{
$template->assign_block_vars('loopname', [
'FOO' => $row['foo'],
'BAR' => $row['bar']
]);
}
Nested loops:
while ($topic = $db->sql_fetchrow($result))
{
$template->assign_block_vars('topic', [
'TOPIC_ID' => $topic['topic_id']
]);
while ($post = $db->sql_fetchrow($result))
{
$template->assign_block_vars('topic.post', [
'POST_ID' => $post['post_id']
]);
}
}
The blocks and nested loops can then be used accordingly in HTML files (see Syntax elements).
Syntax elements¶
This section will highlight Twig syntax elements in the template engine. The older phpBB specific syntax will be deprecated in a later version of phpBB. It is therefore recommended to use the documented Twig syntax instead:
Variables¶
Variables in phpBB take the form of {{ X_YYYYY }}
, where the data is assigned from the source. However, most
language strings are not assigned from the source. When a language variable is found, denoted as {{ lang('YYYYYY') }}
,
phpBB first checks if an assigned variable with that name exists. If it does, it uses that. If not, it checks if an
existing string defined in the language file exists.
By using the language variable format, phpBB allows for more flexibility in the customization of language strings. This allows for easy modifications of language strings in the language files without having to modify the source code directly.
Blocks¶
The basic block level loop takes the form:
{% for item in loops.loopname %}
markup, {{ item.xyyyy }}, etc.
{% endfor %}
A further extension to begin is to use else
in a loop:
{% for item in loops.loopname %}
markup, {{ item.xyyyy }}, etc.
{% else %}
alternate markup
{% endfor %}
This will cause the markup between else
and endfor
to be output if the loop contains no values.
This is useful for forums with no topics (for example) … in some ways it replaces “bits of” the existing
“switch” type control (the rest being replaced by conditionals, see below).
You can also check if your loop has any content similar to using count()
in PHP:
{% if loops.loopname|length %}
{% for item in loops.loopname %}
{{ item.xyyyy }}
{% endfor %}
{% endif %}
loops.loopname|length
will output the size of the block array. This makes sense if you want to prevent, for example,
an empty <select>
tag, which would not be HTML valid.
You can also access specific iterations of a loop using the following special variables:
|
The current iteration of the loop. (1 indexed) |
|
The current iteration of the loop. (0 indexed) |
|
The number of iterations from the end of the loop (1 indexed) |
|
The number of iterations from the end of the loop (0 indexed) |
|
True if first iteration |
|
True if last iteration |
|
The number of items in the sequence |
|
The parent context |
Including files¶
phpBB has the ability to include other HTML, Javascript and CSS files:
{% INCLUDE 'filename.html' %}
{% INCLUDEJS 'filename.js' %}
{% INCLUDECSS 'filename.css' %}
Note
You can introduce new templates (i.e. other than those in the default set) using this system and include them as you wish … perhaps useful for a common “menu” bar or similar.
Conditionals/Control structures¶
Conditionals and control structures can be used similar to Twig. A simple example of this is:
{% if expr %}
markup
{% endif %}
The expression can take many forms:
{% if loop.index is even %}
markup
{% endif %}
This will output the markup if the current iteration of a loop is an even value. You can use various comparison methods (standard as well as equivalent textual versions noted in square brackets) including:
==
[eq
]!=
[neq
,ne
]<>
(same as!=
)!==
(not equivalent in value and type)===
(equivalent in value and type)>
[gt
]<
[lt
]>=
[gte
]<=
[lte
]&&
[and
]||
[or
]%
[mod
]!
[not
]+
-
*
/
<<
(bitwise shift left)>>
(bitwise shift right)|
(bitwise or)^
(bitwise xor)&
(bitwise and)~
(bitwise not)is
(can be used to join comparison operations)
Basic parenthesis can also be used to enforce good old BODMAS rules. Additionally some basic comparison types are defined:
even
odd
div
Beyond the simple use of IF you can also do a sequence of comparisons using the following:
{% if expr1 %}
markup
{% elseif expr2 %}
markup
.
.
.
{% elseif exprN %}
markup
{% else %}
markup
{% endif %}
Each statement will be tested in turn and the relevant output generated when a match (if a match) is found.
It is not necessary to always use elseif
, else
can be used alone to match “everything else”.
This can also be used to for example assign different stylesheets on even row count than on uneven ones:
<table>
{% if loop.index is even %}
<tr class="row1">
{% else %}
<tr class="row2">
{% endif %}
<td>HELLO!</td>
</tr>
</table>
Other elements can also be added:
<table>
{% if loop.index > 10 %}
<tr bgcolor="#FF0000">
{% elseif loop.index > 5 %}
<tr bgcolor="#00FF00">
{% elseif loop.index > 2 %}
<tr bgcolor="#0000FF">
{% else %}
<tr bgcolor="#FF00FF">
{% endif %}
<td>hello!</td>
</tr>
</table>
This will output the row cell in purple for the first two rows, blue for rows 2 to 5, green for rows 5 to 10 and red for remainder. So, you could produce a “nice” gradient effect, for example.
You could use if
to do common checks on for example the login state of a user:
{% if S_USER_LOGGED_IN %}
markup
{% endif %}
User variables¶
You can also define simple (boolean, integer or double) variables from inside the template. This is for example useful
if you dont want to copy & paste complex if
expressions over and over again:
{% if expr1 %}
{% DEFINE $COLSPAN = 3 %}
{% elseif expr2 %}
{% DEFINE $COLSPAN = 4 %}
{% else %}
{% DEFINE $COLSPAN = 1 %}
{% endif %}
<tr><td colspan="{{ $COLSPAN }}">...</td></tr>
<tr><td colspan="{{ $COLSPAN }}">...</td></tr>
The DEFINE
keyword does have some restrictions on its use:
There MUST be exactly one space before and after the
=
You MUST use single quotes
An example of this:
{% DEFINE $COLSPAN = 3 %} //GOOD
{% DEFINE $COLSPAN=3 %} //BAD
{% DEFINE $COLSPAN = 3 %} //BAD
{% DEFINE $CLASS = 'class1' %} //GOOD
{% DEFINE $CLASS = "class1" %} //BAD
User variables can be cleared (unset) using:
{% UNDEFINE $COLSPAN %}