diff --git a/core/includes/theme.inc b/core/includes/theme.inc index e8cff8b..322b882 100644 --- a/core/includes/theme.inc +++ b/core/includes/theme.inc @@ -727,7 +727,8 @@ function template_preprocess_links(&$variables) { * to an empty string, but can be set to NULL for the attribute to be * omitted. Usually, neither omission nor an empty string satisfies * accessibility requirements, so it is strongly encouraged for code - * calling _theme('image') to pass a meaningful value for this variable. + * building variables for image.html.twig templates to pass a meaningful + * value for this variable. * - http://www.w3.org/TR/REC-html40/struct/objects.html#h-13.8 * - http://www.w3.org/TR/xhtml1/dtds.html * - http://dev.w3.org/html5/spec/Overview.html#alt @@ -1721,11 +1722,12 @@ function drupal_common_theme() { 'image' => array( // HTML 4 and XHTML 1.0 always require an alt attribute. The HTML 5 draft // allows the alt attribute to be omitted in some cases. Therefore, - // default the alt attribute to an empty string, but allow code calling - // _theme('image') to pass explicit NULL for it to be omitted. Usually, - // neither omission nor an empty string satisfies accessibility - // requirements, so it is strongly encouraged for code calling - // _theme('image') to pass a meaningful value for the alt variable. + // default the alt attribute to an empty string, but allow code providing + // variables to image.html.twig templates to pass explicit NULL for it to + // be omitted. Usually, neither omission nor an empty string satisfies + // accessibility requirements, so it is strongly encouraged for code + // building variables for image.html.twig templates to pass a meaningful + // value for the alt variable. // - http://www.w3.org/TR/REC-html40/struct/objects.html#h-13.8 // - http://www.w3.org/TR/xhtml1/dtds.html // - http://dev.w3.org/html5/spec/Overview.html#alt diff --git a/core/lib/Drupal/Core/Render/theme.api.php b/core/lib/Drupal/Core/Render/theme.api.php index aff8ab5..471c055 100644 --- a/core/lib/Drupal/Core/Render/theme.api.php +++ b/core/lib/Drupal/Core/Render/theme.api.php @@ -37,16 +37,16 @@ * http://twig.sensiolabs.org/doc/templates.html * * @section sec_theme_hooks Theme Hooks - * The theme system is invoked in drupal_render() by calling the internal - * _theme() function, which operates on the concept of "theme hooks". Theme - * hooks define how a particular type of data should be rendered. They are - * registered by modules by implementing hook_theme(), which specifies the name - * of the hook, the input "variables" used to provide data and options, and - * other information. Modules implementing hook_theme() also need to provide a - * default implementation for each of their theme hooks, normally in a Twig - * file, and they may also provide preprocessing functions. For example, the - * core Search module defines a theme hook for a search result item in - * search_theme(): + * The theme system is invoked in \Drupal\Core\Render\Renderer::doRender() by + * calling the \Drupal\Core\Theme\ThemeManagerInterface::render() function, + * which operates on the concept of "theme hooks". Theme hooks define how a + * particular type of data should be rendered. They are registered by modules by + * implementing hook_theme(), which specifies the name of the hook, the input + * "variables" used to provide data and options, and other information. Modules + * implementing hook_theme() also need to provide a default implementation for + * each of their theme hooks, normally in a Twig file, and they may also provide + * preprocessing functions. For example, the core Search module defines a theme + * hook for a search result item in search_theme(): * @code * return array( * 'search_result' => array( @@ -511,7 +511,8 @@ function hook_form_system_theme_settings_alter(&$form, \Drupal\Core\Form\FormSta * preprocess variables for a specific theme hook, whether implemented as a * template or function. * - * For more detailed information, see _theme(). + * For more detailed information, see + * @link themeable Theme system overview topic @endlink. * * @param $variables * The variables array (modify in place). @@ -559,7 +560,8 @@ function hook_preprocess(&$variables, $hook) { * hook. It should only be used if a module needs to override or add to the * theme preprocessing for a theme hook it didn't define. * - * For more detailed information, see _theme(). + * For more detailed information, see + * @link themeable Theme system overview topic @endlink. * * @param $variables * The variables array (modify in place). diff --git a/core/lib/Drupal/Core/Theme/Registry.php b/core/lib/Drupal/Core/Theme/Registry.php index 0167a74..e2a89a9 100644 --- a/core/lib/Drupal/Core/Theme/Registry.php +++ b/core/lib/Drupal/Core/Theme/Registry.php @@ -47,12 +47,12 @@ class Registry implements DestructableInterface { * - name: The name of the extension the original theme hook originates * from; e.g., 'node' for theme hook 'node' of Node module. * - theme path: The effective \Drupal\Core\Theme\ActiveTheme::getPath() - * during _theme(), available as - * 'directory' variable in templates. For functions, it should point to - * the respective theme.For templates, it should point to the directory - * that contains the template. + * during \Drupal\Core\Theme\ThemeManagerInterface::render(), available + * as 'directory' variable in templates. For functions, it should point + * to the respective theme. For templates, it should point to the + * directory that contains the template. * - includes: (optional) An array of include files to load when the theme - * hook is executed by _theme(). + * hook is executed by \Drupal\Core\Theme\ThemeManagerInterface::render(). * - file: (optional) A filename to add to 'includes', either prefixed with * the value of 'path', or the path of the extension implementing * hook_theme(). @@ -389,7 +389,8 @@ protected function build() { * in hook_theme(). If there is more than one implementation and * 'render element' is not specified in a later one, then the previous * definition is kept. - * - 'preprocess functions': See _theme() for detailed documentation. + * - See the @link themeable Theme system overview topic @endlink for + * detailed documentation. * @param string $name * The name of the module, theme engine, base theme engine, theme or base * theme implementing hook_theme(). @@ -530,7 +531,8 @@ protected function processExtension(array &$cache, $name, $type, $theme, $path) } foreach ($prefixes as $prefix) { // Only use non-hook-specific variable preprocessors for theming - // hooks implemented as templates. See _theme(). + // hooks implemented as templates. See the @defgroup themeable + // topic. if (isset($info['template']) && function_exists($prefix . '_preprocess')) { $info['preprocess functions'][] = $prefix . '_preprocess'; } @@ -566,7 +568,7 @@ protected function processExtension(array &$cache, $name, $type, $theme, $path) $cache[$hook]['preprocess functions'] = array(); } // Only use non-hook-specific variable preprocessors for theme hooks - // implemented as templates. See _theme(). + // implemented as templates. See the @defgroup themeable topic. if (isset($info['template']) && function_exists($name . '_preprocess')) { $cache[$hook]['preprocess functions'][] = $name . '_preprocess'; } diff --git a/core/lib/Drupal/Core/Theme/ThemeManager.php b/core/lib/Drupal/Core/Theme/ThemeManager.php index 7e0e0b4..d4c6a2c 100644 --- a/core/lib/Drupal/Core/Theme/ThemeManager.php +++ b/core/lib/Drupal/Core/Theme/ThemeManager.php @@ -138,11 +138,11 @@ public function render($hook, array $variables) { $active_theme = $this->getActiveTheme(); - // If called before all modules are loaded, we do not necessarily have a full - // theme registry to work with, and therefore cannot process the theme + // If called before all modules are loaded, we do not necessarily have a + // full theme registry to work with, and therefore cannot process the theme // request properly. See also \Drupal\Core\Theme\Registry::get(). if (!$this->moduleHandler->isLoaded() && !defined('MAINTENANCE_MODE')) { - throw new \Exception(t('_theme() may not be called until all modules are loaded.')); + throw new \Exception('The theme implementations may not be rendered until all modules are loaded.'); } $theme_registry = $this->themeRegistry->getRuntime(); @@ -180,9 +180,10 @@ public function render($hook, array $variables) { \Drupal::logger('theme')->warning('Theme hook %hook not found.', array('%hook' => $hook)); } // There is no theme implementation for the hook passed. Return FALSE so - // the function calling _theme() can differentiate between a hook that - // exists and renders an empty string and a hook that is not - // implemented. + // the function calling + // \Drupal\Core\Theme\ThemeManagerInterface::render() can differentiate + // between a hook that exists and renders an empty string, and a hook + // that is not implemented. return FALSE; } } @@ -233,8 +234,8 @@ public function render($hook, array $variables) { // Invoke hook_theme_suggestions_HOOK(). $suggestions = $this->moduleHandler->invokeAll('theme_suggestions_' . $base_theme_hook, array($variables)); - // If _theme() was invoked with a direct theme suggestion like - // '#theme' => 'node__article', add it to the suggestions array before + // If the theme implementation was invoked with a direct theme suggestion + // like '#theme' => 'node__article', add it to the suggestions array before // invoking suggestion alter hooks. if (isset($info['base hook'])) { $suggestions[] = $hook; @@ -250,10 +251,10 @@ public function render($hook, array $variables) { $this->alter($hooks, $suggestions, $variables, $base_theme_hook); // Check if each suggestion exists in the theme registry, and if so, - // use it instead of the hook that _theme() was called with. For example, a - // function may call _theme('node', ...), but a module can add - // 'node__article' as a suggestion via hook_theme_suggestions_HOOK_alter(), - // enabling a theme to have an alternate template file for article nodes. + // use it instead of the base hook. For example, a function may use + // '#theme' => 'node', but a module can add 'node__article' as a suggestion + // via hook_theme_suggestions_HOOK_alter(), enabling a theme to have + // an alternate template file for article nodes. foreach (array_reverse($suggestions) as $suggestion) { if ($theme_registry->has($suggestion)) { $info = $theme_registry->get($suggestion); diff --git a/core/lib/Drupal/Core/Utility/ThemeRegistry.php b/core/lib/Drupal/Core/Utility/ThemeRegistry.php index c5e6055..1a3336e 100644 --- a/core/lib/Drupal/Core/Utility/ThemeRegistry.php +++ b/core/lib/Drupal/Core/Utility/ThemeRegistry.php @@ -24,15 +24,6 @@ class ThemeRegistry extends CacheCollector implements DestructableInterface { /** - * Whether the partial registry can be persisted to the cache. - * - * This is only allowed if all modules and the request method is GET. _theme() - * should be very rarely called on POST requests and this avoids polluting - * the runtime cache. - */ - protected $persistable; - - /** * The complete theme registry array. */ protected $completeRegistry; diff --git a/core/modules/image/image.module b/core/modules/image/image.module index 2c222f8..97b3dd2 100644 --- a/core/modules/image/image.module +++ b/core/modules/image/image.module @@ -96,11 +96,11 @@ function image_theme() { 'image_style' => array( // HTML 4 and XHTML 1.0 always require an alt attribute. The HTML 5 draft // allows the alt attribute to be omitted in some cases. Therefore, - // default the alt attribute to an empty string, but allow code calling - // _theme('image_style') to pass explicit NULL for it to be omitted. + // default the alt attribute to an empty string, but allow code using + // '#theme' => 'image_style' to pass explicit NULL for it to be omitted. // Usually, neither omission nor an empty string satisfies accessibility - // requirements, so it is strongly encouraged for code calling - // _theme('image_style') to pass a meaningful value for the alt variable. + // requirements, so it is strongly encouraged for code using '#theme' => + // 'image_style' to pass a meaningful value for the alt variable. // - http://www.w3.org/TR/REC-html40/struct/objects.html#h-13.8 // - http://www.w3.org/TR/xhtml1/dtds.html // - http://dev.w3.org/html5/spec/Overview.html#alt @@ -260,8 +260,8 @@ function image_style_options($include_empty = TRUE) { * attribute to be omitted in some cases. Therefore, this variable defaults * to an empty string, but can be set to NULL for the attribute to be * omitted. Usually, neither omission nor an empty string satisfies - * accessibility requirements, so it is strongly encouraged for code calling - * _theme('image_style') to pass a meaningful value for this variable. + * accessibility requirements, so it is strongly encouraged for code using + * '#theme' => 'image_style' to pass a meaningful value for this variable. * - http://www.w3.org/TR/REC-html40/struct/objects.html#h-13.8 * - http://www.w3.org/TR/xhtml1/dtds.html * - http://dev.w3.org/html5/spec/Overview.html#alt diff --git a/core/modules/simpletest/src/KernelTestBase.php b/core/modules/simpletest/src/KernelTestBase.php index 56c800e..6210396 100644 --- a/core/modules/simpletest/src/KernelTestBase.php +++ b/core/modules/simpletest/src/KernelTestBase.php @@ -518,7 +518,8 @@ protected function enableModules(array $modules) { $module_filenames = $module_handler->getModuleList(); $this->kernel->updateModules($module_filenames, $module_filenames); - // Ensure isLoaded() is TRUE in order to make _theme() work. + // Ensure isLoaded() is TRUE in order to make + // \Drupal\Core\Theme\ThemeManagerInterface::render() work. // Note that the kernel has rebuilt the container; this $module_handler is // no longer the $module_handler instance from above. $this->container->get('module_handler')->reload(); @@ -551,7 +552,8 @@ protected function disableModules(array $modules) { // Update the kernel to remove their services. $this->kernel->updateModules($module_filenames, $module_filenames); - // Ensure isLoaded() is TRUE in order to make _theme() work. + // Ensure isLoaded() is TRUE in order to make + // \Drupal\Core\Theme\ThemeManagerInterface::render() work. // Note that the kernel has rebuilt the container; this $module_handler is // no longer the $module_handler instance from above. $module_handler = $this->container->get('module_handler'); diff --git a/core/modules/simpletest/src/Tests/KernelTestBaseTest.php b/core/modules/simpletest/src/Tests/KernelTestBaseTest.php index ae3742e..2187ccc 100644 --- a/core/modules/simpletest/src/Tests/KernelTestBaseTest.php +++ b/core/modules/simpletest/src/Tests/KernelTestBaseTest.php @@ -290,7 +290,7 @@ function testEnableModulesFixedList() { } /** - * Tests that _theme() works right after loading a module. + * Tests that ThemeManager works right after loading a module. */ function testEnableModulesTheme() { /** @var \Drupal\Core\Render\RendererInterface $renderer */ @@ -301,7 +301,8 @@ function testEnableModulesTheme() { '#attributes' => array(), ); $this->enableModules(array('system')); - // _theme() throws an exception if modules are not loaded yet. + // \Drupal\Core\Theme\ThemeManager::render() throws an exception if modules + // are not loaded yet. $this->assertTrue($renderer->renderRoot($element)); $element = $original_element; diff --git a/core/modules/system/src/Tests/Theme/ThemeTest.php b/core/modules/system/src/Tests/Theme/ThemeTest.php index 28d47386..a84ef8f 100644 --- a/core/modules/system/src/Tests/Theme/ThemeTest.php +++ b/core/modules/system/src/Tests/Theme/ThemeTest.php @@ -40,7 +40,7 @@ protected function setUp() { * Render arrays that use a render element and templates (and hence call * template_preprocess()) must ensure the attributes at different occasions * are all merged correctly: - * - $variables['attributes'] as passed in to _theme() + * - $variables['attributes'] as passed in to the theme hook implementation. * - the render element's #attributes * - any attributes set in the template's preprocessing function */ @@ -57,7 +57,7 @@ function testAttributeMerging() { } /** - * Test that _theme() returns expected data types. + * Test that ThemeManager renders the expected data types. */ function testThemeDataTypes() { // theme_test_false is an implemented theme hook so \Drupal::theme() service diff --git a/core/modules/system/tests/modules/theme_test/theme_test.module b/core/modules/system/tests/modules/theme_test/theme_test.module index 8a8841e..f64da1e 100644 --- a/core/modules/system/tests/modules/theme_test/theme_test.module +++ b/core/modules/system/tests/modules/theme_test/theme_test.module @@ -88,14 +88,14 @@ function template_preprocess_theme_test_function_suggestions(&$variables) { } /** - * Theme function for testing _theme('theme_test_foo'). + * Theme function for hook theme_test_foo. */ function theme_theme_test_foo($variables) { return $variables['foo']; } /** - * Theme function for testing _theme('theme_test_function_template_override'). + * Theme function for hook theme_test_function_template_override. */ function theme_theme_test_function_template_override($variables) { return 'theme_test_function_template_override test failed.'; @@ -140,7 +140,8 @@ function template_preprocess_theme_test_render_element(&$variables) { * * Theme hooks defining a 'render element' add an internal '#render_children' * property. When this property is found, drupal_render() avoids calling - * _theme() on the top-level element to prevent infinite recursion. + * the 'theme.manager' service 'render' method on the top-level element to + * prevent infinite recursion. * * @param array $variables * An associative array containing: diff --git a/core/modules/update/src/Form/UpdateManagerUpdate.php b/core/modules/update/src/Form/UpdateManagerUpdate.php index cafa4d1..80cc830 100644 --- a/core/modules/update/src/Form/UpdateManagerUpdate.php +++ b/core/modules/update/src/Form/UpdateManagerUpdate.php @@ -197,9 +197,9 @@ public function buildForm(array $form, FormStateInterface $form_state) { if ($needs_manual) { // There are no checkboxes in the 'Manual updates' table so it will be - // rendered by _theme('table'), not _theme('tableselect'). Since the data - // formats are incompatible, we convert now to the format expected by - // _theme('table'). + // rendered by '#theme' => 'table', not '#theme' => 'tableselect'. Since + // the data formats are incompatible, we convert now to the format + // expected by '#theme' => 'table'. unset($entry['#weight']); $attributes = $entry['#attributes']; unset($entry['#attributes']); diff --git a/core/tests/Drupal/KernelTests/KernelTestBase.php b/core/tests/Drupal/KernelTests/KernelTestBase.php index fd7b864..c2d8a56 100644 --- a/core/tests/Drupal/KernelTests/KernelTestBase.php +++ b/core/tests/Drupal/KernelTests/KernelTestBase.php @@ -882,7 +882,8 @@ protected function disableModules(array $modules) { // Update the kernel to remove their services. $this->container->get('kernel')->updateModules($module_filenames, $module_filenames); - // Ensure isLoaded() is TRUE in order to make _theme() work. + // Ensure isLoaded() is TRUE in order to make + // \Drupal\Core\Theme\ThemeManagerInterface::render() work. // Note that the kernel has rebuilt the container; this $module_handler is // no longer the $module_handler instance from above. $module_handler = $this->container->get('module_handler'); diff --git a/core/themes/engines/twig/twig.engine b/core/themes/engines/twig/twig.engine index 30ec511..b66fe58 100644 --- a/core/themes/engines/twig/twig.engine +++ b/core/themes/engines/twig/twig.engine @@ -37,7 +37,7 @@ function twig_init(Extension $theme) { * * Renders a Twig template. * - * If the Twig debug setting is enabled, HTML comments including _theme() call + * If the Twig debug setting is enabled, HTML comments including the theme hook * and template file name suggestions will surround the template markup. * * @param string $template_file