theme() doc block sums up this issue nicely:
/** * Generates themed output. * * All requests for themed output must go through this function (however, * calling the theme() function directly is strongly discouraged - see next * paragraph). It examines the request and routes it to the appropriate * @link themeable theme function or template @endlink, by checking the theme * registry. * * Avoid calling this function directly. It is preferable to replace direct * calls to the theme() function with calls to drupal_render() by passing a * render array with a #theme key to drupal_render(), which in turn calls * theme(). *...
In order to really drive home this dissuasion, we should mark the function as being "private" with an underscore.
theme() function directly raises several issues:
- Circumvents caching.
- Circumvents defaults of types defined in
hook_element_info(), including attached assets
- Circumvents the
theme() should only be invoked as part of the
drupal_render process in order to convert data structures into output.
This issue has become clear as we have progressively hidden asset-adding functions like
_theme() explicitly a private Drupal function, we will also reduce confusion for module developers. This is something that until only recently was still fuzzy for me -- Do I use
theme()with an underscore to mark it as private:
- Write a very detailed Change Record that details why
theme()should not be called directly. Draft at https://drupal.org/node/2195739
- Update documentation to provide best-practice approaches to building data structures, attaching assets and ushering them efficiently into the
User interface changes
theme() function will be removed from the public API.
Original report by @jessebeach
PASSED: [[SimpleTest]]: [MySQL] 64,363 pass(es). View
PASSED: [[SimpleTest]]: [MySQL] 64,454 pass(es). View