Drupal theme engines documentation is almost nonexistent. To understand how they work you need to glean information from many sources. We hope this article will help developers in their process of learning this “dark side” of Drupal.
You can notice that Drupal theme is a collection of different files. And if everything’s clear with css and js files, you can still have a question: “How are the templates parsed?”.
A common template file contains HTML and PHP code. We use templates to separate views from the logic of application (read more Model-View-Controller). But where are the variables used in these templates taken from?
It is template engine that does the trick. It forwards necessary variables and generates plain HTML code based on templates.
Which Drupal template should be used for the theme is indicated in the info file. In Drupal 6 engine configuration is required for the themes. In Drupal 7 it is optional and PHPTemplate is used by default. Drupal 8 uses Twig.
How the PHP Template works
PHPTemplate contains only one file - phptemplate.engine (it is placed in themes/engines/phptemplate). There are 2 hooks - hook_init() and hook_theme() in this file.
Note: template engine doesn’t need the info file. So, they don’t have an integration with Update module. You won’t see versions and available updates for your site. Also, Drupal.org statistics doesn’t have any information about how many sites use this theme engine. You can verify this by choosing one of the following template engines on this page https://www.drupal.org/project/project_theme_engine.
Besides, PHPTemplate doesn't indicate using a very important function theme_render_template. This function parses templates by default. It’s very simple:
- It extracts variables from the $variables array (read more about extract function in the official documentation of PHP)
- It also buffers the output and includes our templates. After that, we can use variables.
How to integrate Drupal with your template engine
It’s very simple. We need to implement only 3 functions for correct work of your theme engine. Let's look at all the steps on a specific example. Let’s take a new template engine, which has no integration with Drupal. We chose Fenom. We took it only to show how this process should work (also the author of this article liked the results of performance tests that Fenom showed https://github.com/fenom-template/fenom/blob/master/docs/en/benchmark.md).
- It is necessary to connect the template.php file. Nothing unusual here, just copy it from PHPTemplate to your hook_init(). Also, you can check something here (e.g. check that the template engine library exists).
- Add templates that your template engine can work with. Copy them from PHPTemplate.
- And the third step is the most interesting. We need to override theme_render_template(). As template engines do not have an info file, we can not use autoloading classes. Therefore, we need to include necessary files.
After loading classes, we need to initialize Fenom
$fenom = Fenom::factory(DRUPAL_ROOT, variable_get('file_public_path', conf_path() . '/files'), array('force_compile' => TRUE));
and then call a function to parse templates by passing these function paths to the files and the required variables.
That's all. Our theme engine is ready to work. Then you can add more settings. For example, Fenom can cache the template output, so it would be logical to remove this cache on request.