diff --git a/core/includes/theme.inc b/core/includes/theme.inc index a6d9362..aa76705 100644 --- a/core/includes/theme.inc +++ b/core/includes/theme.inc @@ -486,37 +486,20 @@ function drupal_find_base_themes($themes, $key, $used_keys = array()) { * engine, it overrides the default implementation of the 'page' theme hook by * containing a 'page.html.twig' file within its folder structure). * - * @subsection sub_preprocess_templates Preprocessing for Template Files - * If the implementation is a template file, several functions are called before - * the template file is invoked to modify the $variables array. These make up - * the "preprocessing" phase, and are executed (if they exist), in the following - * order (note that in the following list, HOOK indicates the theme hook name, - * MODULE indicates a module name, THEME indicates a theme name, and ENGINE - * indicates a theme engine name): - * - template_preprocess(&$variables, $hook): Creates a default set of variables - * for all theme hooks with template implementations. - * - template_preprocess_HOOK(&$variables): Should be implemented by the module - * that registers the theme hook, to set up default variables. - * - MODULE_preprocess(&$variables, $hook): hook_preprocess() is invoked on all - * implementing modules. - * - MODULE_preprocess_HOOK(&$variables): hook_preprocess_HOOK() is invoked on - * all implementing modules, so that modules that didn't define the theme hook - * can alter the variables. - * - ENGINE_engine_preprocess(&$variables, $hook): Allows the theme engine to - * set necessary variables for all theme hooks with template implementations. - * - ENGINE_engine_preprocess_HOOK(&$variables): Allows the theme engine to set - * necessary variables for the particular theme hook. - * - THEME_preprocess(&$variables, $hook): Allows the theme to set necessary - * variables for all theme hooks with template implementations. - * - THEME_preprocess_HOOK(&$variables): Allows the theme to set necessary - * variables specific to the particular theme hook. - * - * @subsection sub_preprocess_theme_funcs Preprocessing for Theme Functions - * If the implementation is a function, only the theme-hook-specific preprocess - * functions (the ones ending in _HOOK) are called from the list above. This is - * because theme hooks with function implementations need to be fast, and - * calling the non-theme-hook-specific preprocess functions for them would incur - * a noticeable performance penalty. + * @subsection sub_prepare_variables Preparing Variables for Theme Hooks + * Several functions are invoked before theme functions or template files are + * provided their available $variables. These functions make up the "prepare" + * phase, and are executed (if they exist), in the following + * order (HOOK indicates the profile, module, theme engine or theme name, + * THEME_HOOK indicates the name of the specific theme hook called): + * - HOOK_theme_prepare(&$variables, $hook): Prepare a set of variables + * for all theme hook implementations. + * - HOOK_theme_prepare_THEME_HOOK(&$variables): Prepare a set of + * variables for a specific theme hook implementation. + * - HOOK_theme_prepare_alter(&$variables, $hook): Alter a set of prepared + * variables for all theme hook implementations. + * - HOOK_theme_prepare_THEME_HOOK_alter(&$variables, $context): Alter a set of + * prepared variables for a specific theme hook implementation. * * @subsection sub_alternate_suggestions Suggesting Alternate Hooks * Alternate hooks can be suggested by implementing the hook-specific @@ -532,11 +515,11 @@ function drupal_find_base_themes($themes, $key, $used_keys = array()) { * * @param $hook * The name of the theme hook to call. If the name contains a - * double-underscore ('__') and there isn't an implementation for the full - * name, the part before the '__' is checked. This allows a fallback to a + * double-underscore ('__') and there is not an implementation for the full + * name, the name before the '__' is checked. This allows a fallback to a * more generic implementation. For example, if theme('links__node', ...) is * called, but there is no implementation of that theme hook, then the - * 'links' implementation is used. This process is iterative, so if + * 'links' implementation is used instead. This process is iterative, so if * theme('links__contextual__node', ...) is called, theme() checks for the * following implementations, and uses the first one that exists: * - links__contextual__node @@ -550,7 +533,7 @@ function drupal_find_base_themes($themes, $key, $used_keys = array()) { * convention is not desired or is insufficient. * @param $variables * An associative array of variables to merge with defaults from the theme - * registry, pass to preprocess functions for modification, and finally, pass + * registry, pass to prepare functions for modification, and finally, pass * to the function or template implementing the theme hook. Alternatively, * this can be a renderable array, in which case, its properties are mapped to * variables expected by the theme hook implementations. @@ -563,6 +546,8 @@ function drupal_find_base_themes($themes, $key, $used_keys = array()) { * @see themeable * @see hook_theme() * @see template_preprocess() + * + * @throws Exception */ function theme($hook, $variables = array()) { static $default_attributes; @@ -654,10 +639,6 @@ function theme($hook, $variables = array()) { elseif (!empty($info['render element'])) { $variables += array($info['render element'] => array()); } - // Supply original caller info. - $variables += array( - 'theme_hook_original' => $original_hook, - ); // Set base hook for later use. For example if '#theme' => 'node__article' // is called, we run hook_theme_suggestions_node_alter() rather than @@ -670,6 +651,12 @@ function theme($hook, $variables = array()) { $base_theme_hook = $hook; } + // Supply original caller info. + $variables += array( + 'theme_hook' => $base_theme_hook, + 'theme_hook_original' => $original_hook, + ); + // Invoke hook_theme_suggestions_HOOK(). $suggestions = Drupal::moduleHandler()->invokeAll('theme_suggestions_' . $base_theme_hook, array($variables)); // If theme() was invoked with a direct theme suggestion like @@ -712,6 +699,43 @@ function theme($hook, $variables = array()) { $info['preprocess functions'] = $base_hook_info['preprocess functions']; } } + + // A list of hooks that will be invoked for the given theme hook. + $prepare_hooks = array( + 'theme_prepare', + 'theme_prepare_' . $base_theme_hook, + ); + // If the original theme hook is not the same as the base theme hook, then + // invoke the original theme hook suggestion after the base theme hook. + if ($hook !== $original_hook) { + $prepare_hooks[] = 'theme_prepare_' . $original_hook; + } + + // Send prepare arguments to invoke hooks with $variables passed by reference. + $prepare_args = array(&$variables, $base_theme_hook); + + // Invokes hook_theme_prepare(), hook_theme_prepare_THEME_HOOK() for enabled + // modules. + foreach ($prepare_hooks as $prepare_hook) { + foreach (\Drupal::moduleHandler()->getImplementations($prepare_hook) as $module) { + $prepare_function = $module . '_' . $prepare_hook; + if (function_exists($prepare_function)) { + call_user_func_array($prepare_function, $prepare_args); + } + } + } + + // Invokes hook_theme_prepare(), hook_theme_prepare_THEME_HOOK() for the active + // theme, which takes precedence over modules. + // @todo Replace with Drupal::themeHandler()->invoke() once implemented. + // @see https://drupal.org/node/2029819 + foreach ($prepare_hooks as $prepare_hook) { + theme_invoke($prepare_hook, $prepare_args); + } + + // Invokes hook_preprocess() and hook_preprocess_HOOK() implementations. This + // phase is deprecated and is run in between hook_theme_prepare[_THEME_HOOK]() + // and hook_theme_prepare[_THEME_HOOK]_alter(). if (isset($info['preprocess functions'])) { foreach ($info['preprocess functions'] as $preprocessor_function) { if (function_exists($preprocessor_function)) { @@ -720,6 +744,14 @@ function theme($hook, $variables = array()) { } } + // Invokes hook_theme_prepare_alter(), hook_theme_prepare_THEME_ID_alter() + // for enabled modules. + // @todo Add Drupal::themeHandler()->alter() invocations once implemented. + // @see https://drupal.org/node/2029819 + foreach ($prepare_hooks as $prepare_hook) { + Drupal::moduleHandler()->alter($prepare_hook, $variables, $base_theme_hook); + } + // Generate the output using either a function or a template. $output = ''; if (isset($info['function'])) { @@ -1205,6 +1237,39 @@ function theme_disable($theme_list) { } /** + * Rudimentary and temporary method for invoking theme hooks. + * + * @param string $hook + * The hook name to invoke. + * @param array $args + * The array of arguments to pass to hook invocation (by reference). + * + * @return mixed + * The value returned varies on which hook is invoked. + * + * @todo Remove once a proper Drupal::themeHandler() is created. + * @see https://drupal.org/node/2029819 + */ +function theme_invoke($hook, &$args = array()) { + // Allow the active theme to invoke hooks after the theme system has been + // initialized. + global $theme, $base_theme_info; + if (isset($theme)) { + $theme_keys = array(); + foreach ($base_theme_info as $base) { + $theme_keys[] = $base->name; + } + $theme_keys[] = $theme; + foreach ($theme_keys as $theme_key) { + $function = $theme_key . '_' . $hook; + if (function_exists($function)) { + call_user_func_array($function, $args); + } + } + } +} + +/** * @addtogroup themeable * @{ */ diff --git a/core/modules/system/lib/Drupal/system/Tests/Theme/ThemePrepareTest.php b/core/modules/system/lib/Drupal/system/Tests/Theme/ThemePrepareTest.php new file mode 100644 index 0000000..9614924 --- /dev/null +++ b/core/modules/system/lib/Drupal/system/Tests/Theme/ThemePrepareTest.php @@ -0,0 +1,197 @@ + 'Theme Prepare API', + 'description' => 'Test theme prepare and alter functions.', + 'group' => 'Theme', + ); + } + + function setUp() { + parent::setUp(); + theme_enable(array('test_theme')); + } + + function testThemePrepare() { + $this->drupalGet('theme-test/prepare'); + + $this->assertRaw('
moduleVariable1: Drupal\theme_test\ThemeTestController::prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleVariable2: Drupal\theme_test\ThemeTestController::prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleVariableSuggestion1: Drupal\theme_test\ThemeTestController::prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleVariableSuggestion2: Drupal\theme_test\ThemeTestController::prepare
+theme_test_theme_prepare_theme_test_prepare__implemented
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+test_theme_theme_prepare_theme_test_prepare__implemented
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
+theme_test_theme_prepare_theme_test_prepare__implemented_alter
moduleVariableSuggestion3: Drupal\theme_test\ThemeTestController::prepare
+theme_test_theme_prepare_theme_test_prepare__implemented__extended
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+test_theme_theme_prepare_theme_test_prepare__implemented__extended
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
+theme_test_theme_prepare_theme_test_prepare__implemented__extended_alter
moduleElement1: Drupal\theme_test\ThemeTestController::prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleInjectedVariable1: theme_test_theme_prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleInjectedVariable2: theme_test_theme_prepare_theme_test_prepare_element
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
themeInjectedVariable1: test_theme_theme_prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleInjectedVariable3: theme_test_theme_prepare_theme_test_prepare_element_alter
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleElementSuggestion1: Drupal\theme_test\ThemeTestController::prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleInjectedVariable1: theme_test_theme_prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleInjectedVariable2: theme_test_theme_prepare_theme_test_prepare_element
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
themeInjectedVariable1: test_theme_theme_prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleInjectedVariable3: theme_test_theme_prepare_theme_test_prepare_element_alter
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleElementSuggestion2: Drupal\theme_test\ThemeTestController::prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleInjectedVariable1: theme_test_theme_prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleInjectedVariable2: theme_test_theme_prepare_theme_test_prepare_element
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
themeInjectedVariable1: test_theme_theme_prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleInjectedVariable3: theme_test_theme_prepare_theme_test_prepare_element_alter
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleElementSuggestion3: Drupal\theme_test\ThemeTestController::prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleInjectedVariable1: theme_test_theme_prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleInjectedVariable2: theme_test_theme_prepare_theme_test_prepare_element
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
themeInjectedVariable1: test_theme_theme_prepare
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
moduleInjectedVariable3: theme_test_theme_prepare_theme_test_prepare_element_alter
+test_theme_theme_prepare
+test_theme_theme_prepare_theme_test_prepare
+theme_test_theme_prepare_alter
+test_theme_theme_prepare_alter
$title: $value
"; +} + +/** + * Theme function for testing rendering of theme_test_prepare_element(). + */ +function theme_theme_test_prepare_element($variables) { + return drupal_render($variables['element']); +} + +/** * Implements hook_theme_suggestions_HOOK(). */ function theme_test_theme_suggestions_theme_test_suggestion_provided(array $variables) { return array('theme_test_suggestion_provided__' . 'foo'); } + +/** + * Implements hook_theme_prepare(). + */ +function theme_test_theme_prepare(&$variables, $hook) { + // Only prepare variables for a specific base theme hook. + if ($hook === 'theme_test_prepare_element') { + $variables['element']['moduleInjectedVariable1'] = array( + '#theme' => 'theme_test_prepare__element', + '#title' => 'moduleInjectedVariable1', + '#value' => __FUNCTION__, + ); + } +} + +/** + * Implements hook_theme_prepare_alter(). + */ +function theme_test_theme_prepare_alter(&$variables, $hook) { + if ($hook === 'theme_test_prepare') { + $variables['value'] .= "