Twig Template: Correct usage of blocks

Matej Kuna aka Maťok 9 June 2017

Name the block correctly

{% block meta_tags %}
  {# ... #}
{% endblock %}

Don't use camel case.

According to twig coding standard

Use lower cased and underscored variable names

Apply same rule on block names. You can see same approach in Symfony form fields definitions where blocks are named like: money_widget, button_attributes, etc. When you want to define custom form type and custom rendering you must use suffix: _row, _label, etc. Please, keep up with this standard.

Don't use redundant prefix of suffix

Don't name blocks like meta_tags_block or block_meta_tags because it's obvious they are blocks. It's the same like name of each function starts with function. It's bad and unnecessary - avoid it.

Is it good practice to use kind of company prefix/suffix in block names? My advice is:

No
If template is specific for single project (it is used only in one bundle). This option is more likely.

Yes
If you are planning to use template across several project (in multiple bundles) or you are coding an open source.

Blocks for JavaScript or Style

The majority of blocks is defined like HTML, but there are cases when you define twig block for javascript code or style definition because they can be part of HTML. Always do it like this:

{# master.html.twig #}
{% block javascript %}
  <script>
    // js code here
  </script>
{% endblock %}

{# child.html.twig #}
{% extends 'master.html.twig' %}

{% block javascript %}
  {{ parent() }}
  <script>
    // js code of child here
  </script>
{% endblock %}

As you see I must repeat <script></script> tags but that's the point. If the javascript block definition was inside <script></script> tag then you likely lost syntax highlighting in your IDE.

Don't WET parent()

Despite previous paragraph repeating is mostly bad pactice. WET¹: If someone must type {{ parent() }} almost in every template then something is slightly fucked up and sooner or later someone else forget on {{ parent() }} and everyone will be surprised that something is not working or looks weird. If you find yourself out in described situation rewrite templates like this:

{# master.html.twig #}
{% block javascript_common %}
  <script>
    // core functionality needed on every page
  </script>
  {% block javascript %}{% endblock %}
{% endblock %}

{# child.html.twig #}
{% extends 'master.html.twig' %}

{% block javascript %}
  <script>
    // js code of child here
  </script>
{% endblock %}

It's very easy. Take care that you write code in child templates into nested block (javascript) only. In case of multiple level inheritance between templates it can be suitable to define more blocks nested in order fits you the best - you can make more blocks on master template or define new block in child template as shows code below. This stuff with javascript is just example. You can use this approach with any blocks (menu, sidebars, footer, ...) you have on page.

Example of three level inheritance:

layout.html.twig
  ┕ article.html.twig
    ┕ article_with_gallery.html.twig

{# layout.html.twig #}
{% block javascript_common %}
    <script>console.log('Core JS functionality');</script>

    {% block javascript %}{% endblock %}
{% endblock %}

{# article.html.twig #}
{% extends 'MatokBundle::layout.html.twig' %}

{% block javascript %}
    <script>console.log('Article JS functionality');</script>

    {% block javascript_custom %}{% endblock %}
{% endblock %}

{# article_with_gallery.html.twig #}
{% extends 'MatokBundle:Article:article.html.twig' %}

{% block javascript_custom %}
    <script>console.log('Article-Gallery JS functionality');</script>
{% endblock %}

No parent() here, but you can use it - there is nothing bad about it, but use it wisely and if you are using it often, then remember this blog post.

1: "write everything twice", "we enjoy typing" or "waste everyone's time"