New Template Engine Functions in 3.1

Template engine in phpBB 3.0 is different than template engine for phpBB 3.1, but most functions remain the same. This article lists new and changed functions.

Style components merge
Style components were merged. When this article refers to templates in phpBB 3.1, it refers to template .html files in templates directory in style.

There is now new global variable $style, which represents style. $template still exists and it deals with templates.

set_custom_style and set_custom_template
In phpBB 3.0 to set custom template directory, the following code was used $template->set_custom_template($phpbb_admin_path . 'style', 'admin'); First parameter was path to template files, second parameter was keyword used for template cache.

In phpBB 3.1 instead of setting path to templates, you set path to style. Therefore function was renamed from set_custom_template to set_custom_style

Function has 3 parameters:
 * 1) $name: string. Value is a keyword used for template cache, same as second parameter to old set_custom_template
 * 2) $paths: string or array. Value is path to style files. You can set more than one path to take advantage of style inheritance, then $paths should be array of paths.
 * 3) $template_path: string. Value is path to template files relative to style directory. Examples: ' ' (empty string), 'template/'. This parameter is optional

Example: $template->set_custom_style('admin', $phpbb_admin_path . 'style', '');

append_var
This function works just like assign_var, but instead of assigning a variable, it appends value to existing variable.

Function has 2 parameters:
 * 1) $varname: string. Variable name
 * 2) $varval: string. Value

If variable does not exist, function will work exactly like assign_var

locate
This function locates template files or style resources. There are two versions of it: $style->locate and $template->locate, the difference is file paths in $style->locate are relative to style directory (such as styles/prosilver/), file paths in $template->locate are relative to template directory (such as styles/prosilver/template/).

Function has 3 parameters:
 * 1) $files: array. Array of files to locate. If there is only 1 file to check, $files can be a string to make code easier to read.
 * 2) $return_default: boolean. Determines what to return if file does not exist. If true, function will return location where file is supposed to be. If false, function will return false.
 * 3) $return_full_path: boolean. If true, function will return full path to file. If false, function will return file name. This parameter can be used to check which one of set of files is available.

If files were not found, function will return false if $return_default is false or path to where file is supposed to be if $return_default is true.

Example of usage: You need to show message as AJAX data. If style has message_ajax.html, you want to use message_ajax.html. If style does not have it, you want to use message_body.html. Use function locate to check which one of those templates is available: $template_name = $template->locate(array('message_ajax.html', 'message_body.html'), true, false); $template->set_filenames(array('body' => $template_name));

Why second parameter was set to "true"? To make sure function returns file. If files do not exist set_filenames will trigger error, so there is no need to check if file exists before that.

Why third parameter was set to "false"? To return only template name. Function will return ether 'message_ajax.html' or 'message_body.html'.

Another example: you want to find where template "bbcode.html" is located in order to parse it without template engine. The following code will return its location: $template_location = $template->locate('bbcode.html', false, true);

Why second parameter was set to "false"? To return false if file does not exist, allowing you to trigger error.

Why third parameter was set to "true"? To return full path to file, ready to be read via file_get_contents or any other function.