Converting your Drupal Theme to Drupal 8: Part 1

by Dustin LeBlanc

My last article Modernize Your Drupal Theme tackled adding some modern touches to your legacy Drupal themes such as SCSS and Compass. With Drupal 8 on the horizon, Drupal theming is changing in some substantial ways. I'd like to take a look over the course of a few posts at the process of converting a current Drupal 7 theme to work with Drupal 8.

Along with some structural changes to how theme packages are laid out, one of the major changes in Drupal 8 theming is the switch from PHPTemplate to Twig for creating your page templates. At first it sounds scary; especially if you feel like you just finally learned PHP and theming for Drupal 7. The truth is, templating in Twig is no harder than templating in PHPTemplate, in fact the syntax and changes to Drupal's theming variables is probably some what easier.

In this article I want to look at a simple example; the header portion of Singlebrook's Drupal Streamline Theme page.tpl.php file:

This is the old page.tpl.php of our Drupal 7 starter theme. It is really generic and we significantly alter it for each project but it gets the job done for our purposes today. We see a typical interspersion of PHP and HTML here. You can make a template a lot simpler than this, and we frequently do. For themes that don't need the logo, site name, and slogan to be edittable on the backend (and really, unless you are distributing a theme for contrib use, most folks don't need this). For illustration, I am leaving all this in the gists so that we can see more of the twig variable and function use.

So to summarize what we have above; first we open with an HTML header tag and give it a unique role on line one; then we have a php conditional block that takes care of rendering our site logo if we are using one (in a default Drupal install this is our friendly drop logo) on lines three through seven.

We are making some calls to find out if the variable '$logo' is defined, and if it is we are then printing an anchor tag that links to our home page (again using our Drupal variables), printing our logo, adding some other info like titles and alt tags (making sure to sanitize them and make them available to be translated with the t() function) and closing the conditional with the 'endif' php tag.

For a front end themer this can be a pain, understanding some of the ternary operator short tags here isn't immediately obvious. For the developer who jumps back and forth between front end and back end Drupal work, seeing PHP everywhere tends to make us want to put PHP everywhere (probably places we shouldn't!).

This covers the basics of how we theme for drupal in Drupal 7, we are using html and interspersing some php to call variables from the system to render them into our layouts. We can do some nice things like call assets from our theme directory using some drupal specific functions for path definitions or some global varibles that the system already tracks for us. In Drupal 8, things are going to be very similar, just with some new syntax and some tweaks to the variables available to us. Here is a gist of the same section from the Drupal 8 port of the same theme:

The first thing you will notice is that there is no PHP here. We start with the same opening header tag and we tackle our friend the logo on lines three through seven again.

You can see some of the syntax changes here, for instance we are using Braces with percent symbols for our control structures and we are using 'mustaches' for inserting variables in our template. Look at line 4 to see how much shorter and more readable the syntax has become.

You can get some more information about the twig templating system here.

For developers who are coding PHP for module development and then also theming using twig this might mean a little bit more mental seperation. I swear I will want to type t('foo') rather than 'foo'|t for a while yet.

The other good news here for Drupal developers is that the twig templating engine is also the default for the Symfony2 framework. This means that learning to develop for Drupal is becoming a bit more of a cross-training skill than it has been in the past.

Make sure when you convert your files that you rename all your .tpl.php files to .html.twig so that Drupal 8 will recognize them.

That pretty much covers the basics of changing template files from Drupal 7 to Drupal 8. The only other difference is that there are some changes in which variables are available in Drupal 8 theming, the easiest way to see the basics here is just to scope out what was changed in Bartik and copy those changes; or alternatively, take a look through my page.html.twig for the Drupal 8 fork of Drupal Streamline.

Next time we will take a look at converting your template.php to a THEME_NAME.theme file. For really basic template.php files this is a cake walk, for more complicated ones, you might be for some late night coffee action.

Stay tuned!