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.
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.
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
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:
- template_inherits_id was renamed to style_parent_id. Value points to parent style, 0 if there is no parent style.
- 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
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.