Development Wiki

Template Inheritance Changes in 3.1

From phpBB Development Wiki

Template inheritance allowed to create child template sets without copying all templates. In phpBB 3.0 there was only 2 levels deep template inheritance: one parent template set and child template sets. Child template sets couldn't have child template sets, therefore template inheritance was very simple.

In phpBB 3.1 template inheritance still exists, but it is different.

Styles tree

To avoid confusion, template inheritance is now known as styles tree. Term "template inheritance" was confusing people, styles tree is easier to understand. After all, it is a tree.

Example of styles tree:

- prosilver
- - prosilver se
- - - progreen se


In addition to installed styles, phpBB 3.1 has extensions. Extensions have their own styles that needs to be taken into account when searching for templates. Therefore styles tree became many levels deep.

Style components merge

Style components were merged. As a result, template inheritance data was moved from templates to styles. Template inheritance is now known as styles tree. There are parent and child styles.

Style configuration

Field "inherits_from" from template.cfg was moved to style.cfg and was renamed to "parent".

Example of style.cfg:

# General Information about this style
name = prosilver (Blue)
copyright = © phpBB Group, 2007
version = 3.1.0-dev

# Defining a different template bitfield
# template_bitfield = lNg=

# Parent style
# Set value to empty if this style does not have a parent style
parent = prosilver

Database changes

phpBB 3.0 has two fields for styles tree in phpbb_template table: template_inherits_id and template_inherit_path. phpbb_template table no longer exists, so these field were moved to phpbb_style and renamed:

  1. template_inherits_id was renamed to style_parent_id. Value points to parent style, 0 if there is no parent style.
  2. template_inherit_path was renamed to style_parent_tree. Value lists directories where parent styles are located.

Styles tree can be many levels deep, so style_parent_tree might have more than one path. Paths are separated with "/". For example "prosilver/progreen" means this style's parent style is located in "progreen" and its parent style is located in "prosilver".

What styles tree applies to

In phpBB 3.0 it was applied only to templates. in phpBB 3.1 it is applied to templates and to javascript files that are included via <!-- INCLUDEJS -->. It does not apply to css files and images yet.

Is there a global parent style?

Yes, there is. It is called "all".

How to correctly use styles tree for events and extensions

All events and extensions that override templates or have templates for events, should store those templates in ext/extension_name/styles/all/template/ and override them with style specific templates in ext/extension_name/styles/style_name/template/

For example, if you want to add code to HEAD section of overall_header.html, you need to create template overall_header_head.html that will be appended to HEAD section via "overall_header_head" template event. You should create the following file: ext/extension_name/styles/all/template/overall_header_head.html

Generally styles are based on prosilver, therefore it makes sense to put prosilver's code in that file. If you want to use different code for subsilver2, create another file and put subsilver2 version of your code in it: ext/extension_name/styles/subsilver2/template/overall_header_head.html

That file will be used instead of styles/all/ file for subsilver2 styles and its child styles because it is lower in styles tree than "all". Both files will not be included, only 1 file that is closer to current style in styles tree will be included.