Template engine changes to allow for structure flexibility

Note: We are moving the topics of this forum and it will be deleted at some point

Publish your own request for comments/change or patches for the next version of phpBB. Discuss the contributions and proposals of others. Upcoming releases are 3.2/Rhea and 3.3.
User avatar
PayBas
Registered User
Posts: 305
Joined: Tue Jul 29, 2008 6:08 pm
Contact:

Template engine changes to allow for structure flexibility

Post by PayBas »

For future styles development, we are looking into restructuring the template files. This will be done in a more object oriented way, with an emphasis on splitting the templates up into reusable, self-contained blocks. It has been brought up before, particularly here: https://area51.phpbb.com/phpBB/viewtopi ... 81&t=45763

This reorganization will be particularly helpful when used in combination with the more advanced Twig functions, and will allow specific components to extend each other, thus reducing the amount of duplicate code, as well as promoting better consistency of said code.

However, in order to do this, we need to change some things in the core. The problem is that most templates (all, except those that are only used via the template <!-- INCLUDE foobar.html --> command) are hard-coded into the back-end.
They are usually assigned using $template->set_filenames(array('foobar.html' => 'foobar.html'));

There are a few problems with this, which are hampering style development:
  1. All templates are assumed to be in the root template/ directory. This makes it impossible to refactor some template files into subdirectories.
  2. All template names are hard-coded. This prevents us from renaming certain templates, which is useful if we want to split up certain templates (particularly in combination with point 1).
  3. All template files assume a .html file extension. Future styles will most likely be written using Twig syntax, rather than our own phpBB template syntax. The preferred file extension for Twig html files is .html.twig.
So how should we address this? Ideally, we would want a method that:
  1. Doesn't break backwards-compatibility (or at least doesn’t require major changes to existing 3.1 styles).
  2. Allows authors a degree of freedom when structuring and naming their templates.
  3. Allow greater control over the template inheritance tree traversal.
  4. Is easy to understand.
I see 3 possible courses of action:
  1. Do nothing: this would force all style authors to use the same flat-file structure that we have now, preventing any real style restructuring
  2. Update all template references in the core: we could update these references to reflect the new template names and directory structure, forcing all new styles to comply (and requiring significant changes to prosilver).
  3. Have a “template abstraction layer”: each style provides a small file with information that maps the core template references to the actual template files in the style.
How the Template Abstraction Layer (TAL) could work
Please note that Nicofuma, MichaelC and me have experimented with this implementation. It works, but it is highly experimental code, and very much open for discussion.

Each style would have a template.json file, which serves only 1 goal: to map the template references in the core to the actual template files in the style. Nothing more.
The template engine would be changed to lookup these references in the style to be displayed, instead of the direct filenames. The TAL file would be cached, so lookups are near instantaneous.

This setup differs significantly from "config" files that we had in the past (such as imageset.cfg), in that the TAL doesn't contain any styling information at all, just information on structure.

Code sample:

Code: Select all

{
	"faq_body" : "faq.html.twig",
	"index_body" : "index.html.twig",
	"viewforum_body": "viewforum.html.twig",
	"viewtopic_body" : "viewtopic.html.twig",
	"mcp_front" : "mcp/index.html.twig",
	"ucp_main_front" : "ucp/index.html.twig",
}
Advantages:
  • Allows style authors complete freedom to structure and name their template files as they see fit.
  • Allows for greater inheritance control by allowing the use of namespaces for styles.
  • 3.1 compatible styles need only include a single TAL file (which they can simply copy from prosilver 3.2).
Disadvantages:
  • Current styles need to be updated to include the TAL file.
  • Support questions for particular styles might become more confusing since template names are variable.
All comments are welcome. But preferably from people that have an actual stake in the matter (style authors, development team, website team, etc.)

User avatar
Arty
Former Team Member
Posts: 985
Joined: Wed Mar 06, 2002 2:36 pm
Location: Mars
Contact:

Re: Template engine changes to allow for structure flexibility

Post by Arty »

I've never seen anyone ever wanting to rename a template file. Each template file has its own purpose, variables inside that template file are specific to that template file and are not reusable in other files, so there is no point in renaming files.

The only usage for this is to add .twig to templates that use twig syntax, but wouldn't that cause problems for users? Twig templates are html code with control structures and other twig stuff (so basically no different than current .html templates, but with different syntax), extra extension might only cause problems with html editors.
PayBas wrote:Allows authors a degree of freedom when structuring and naming their templates.
Something that as far as I'm aware no style author ever wanted or needed to do.
PayBas wrote:Allow greater control over the template inheritance tree traversal.
Do you mean ability to point to template from another style? If its already part of style tree then template inheritance already takes care of it, therefore template name mapping is pointless. If its not part of style tree then there should be mechanism to make sure required template exists, adding extra layer of complexity to styles management, which requires a lot of development and testing for feature that I doubt anyone would ever use.

User avatar
hanakin
Front-End Dev Team Lead
Front-End Dev Team Lead
Posts: 968
Joined: Sat Dec 25, 2010 9:02 pm
Contact:

Re: Template engine changes to allow for structure flexibility

Post by hanakin »

Arty wrote:I've never seen anyone ever wanting to rename a template file.
maybe its just how you worded this, perhaps you are referring to the controllers, but this is not true in either case. We have renamed a lot of the template files in 3.1 vs 3.2 and all of them really need re-looked at/renamed. As for the controllers some of them are named horribly ie any of them that begin with view.
Donations welcome via Paypal Image

User avatar
DavidIQ
Customisations Team Leader
Customisations Team Leader
Posts: 1903
Joined: Thu Mar 02, 2006 4:29 pm
Location: Earth
Contact:

Re: Template engine changes to allow for structure flexibility

Post by DavidIQ »

He means going outside the file naming we've set up. I have to agree with him and can't see any reason for style authors to be given the freedom to name the template files whatever they feel like. Viewforum should just be called that; same for index, viewtopic, etc. Allowing such a thing could also be trouble for some extensions.
Image

User avatar
hanakin
Front-End Dev Team Lead
Front-End Dev Team Lead
Posts: 968
Joined: Sat Dec 25, 2010 9:02 pm
Contact:

Re: Template engine changes to allow for structure flexibility

Post by hanakin »

I am not saying that it nessecarily should be up to the author, but they really do need renamed as everything having view infront of it for example is misleading and confusing for professionals coming to phpbb for the first time. If i want to edit the structure/look of a forum row I should find it in the forum file. essentially keeping the object form the entire way through design/development of the theme.

But this is not really the main problem, and vearing offtopic. The main issue is that we need to allow for a more modular template breakout. This is currently limited by the backend which needs addressed. Second the controllers do not lend them selfs well to the way twig works if I am understanding this correctly (@PayBas correct me if I am wrong here).

Current templates work off the include principle which is very basic and primitive by comparison. Twig allows for more powerful and dynamic methods of inclusion and enxtendability which is currently blocked/limited.
Donations welcome via Paypal Image

User avatar
Arty
Former Team Member
Posts: 985
Joined: Wed Mar 06, 2002 2:36 pm
Location: Mars
Contact:

Re: Template engine changes to allow for structure flexibility

Post by Arty »

hanakin wrote:maybe its just how you worded this, perhaps you are referring to the controllers, but this is not true in either case.
I meant as designer. PayBas posted that it will give greater freedoms to designers. I've yet to see a designer that ever wanted to rename template file and don't think I'll ever will see one. Why? Because it is pointless.

As for controllers, it is still a simple rename and there is no reason to add extra layer of complexity.

User avatar
hanakin
Front-End Dev Team Lead
Front-End Dev Team Lead
Posts: 968
Joined: Sat Dec 25, 2010 9:02 pm
Contact:

Re: Template engine changes to allow for structure flexibility

Post by hanakin »

Arty wrote:
hanakin wrote:maybe its just how you worded this, perhaps you are referring to the controllers, but this is not true in either case.
I meant as designer. PayBas posted that it will give greater freedoms to designers. I've yet to see a designer that ever wanted to rename template file and don't think I'll ever will see one. Why? Because it is pointless.
False? As a designer I want to rename them! Paybas wants to rename them! I have never liked the names as they are not semantic and the structure is not clean and easy to maintain.
Donations welcome via Paypal Image

User avatar
Arty
Former Team Member
Posts: 985
Joined: Wed Mar 06, 2002 2:36 pm
Location: Mars
Contact:

Re: Template engine changes to allow for structure flexibility

Post by Arty »

Why would you want to do that?

User avatar
hanakin
Front-End Dev Team Lead
Front-End Dev Team Lead
Posts: 968
Joined: Sat Dec 25, 2010 9:02 pm
Contact:

Re: Template engine changes to allow for structure flexibility

Post by hanakin »

Arty wrote:Why would you want to do that?
I think you are completely misunderstanding. Not each and everytime. I want to rename them from what they are now for the FF files. Also as a theme/extension authour I wish to break things out by objects and as you add new objects you will need new files for those objects.
Donations welcome via Paypal Image

User avatar
Arty
Former Team Member
Posts: 985
Joined: Wed Mar 06, 2002 2:36 pm
Location: Mars
Contact:

Re: Template engine changes to allow for structure flexibility

Post by Arty »

And how does mapping help you with that? It is still a simple rename. You can break it into object with current naming or after mapping - it won't make any difference.

Post Reply