Write Up: Twig theme sprint @ Twin Cities Drupal Camp

On May 20 chx, crell, c4rl, mlncn, stevector, Jerdavis, quicksketch, and jenlampton sprinted on creating a new theme layer for Drupal 8, using Twig, along with help from various members of The Nerdery, Tom Cox, and other Twin Cities Drupal Camp attendees.

The goal for this sprint was to rebuild comment.tpl.php and everything rendered through it, using Twig. This action would involve replacing theme functions (such as theme_username) as well as template files (such as comment.tpl.php) and also force us to reconsider if each template file truly deserved to be a template of it's own (comment-wrapper.tpl.php) or if some should be replaced with a generic wrapper.tpl.php that could be used almost everywhere.

The long term goals for the Drupal 8 theme layer is to reduce confusion with template files, and create something more along the lines of Jacine's components in core.

But before we decided to do anything too drastic, C4rl, mlncn, stevector and I decided to have a "quick meeting" to discuss Twig template inheritance, to think about how the new Blocks Everywhere initiative tied into what we were working on, and to figure out our new template file naming conventions.

Twig template inheritance

The fist downside we noticed to using Twig inheritance with Drupal, is an obvious conflict of the "block" namespace. Drupal uses the word "block" to mean 'something that you put onto a page' but in Twig, a "block" is more like a "region" in Drupal. It's a part of the page that can have stuff added into it, or more accurately, a part of the HTML that may be overridden by a "child template".

The "child templates" in Twig contain only the overrides for the parent template. This is very efficient, since with Twig you would not get yourself into the problem of having eight nearly identical copies of any template, but the model of child templates only containing the HTML that is different is drastically different than the approach we are taking now, and will be difficult for our current theme developers to adjust to.

But page templates may not be our responsibility any more, since page layouts will be managed by the Blocks Everywhere initiative, and may end up being "Plugins" for that system.* THIS HAS NOT YET BEEN DECIDED

So for now, let's look at a smaller piece of the puzzle. Here is a sample wrapper template we came up with, wrapper.twig:

This template could be used for many things, a block is the obvious example, but could also be used for a region, a node, a comment, and maybe even a field or a form element. Almost everything in Drupal follows this basic pattern, a containing element around a title and content. Okay, so where does the inheritance come in? Where in a Drupal block, would you place a Twig block? The child template model doesn't really work for Drupal's "blocks", or smaller pieces of HTML.

The Blocks Everywhere initiative

Speaking of blocks, things get a little more complicated when we take the Blocks Everywhere initiative (code name Scotch) into consideration. Everything in Drupal 8 is going to become a block: nodes themselves, fields on nodes, comments, fields on comments, everything.

In Drupal 7, there were regions that were specified by your theme (in yellow, below) and blocks could be placed into those regions (in red, below).

In Drupal 8, The blocks Everywhere initiative will be responsible for the layout of your pages, as well as the placement of content within. Smaller blocks (in red, below) can be placed into larger blocks (in orange, below), and any type of block can be placed into the layout of your page (in green, below).

So how does this change things at the theme level? If everything is a block, should everything be run through the block template file? How do we want to differentiate between different kinds of blocks at the template level?

One option is to use Twig inheritance, and let every module that needs to add something additional override the HTML that is output for the contents part of the Twig file above. But Drupal already has a solution to that problem, modules can simply add their output into a renderable (as D7 would call it) or a TemplateData Object (as D8 will call it) and the appropriate output will appear as part of contents.

We decided that from what we knew of Twig template inheritance, it wasn't a better approach than what Drupal already does. But, we also all agreed that we aren't Twig experts, and that we wanted to see more, from someone who really understands Twig, before we gave up on it completely.

New template file naming conventions

And speaking of template files, we're going to need some new naming conventions. if everything is going to be a block, can we just drop 'block' from the file names altogether, and assume that if no specific template is requested, we always default back to using the wrapper? And how do we want to differentiate between a field on a node and a field on a comment, or do we?

PHPTemplate to Twig

We also struggled with which files to keep and which files to loose. If everything is a block, we could, in theory, ship Drupal core with only one template file! However, that would make overriding that file very complicated, there would be too many naming conventions, and learning how to use it woud be nearly impossible. So, we need to reach a reasonable compromise. We decided to keep the templates everyone loves to override (like node.tpl.php) and eliminate the ones everyone loves to hate (comment-wrapper.tpl.php).

Here's a first pass at a potential mapping of PHPTemplate files to Twig files, this is in no way final, these were just our first, second, and maybe third ideas.

On a more technical note

At the end of the Theme Sprint in April at the Chapter Three offices, chx had discovered that the __toString method could not be used for two major reasons. One, __toString has very special rules about exceptions thrown: PHP immediately fatals with an unhelpful error and you have no idea where and what happened. Calling Twig's template rendering might throw exceptions -- for example for template syntax errors -- and so it would be extremely developer unfriendly to call Twig from __toString. Two, one can't pass parameters to __toString.

While the rest of us were debating about Twig inheritance and template files in the Bat Cave, chx was solving this problem by creating Drupal's own version of __toString, currently called render() that can both catch exceptions and accept parameters to produce different output.

Summary

We may have ended up with more questions after this sprint than answers, but chx did solve a big problem by creating a function that will flatten a TemplateData Object into a string cleanly.

Beyond that, we also established a few new questions that need to be answered:

1. Can we use Twig template inheritance, or is what Drupal does already, better?
2. How many template files could/should be removed?
3. How do we want to name the new template files, and their overrides?

Next Steps

We ended the sprint by deciding to first re-write the existing comment rendering system in Twig, before we start throwing away the template files we will eventually get rid of. This will help us prove that we can do the theme layer in Twig, before we get blocked by too many decisions about what we should be doing to simplify things.