Templates#
Templates are responsible for the output a user sees when requesting a page (while the PHP code is responsible for providing the data that will be shown).
Templates are text files with .tpl
as the file extension.
WoltLab Suite Core compiles the template files once into a PHP file that is executed when a user requests the page.
In subsequent request, as the PHP file containing the compiled template already exists, compiling the template is not necessary anymore.
Template Types and Conventions#
WoltLab Suite Core supports two types of templates: frontend templates (or simply templates) and backend templates (ACP templates). Each type of template is only available in its respective domain, thus frontend templates cannot be included or used in the ACP and vice versa.
For pages and forms, the name of the template matches the unqualified name of the PHP class except for the Page
or Form
suffix:
RegisterForm.class.php
→register.tpl
UserPage.class.php
→user.tpl
If you follow this convention, WoltLab Suite Core will automatically determine the template name so that you do not have to explicitly set it.
For forms that handle creating and editing objects, in general, there are two form classes: FooAddForm
and FooEditForm
. WoltLab Suite Core, however, generally only uses one template fooAdd.tpl
and the template variable $action
to distinguish between creating a new object ($action = 'add'
) and editing an existing object ($action = 'edit'
) as the differences between templates for adding and editing an object are minimal.
Installing Templates#
Templates and ACP templates are installed by two different package installation plugins: the template PIP and the ACP template PIP. More information about installing templates can be found on those pages.
Base Templates#
Frontend#
1 2 3 4 5 |
|
Backend#
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
foo.bar.baz
is the language item that contains the title of the page.
Common Template Components#
Forms#
For new forms, use the form builder API.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
|
Tab Menus#
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
|
Template Scripting#
Template Variables#
Template variables can be assigned via WCF::getTPL()->assign('foo', 'bar')
and accessed in templates via $foo
:
{$foo}
will result in the contents of$foo
to be passed toStringUtil::encodeHTML()
before being printed.{#$foo}
will result in the contents of$foo
to be passed toStringUtil::formatNumeric()
before being printed. Thus, this method is relevant when printing numbers and having them formatted correctly according the the user’s language.{@$foo}
will result in the contents of$foo
to be printed directly. In general, this method should not be used for user-generated input.
Multiple template variables can be assigned by passing an array:
1 2 3 4 |
|
Modifiers#
Variable modifiers are used to modify the output of variables within templates.
These modifiers allow you to perform various operations on the variables before displaying them.
The general syntax for applying a variable modifier is {$variable|modifier}
.
Modifiers can be chained together to perform multiple operations on a variable. In such cases, the modifiers are applied from left to right. For example:
1 |
|
A modifier may accept additional parameters that affect its behavior. These parameters follow the modifier name and are separated by a :
. For example:
1 |
|
An overview of all available modifiers is available on a dedicated page.
System Template Variable#
$__wcf
contains theWCF
object (orWCFACP
object in the backend).
Comments#
Comments are wrapped in {*
and *}
and can span multiple lines:
1 2 |
|
The template compiler discards the comments, so that they not included in the compiled template.
Conditions#
Conditions follow a similar syntax to PHP code:
1 2 3 4 5 6 7 |
|
The supported operators in conditions are ===
, !==
, ==
, !=
, <=
, <
, >=
, >
, ||
, &&
, !
, and =
.
More examples:
1 2 3 |
|
Foreach Loops#
Foreach loops allow to iterate over arrays or iterable objects:
1 2 3 4 5 |
|
While the from
attribute containing the iterated structure and the item
attribute containg the current value are mandatory, the key
attribute is optional.
If the foreach loop has a name assigned to it via the name
attribute, the $tpl
template variable provides additional data about the loop:
1 2 3 4 5 6 7 8 9 10 11 |
|
In contrast to PHP’s foreach loop, templates also support foreachelse
:
1 2 3 4 5 |
|
Including Other Templates#
To include template named foo
from the same domain (frontend/backend), you can use
1 |
|
If the template belongs to an application, you have to specify that application using the application
attribute:
1 |
|
Additional template variables can be passed to the included template as additional attributes:
1 |
|
Template Plugins#
An overview of all available template plugins can be found here.