From be15db1f28227a4cce7e0572d6eb3bfbeb5f5492 Mon Sep 17 00:00:00 2001
From: Alex Pott <alex.a.pott@googlemail.com>
Date: Sat, 4 Oct 2014 15:15:51 +0200
Subject: [PATCH] Issue #1332068 by Cottser, pixelmord | tim.plunkett:
 ENGINE_render_template() and ENGINE_extension() are undocumented.

---
 core/modules/system/theme.api.php             | 36 +++++++++++++++++++
 .../engines/phptemplate/phptemplate.engine    |  2 ++
 core/themes/engines/twig/twig.engine          |  4 ++-
 3 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/core/modules/system/theme.api.php b/core/modules/system/theme.api.php
index 70426ecdd7f..1a613b7d6f7 100644
--- a/core/modules/system/theme.api.php
+++ b/core/modules/system/theme.api.php
@@ -495,3 +495,39 @@ function hook_themes_uninstalled(array $themes) {
     \Drupal::state()->delete('example.' . $theme);
   }
 }
+
+/**
+ * Declare a template file extension to be used with a theme engine.
+ *
+ * This hook is used in a theme engine implementation in the format of
+ * ENGINE_extension().
+ *
+ * @return string
+ *   The file extension the theme engine will recognize.
+ */
+function hook_extension() {
+  // Extension for template base names in Twig.
+  return '.html.twig';
+}
+
+/**
+ * Render a template using the theme engine.
+ *
+ * @param string $template_file
+ *   The path (relative to the Drupal root directory) to the template to be
+ *   rendered including its extension in the format 'path/to/TEMPLATE_NAME.EXT'.
+ * @param array $variables
+ *   A keyed array of variables that are available for composing the output. The
+ *   theme engine is responsible for passing all the variables to the template.
+ *   Depending on the code in the template, all or just a subset of the
+ *   variables might be used in the template.
+ *
+ * @return string
+ *   The output generated from the template. In most cases this will be a string
+ *   containing HTML markup.
+ */
+function hook_render_template($template_file, $variables) {
+  $twig_service = \Drupal::service('twig');
+
+  return $twig_service->loadTemplate($template_file)->render($variables);
+}
diff --git a/core/themes/engines/phptemplate/phptemplate.engine b/core/themes/engines/phptemplate/phptemplate.engine
index 0521092eb44..a4eee497a75 100644
--- a/core/themes/engines/phptemplate/phptemplate.engine
+++ b/core/themes/engines/phptemplate/phptemplate.engine
@@ -31,6 +31,8 @@ function phptemplate_extension() {
 }
 
 /**
+ * Implements hook_render_template().
+ *
  * Renders a system default template, which is essentially a PHP template.
  *
  * @param $template_file
diff --git a/core/themes/engines/twig/twig.engine b/core/themes/engines/twig/twig.engine
index c859b65dc68..6f4aece8b6f 100644
--- a/core/themes/engines/twig/twig.engine
+++ b/core/themes/engines/twig/twig.engine
@@ -33,6 +33,8 @@ function twig_init(Extension $theme) {
 }
 
 /**
+ * Implements hook_render_template().
+ *
  * Renders a Twig template.
  *
  * If the Twig debug setting is enabled, HTML comments including _theme() call
@@ -43,7 +45,7 @@ function twig_init(Extension $theme) {
  * @param $variables
  *   A keyed array of variables that will appear in the output.
  *
- * @return
+ * @return string
  *   The output generated by the template, plus any debug information.
  */
 function twig_render_template($template_file, $variables) {