Advanced template engine functionnality (blocks)

General discussion of development ideas and the approaches taken in the 3.x branch of phpBB. The next feature release of phpBB 3 will be 3.3/Proteus.
Forum rules
Please do not post support questions regarding installing, updating, or upgrading phpBB 3.2.x. If you need support for phpBB 3.2.x please visit the 3.2.x Support Forum on phpbb.com.

If you have questions regarding writing extensions please post in Extension Writers Discussion to receive proper guidance from our staff and community.
Nicofuma
3.2 Release Manager
3.2 Release Manager
Posts: 299
Joined: Sun Apr 13, 2014 1:40 am
Location: Paris

Advanced template engine functionnality (blocks)

Post by Nicofuma »

Twig is a very powerful template engine which come with some advanced features. One of them is the ability to structure the template in blocks and to use a template inheritance trough them (http://twig.sensiolabs.org/doc/template ... nheritance - http://twig.sensiolabs.org/doc/tags/extends.html).
Example:
The base template: base.html

Code: Select all

<!DOCTYPE html>
<html>
    <head>
        {% block head %}
            <link rel="stylesheet" href="style.css" />
            <title>{% block title %}{% endblock %} - My Webpage</title>
        {% endblock %}
    </head>
    <body>
        <div id="content">{% block content %}Base content{% endblock %}</div>
        <div id="footer">
            {% block footer %}
                &copy; Copyright 2011 by <a href="http://domain.invalid/">you</a>.
            {% endblock %}
        </div>
    </body>
</html>
And a child template: child.html

Code: Select all

{% extends "base.html" %}

{% block title %}Index{% endblock %}
{% block head %}
    {{ parent() }}
    <style type="text/css">
        .important { color: #336699; }
    </style>
{% endblock %}
{% block content %}
    <h1>Index</h1>
    <p class="important">
        Welcome to my awesome homepage.
    </p>
{% endblock %}
Then, in the php code we ask to render the child template and this code is generated:

Code: Select all

!DOCTYPE html>
<html>
    <head>
            <link rel="stylesheet" href="style.css" />
            <title>Index - My Webpage</title>
    <style type="text/css">
        .important { color: #336699; }
    </style>
    </head>
    <body>
        <div id="content">    <h1>Index</h1>
    <p class="important">
        Welcome to my awesome homepage.
    </p></div>
        <div id="footer">=
                &copy; Copyright 2011 by <a href="http://domain.invalid/">you</a>.=
        </div>
    </body>
</html>
That's template inheritance and it's already available in phpBB.

But it's not the only way to use the blocks because at any time we can request Twig to render a specific block in a given template but to send this request we need to have the Template element himself and that is currently not possible. It can be useful to define many different blocks for a set of module (ie: menu, toolbar, content, footer...) and then render each block of each module in different places in the code.
Example:

Code: Select all

[...]
{% for template in templates %}
{{ template.renderBlock('menu', {<arguments>}) }}
{% endfor %}
[...]
{% for template in templates %}
{{ template.renderBlock('footer', {<arguments>}) }}
{% endfor %}
[...]
This behavior can be simulate by two different ways:
  1. Define one template file per block and include them

    Code: Select all

    [...]
    {% for module_name in modules %}
    {% include module_name ~ '_menu.html' %}
    {% endfor %}
    [...]
    {% for module_name in modules %}
    {% include module_name ~ '_footer.html' %}
    {% endfor %}
    [...]
  2. Define a variable in the base template and use a combination of if in the included template
    Base template

    Code: Select all

    [...]
    {% for template_path in templates %}
    {% include template_path with { 'in_menu': true } %}
    {% endfor %}
    [...]
    {% for template_path in templates %}
    {% include template_path with { 'in_footer': true } %}
    {% endfor %}
    [...]
    Included template

    Code: Select all

    {% if in_menu %}
    MENU
    {% endif %}
    {% if in_footer %}
    FOOTER
    {% endif %}
So now the question is: Do we want to support this feature? And if the answer is yes how should we do?
  1. Now we are using Twig and \phpbb\template\template is only a BC interface => the template engine can extends \Twig_Environment and implements the interface
  2. \phpbb\template\template is a generic interface which allows us to change the template engine without changing all the code, only the templates could have to be updated => we can provide a get_engine() method to get the real template engine but in this case we can return anything and the user has to manage with (he has to test which engine is returned and then generate an appropriate code)
-------------------------
personally, after some thought,i don't think that we should support this feature but in the other case we should use the first solution (extend \Twig_Environment)
Member of the phpBB Development-Team
No Support via PM

User avatar
VSE
Extension Customisations
Extension Customisations
Posts: 673
Joined: Mon Mar 08, 2010 9:18 am

Re: Advanced template engine functionnality (blocks)

Post by VSE »

This would be good for allowing extensions to replace blocks with new blocks. Right now extensions can only add to the template, not replace/overwrite.
Has an irascible disposition.

User avatar
rfdy
Registered User
Posts: 45
Joined: Wed Apr 16, 2014 2:28 pm

Re: Advanced template engine functionnality (blocks)

Post by rfdy »

There are a few threads (and jiras) about doing this, ie. making full use of Twig's power.

+1

Nicofuma
3.2 Release Manager
3.2 Release Manager
Posts: 299
Joined: Sun Apr 13, 2014 1:40 am
Location: Paris

Re: Advanced template engine functionnality (blocks)

Post by Nicofuma »

But the real question is somewhere else: do we want to keep a generic (and so limited) interface to be able to replace the template engine later or do we want to abandon this interface?
Member of the phpBB Development-Team
No Support via PM

User avatar
nickvergessen
Former Team Member
Posts: 733
Joined: Sun Oct 07, 2007 11:54 am
Location: Stuttgart, Germany
Contact:

Re: Advanced template engine functionnality (blocks)

Post by nickvergessen »

We can also add <-- BLOCK --> to the phpBB interface and then mirror it just like all the other constructions?
Member of the Development-TeamNo Support via PM

Nicofuma
3.2 Release Manager
3.2 Release Manager
Posts: 299
Joined: Sun Apr 13, 2014 1:40 am
Location: Paris

Re: Advanced template engine functionnality (blocks)

Post by Nicofuma »

for the blocks it should be feasible
Member of the phpBB Development-Team
No Support via PM

User avatar
rfdy
Registered User
Posts: 45
Joined: Wed Apr 16, 2014 2:28 pm

Re: Advanced template engine functionnality (blocks)

Post by rfdy »

Not sure why you'd want to preserve phpbb's ancient template syntax. Modern IDEs support twig, and many projects are moving to twig (drupal, et al), so the more standard syntax it is kept the better.

Nicofuma
3.2 Release Manager
3.2 Release Manager
Posts: 299
Joined: Sun Apr 13, 2014 1:40 am
Location: Paris

Re: Advanced template engine functionnality (blocks)

Post by Nicofuma »

the question is not the syntax, but the php interface. (and the old syntax is very good for some designers, because the syntax of twig can be very complicated for some of them)
Member of the phpBB Development-Team
No Support via PM

User avatar
VSE
Extension Customisations
Extension Customisations
Posts: 673
Joined: Mon Mar 08, 2010 9:18 am

Re: Advanced template engine functionnality (blocks)

Post by VSE »

rfdy wrote:Not sure why you'd want to preserve phpbb's ancient template syntax. Modern IDEs support twig, and many projects are moving to twig (drupal, et al), so the more standard syntax it is kept the better.
because hundreds of styles are built on it and authors are used to it, and preserving it will allow authors to more easily update their styles to 3.1. Jumping straight into Twig only Syntax with no preservation of traditional syntax could create a black hole in new style development. And that could then result in decreased adoption of phpBB 3.1 by users who see no useable styles for ready for it.

The idea is to switch to Twig only gradually, by version 3.2.
Has an irascible disposition.

Nicofuma
3.2 Release Manager
3.2 Release Manager
Posts: 299
Joined: Sun Apr 13, 2014 1:40 am
Location: Paris

Re: Advanced template engine functionnality (blocks)

Post by Nicofuma »

the syntax of the template files is definitely not a problem: we can use the two syntaxes in the same template file. Currently the only limitation is made by the php interface (\phpbb\template\template) because the Twig object is encapsulated and to keep a generic interface we can't access it directly.
Member of the phpBB Development-Team
No Support via PM

Post Reply