Template preview mode for Twig templates

[leofeyer]

Description

As discussed on the Contao camp, it is difficult to analyze the parent Twig templates when extending a template. This is the content of a new template added in the back end:

{% extends "@Contao/content_element/downloads.html.twig" %}

{#
  ** Add changes to the base template here. **

  Hint: Try adjusting blocks and attributes instead of
  overwriting the whole template. This way your version
  can remain compatible with future changes to the base
  template as well as adjustments made by extensions.

  Currently available blocks:
    "list_component", "list", "list_attributes",
    "list_item_attributes", "list_item", "pagination",
    "list_script", "pagination_script_show_element",
    "pagination_script_activate_selector",
    "picture_component", "image", "sources", "source",
    "schema_org", "figure_component", "media",
    "media_link", "caption", "caption_inner",
    "download_component", "download_link",
    "download_link_attributes", "download_link_inner",
    "file_previews", "file_preview", "content",
    "headline_component", "headline_attributes",
    "headline_inner", "wrapper", "wrapper_tag",
    "attributes", "inner", "metadata", "style",
    "script"

  Example:
    {% block list_component %}
       {{ parent() }}
       My additional content for 'list_component'…
    {% endblock %}
#}

The available blocks come from 4 different templates:

• _base.html.twig
• _list.html.twig
• _download.html.twig
• downloads.html.twig

To really understand how to adjust the custom template, most developers want to look at the original templates, which is currently not possible in the back end. A possible solution would be a link to the original template on GitHub or a template preview mode in the back end.

[m-vo]

This is even more complicated: there could be embedded templates, horizontal reuse etc. and blocks could be overwritten.

However, our inspector system is already capable of recording the structure at compile time, so we could probably improve the experience. Keep in mind, that the Symfony profiler already tells you about the effectively rendered templates, so this might be a starting point.

[m-vo]

I think I need to clarify things a bit more with an example:

Let's assume there is the fancy-downloads extension that adds images to your downloads list. There are also adjustments to the content_element/base.html.twig template in your system. Now you want to adjust something with the downloads, so you already need to make a decision: Do I want everything using the downloads component to be affected or just the download content element ...? Then you maybe create a content_element/download.html.twig template, extend from @Contao/content_element/download.html.twig and start overwriting blocks of any parent template or any imported block of any parent template. Depending on what you actually want to achieve there are now a lot of places:

1. content_element/_base.html.twig (core)
2. content_element/_base.html.twig (your app)
3. component/_headline.html.twig (via the base template)
4. content_element/downloads.html.twig (core)
5. content_element/downloads.html.twig (fancy-downloads)
6. component/_list.html.twig
7. component/_download.html.twig
8. component/_figure.html.twig (either via fancy-downloads or by using file previews)
9. component/_picture.html.twig

And depending on the complexity of the project, there could be more. Sometimes you need to jump from template to template to find the correct level of abstraction, that you want/decide to use for your adjustments. Its very similar to writing code - going up base classes and following dependencies. Having different levels of possible adjustments is something, that was not possible with the old framework, so you needed to overwrite everything all the time.

If you are using PHPStorm with the Symfony plugin, you can already traverse templates and quickly find the right spot thanks to our ide-twig.json helper file (still needs to be put at a better location, though). For the backend we would probably need an editor, that could do something similar. This would be possible with the inspector data, but it's not an easy task at all. And there is also a difference between creating a template (you already know what you want to do, because you selected this exact template) and traversing the rendered templates, finding out what to do.